github.com/nathanielks/terraform@v0.6.1-0.20170509030759-13e1a62319dc/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  Terraform providers and provisioners are provided via plugins. Each plugin
    23  exposes an implementation for a specific service, such as AWS, or provisioner,
    24  such as bash. Plugins are executed as a separate process and communicate with
    25  the main Terraform binary over an RPC interface.
    26  
    27  More details are available in
    28  [Internal Docs](/docs/internals/internal-plugins.html).
    29  
    30  The code within the binaries must adhere to certain interfaces.
    31  The network communication and RPC is handled automatically by higher-level
    32  Terraform libraries. The exact interface to implement is documented
    33  in its respective documentation section.
    34  
    35  ## Installing a Plugin
    36  
    37  To install a plugin, put the binary somewhere on your filesystem, then
    38  configure Terraform to be able to find it. The configuration where plugins
    39  are defined is `~/.terraformrc` for Unix-like systems and
    40  `%APPDATA%/terraform.rc` for Windows.
    41  
    42  An example that configures a new provider is shown below:
    43  
    44  ```hcl
    45  providers {
    46    privatecloud = "/path/to/privatecloud"
    47  }
    48  ```
    49  
    50  The key `privatecloud` is the _prefix_ of the resources for that provider.
    51  For example, if there is `privatecloud_instance` resource, then the above
    52  configuration would work. The value is the name of the executable. This
    53  can be a full path. If it isn't a full path, the executable will be looked
    54  up on the `PATH`.
    55  
    56  ## Developing a Plugin
    57  
    58  Developing a plugin is simple. The only knowledge necessary to write
    59  a plugin is basic command-line skills and basic knowledge of the
    60  [Go programming language](http://golang.org).
    61  
    62  -> **Note:** A common pitfall is not properly setting up a
    63  <code>$GOPATH</code>. This can lead to strange errors. You can read more about
    64  this [here](https://golang.org/doc/code.html) to familiarize
    65  yourself.
    66  
    67  Create a new Go project somewhere in your `$GOPATH`. If you're a
    68  GitHub user, we recommend creating the project in the directory
    69  `$GOPATH/src/github.com/USERNAME/terraform-NAME`, where `USERNAME`
    70  is your GitHub username and `NAME` is the name of the plugin you're
    71  developing. This structure is what Go expects and simplifies things down
    72  the road.
    73  
    74  With the directory made, create a `main.go` file. This project will
    75  be a binary so the package is "main":
    76  
    77  ```golang
    78  package main
    79  
    80  import (
    81  	"github.com/hashicorp/terraform/plugin"
    82  )
    83  
    84  func main() {
    85  	plugin.Serve(new(MyPlugin))
    86  }
    87  ```
    88  
    89  And that's basically it! You'll have to change the argument given to
    90  `plugin.Serve` to be your actual plugin, but that is the only change
    91  you'll have to make. The argument should be a structure implementing
    92  one of the plugin interfaces (depending on what sort of plugin
    93  you're creating).
    94  
    95  Terraform plugins must follow a very specific naming convention of
    96  `terraform-TYPE-NAME`. For example, `terraform-provider-aws`, which
    97  tells Terraform that the plugin is a provider that can be referenced
    98  as "aws".