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