github.com/maheshbr/terraform@v0.3.1-0.20141020033300-deec7194a3ea/website/source/docs/plugins/basics.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Plugin Basics"
     4  sidebar_current: "docs-plugins-basics"
     5  ---
     6  
     7  # Plugin Basics
     8  
     9  This page documents the basics of how the plugin system in Terraform
    10  works, and how to setup a basic development environment for plugin development
    11  if you're writing a Terraform plugin.
    12  
    13  <div class="alert alert-block alert-warning">
    14  <strong>Advanced topic!</strong> Plugin development is a highly advanced
    15  topic in Terraform, and is not required knowledge for day-to-day usage.
    16  If you don't plan on writing any plugins, we recommend not reading
    17  this section of the documentation.
    18  </div>
    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  <div class="alert alert-block alert-info">
    72  <strong>Note:</strong> A common pitfall is not properly setting up a
    73  <code>$GOPATH</code>. This can lead to strange errors. You can read more about
    74  this <a href="https://golang.org/doc/code.html">here</a> to familiarize
    75  yourself.
    76  </div>
    77  
    78  Create a new Go project somewhere in your `$GOPATH`. If you're a
    79  GitHub user, we recommend creating the project in the directory
    80  `$GOPATH/src/github.com/USERNAME/terraform-NAME`, where `USERNAME`
    81  is your GitHub username and `NAME` is the name of the plugin you're
    82  developing. This structure is what Go expects and simplifies things down
    83  the road.
    84  
    85  With the directory made, create a `main.go` file. This project will
    86  be a binary so the package is "main":
    87  
    88  ```
    89  package main
    90  
    91  import (
    92  	"github.com/hashicorp/terraform/plugin"
    93  )
    94  
    95  func main() {
    96  	plugin.Serve(new(MyPlugin))
    97  }
    98  ```
    99  
   100  And that's basically it! You'll have to change the argument given to
   101  `plugin.Serve` to be your actual plugin, but that is the only change
   102  you'll have to make. The argument should be a structure implementing
   103  one of the plugin interfaces (depending on what sort of plugin
   104  you're creating).
   105  
   106  While its not strictly necessary, Terraform plugins follow specific
   107  naming conventions. The format of the plugin binaries are
   108  `terraform-TYPE-NAME`. For example, `terraform-provider-aws`.
   109  We recommend you follow this convention to help make it clear what
   110  your plugin does to users.