github.com/jzbruno/terraform@v0.10.3-0.20180104230435-18975d727047/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  _[Plugin Internals](/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 distributed by a third party developer, place the binary
    40  (extracted from any containing zip file) in
    41  [the third-party plugins directory](/docs/configuration/providers.html#third-party-plugins).
    42  
    43  Provider plugin binaries are named with the prefix `terraform-provider-`,
    44  while provisioner plugins have the prefix `terraform-provisioner-`. Both
    45  are placed in the same directory.
    46  
    47  ## Developing a Plugin
    48  
    49  Developing a plugin is simple. The only knowledge necessary to write
    50  a plugin is basic command-line skills and basic knowledge of the
    51  [Go programming language](http://golang.org).
    52  
    53  -> **Note:** A common pitfall is not properly setting up a
    54  <code>$GOPATH</code>. This can lead to strange errors. You can read more about
    55  this [here](https://golang.org/doc/code.html) to familiarize
    56  yourself.
    57  
    58  Create a new Go project somewhere in your `$GOPATH`. If you're a
    59  GitHub user, we recommend creating the project in the directory
    60  `$GOPATH/src/github.com/USERNAME/terraform-NAME`, where `USERNAME`
    61  is your GitHub username and `NAME` is the name of the plugin you're
    62  developing. This structure is what Go expects and simplifies things down
    63  the road.
    64  
    65  The `NAME` should either begin with `provider-` or `provisioner-`,
    66  depending on what kind of plugin it will be. The repository name will,
    67  by default, be the name of the binary produced by `go install` for
    68  your plugin package.
    69  
    70  With the package directory made, create a `main.go` file. This project will
    71  be a binary so the package is "main":
    72  
    73  ```golang
    74  package main
    75  
    76  import (
    77  	"github.com/hashicorp/terraform/plugin"
    78  )
    79  
    80  func main() {
    81  	plugin.Serve(new(MyPlugin))
    82  }
    83  ```
    84  
    85  The name `MyPlugin` is a placeholder for the struct type that represents
    86  your plugin's implementation. This must implement either
    87  `terraform.ResourceProvider` or `terraform.ResourceProvisioner`, depending
    88  on the plugin type.
    89  
    90  To test your plugin, the easiest method is to copy your `terraform` binary
    91  to `$GOPATH/bin` and ensure that this copy is the one being used for testing.
    92  `terraform init` will search for plugins within the same directory as the
    93  `terraform` binary, and `$GOPATH/bin` is the directory into which `go install`
    94  will place the plugin executable.