github.com/arvindram03/terraform@v0.3.7-0.20150212015210-408f838db36d/website/source/docs/plugins/basics.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Plugin Basics"
     4  sidebar_current: "docs-plugins-basics"
     5  description: |-
     6    This page documents the basics of how the plugin system in Terraform works, and how to setup a basic development environment for plugin development if you're writing a Terraform plugin.
     7  ---
     8  
     9  # Plugin Basics
    10  
    11  This page documents the basics of how the plugin system in Terraform
    12  works, and how to setup a basic development environment for plugin development
    13  if you're writing a Terraform plugin.
    14  
    15  ~> **Advanced topic!** Plugin development is a highly advanced
    16  topic in Terraform, and is not required knowledge for day-to-day usage.
    17  If you don't plan on writing any plugins, we recommend not reading
    18  this section of the documentation.
    19  
    20  ## How it Works
    21  
    22  The plugin system for Terraform is based on multi-process RPC. Every
    23  provider, provisioner, etc. in Terraform is actually a separate compiled
    24  binary. You can see this when you download Terraform: the Terraform package
    25  contains multiple binaries.
    26  
    27  Terraform executes these binaries in a certain way and uses Unix domain
    28  sockets or network sockets to perform RPC with the plugins.
    29  
    30  If you try to execute a plugin directly, an error will be shown:
    31  
    32  ```
    33  $ terraform-provider-aws
    34  This binary is a Terraform plugin. These are not meant to be
    35  executed directly. Please execute `terraform`, which will load
    36  any plugins automatically.
    37  ```
    38  
    39  The code within the binaries must adhere to certain interfaces.
    40  The network communication and RPC is handled automatically by higher-level
    41  Terraform libraries. The exact interface to implement is documented
    42  in its respective documentation section.
    43  
    44  ## Installing a Plugin
    45  
    46  To install a plugin, put the binary somewhere on your filesystem, then
    47  configure Terraform to be able to find it. The configuration where plugins
    48  are defined is `~/.terraformrc` for Unix-like systems and
    49  `%APPDATA%/terraform.rc` for Windows.
    50  
    51  An example that configures a new provider is shown below:
    52  
    53  ```
    54  providers {
    55  	privatecloud = "/path/to/privatecloud"
    56  }
    57  ```
    58  
    59  The key `privatecloud` is the _prefix_ of the resources for that provider.
    60  For example, if there is `privatecloud_instance` resource, then the above
    61  configuration would work. The value is the name of the executable. This
    62  can be a full path. If it isn't a full path, the executable will be looked
    63  up on the `PATH`.
    64  
    65  ## Developing a Plugin
    66  
    67  Developing a plugin is simple. The only knowledge necessary to write
    68  a plugin is basic command-line skills and basic knowledge of the
    69  [Go programming language](http://golang.org).
    70  
    71  -> **Note:** A common pitfall is not properly setting up a
    72  <code>$GOPATH</code>. This can lead to strange errors. You can read more about
    73  this [here](https://golang.org/doc/code.html) to familiarize
    74  yourself.
    75  
    76  Create a new Go project somewhere in your `$GOPATH`. If you're a
    77  GitHub user, we recommend creating the project in the directory
    78  `$GOPATH/src/github.com/USERNAME/terraform-NAME`, where `USERNAME`
    79  is your GitHub username and `NAME` is the name of the plugin you're
    80  developing. This structure is what Go expects and simplifies things down
    81  the road.
    82  
    83  With the directory made, create a `main.go` file. This project will
    84  be a binary so the package is "main":
    85  
    86  ```
    87  package main
    88  
    89  import (
    90  	"github.com/hashicorp/terraform/plugin"
    91  )
    92  
    93  func main() {
    94  	plugin.Serve(new(MyPlugin))
    95  }
    96  ```
    97  
    98  And that's basically it! You'll have to change the argument given to
    99  `plugin.Serve` to be your actual plugin, but that is the only change
   100  you'll have to make. The argument should be a structure implementing
   101  one of the plugin interfaces (depending on what sort of plugin
   102  you're creating).
   103  
   104  While its not strictly necessary, Terraform plugins follow specific
   105  naming conventions. The format of the plugin binaries are
   106  `terraform-TYPE-NAME`. For example, `terraform-provider-aws`.
   107  We recommend you follow this convention to help make it clear what
   108  your plugin does to users.