github.com/pdecat/terraform@v0.11.9-beta1/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 Plugins
    38  
    39  The [provider plugins distributed by HashiCorp](/docs/providers/index.html) are
    40  automatically installed by `terraform init`. Third-party plugins (both
    41  providers and provisioners) can be manually installed into the user plugins
    42  directory, located at `<APPLICATION DATA>\terraform.d\plugins` on Windows and
    43  `~/.terraform.d/plugins` on other systems.
    44  
    45  For more information, see:
    46  
    47  - [Configuring Providers](/docs/configuration/providers.html)
    48  - [Configuring Providers: Third-party Plugins](/docs/configuration/providers.html#third-party-plugins)
    49  
    50  For developer-centric documentation, see:
    51  
    52  - [How Terraform Works: Plugin Discovery](/docs/extend/how-terraform-works.html#discovery)
    53  
    54  ## Developing a Plugin
    55  
    56  Developing a plugin is simple. The only knowledge necessary to write
    57  a plugin is basic command-line skills and basic knowledge of the
    58  [Go programming language](http://golang.org).
    59  
    60  -> **Note:** A common pitfall is not properly setting up a
    61  <code>$GOPATH</code>. This can lead to strange errors. You can read more about
    62  this [here](https://golang.org/doc/code.html) to familiarize
    63  yourself.
    64  
    65  Create a new Go project somewhere in your `$GOPATH`. If you're a
    66  GitHub user, we recommend creating the project in the directory
    67  `$GOPATH/src/github.com/USERNAME/terraform-NAME`, where `USERNAME`
    68  is your GitHub username and `NAME` is the name of the plugin you're
    69  developing. This structure is what Go expects and simplifies things down
    70  the road.
    71  
    72  The `NAME` should either begin with `provider-` or `provisioner-`,
    73  depending on what kind of plugin it will be. The repository name will,
    74  by default, be the name of the binary produced by `go install` for
    75  your plugin package.
    76  
    77  With the package directory made, create a `main.go` file. This project will
    78  be a binary so the package is "main":
    79  
    80  ```golang
    81  package main
    82  
    83  import (
    84  	"github.com/hashicorp/terraform/plugin"
    85  )
    86  
    87  func main() {
    88  	plugin.Serve(new(MyPlugin))
    89  }
    90  ```
    91  
    92  The name `MyPlugin` is a placeholder for the struct type that represents
    93  your plugin's implementation. This must implement either
    94  `terraform.ResourceProvider` or `terraform.ResourceProvisioner`, depending
    95  on the plugin type.
    96  
    97  To test your plugin, the easiest method is to copy your `terraform` binary
    98  to `$GOPATH/bin` and ensure that this copy is the one being used for testing.
    99  `terraform init` will search for plugins within the same directory as the
   100  `terraform` binary, and `$GOPATH/bin` is the directory into which `go install`
   101  will place the plugin executable.