github.com/hobbeswalsh/terraform@v0.3.7-0.20150619183303-ad17cf55a0fa/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  Terraform plugins must follow a very specific naming convention of
   105  `terraform-TYPE-NAME`. For example, `terraform-provider-aws`, which
   106  tells Terraform that the plugin is a provider that can be referenced
   107  as "aws".