resilien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

documentation: explain provider dev environment setup 

The intent here is just to introduce some initial docs on our recommended
way to develop plugins in the same GOPATH as Terraform itself. The
documentation in this area needs some more fundamental rework as it is
rather outdated and mis-organized, but that's outside the scope of what
this change is trying to achieve.
This commit is contained in:
Martin Atkins 2017-07-18 14:00:32 -07:00
parent eb02467298
commit c57dbebe84
2 changed files with 56 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@ -31,9 +31,10 @@ Developing Terraform
If you wish to work on Terraform itself or any of its built-in providers, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.8+ is *required*). Alternatively, you can use the Vagrantfile in the root of this repo to stand up a virtual machine with the appropriate dev tooling already set up for you.
Note that as of Terraform 0.10, most providers are no longer built in, and instead are located in their own repositories in the [terraform-providers](https://github.com/terraform-providers) organization on GitHub. Instructions for developing each provider are in the associated README file.
This repository contains only Terraform core, which includes the command line interface and the main graph engine. Providers are implemented as plugins that each have their own repository in [the `terraform-providers` organization](https://github.com/terraform-providers) on GitHub. Instructions for developing each provider are in the associated README file. For more information, see [the provider development overview](https://www.terraform.io/docs/plugins/provider.html).
For local dev first make sure Go is properly installed, including setting up a [GOPATH](http://golang.org/doc/code.html#GOPATH). You will also need to add `$GOPATH/bin` to your `$PATH`.
For local development of Terraform core, first make sure Go is properly installed and that a
[GOPATH](http://golang.org/doc/code.html#GOPATH) has been set. You will also need to add `$GOPATH/bin` to your `$PATH`.
Next, using [Git](https://git-scm.com/), clone this repository into `$GOPATH/src/github.com/hashicorp/terraform`. All the necessary dependencies are either vendored or automatically installed, so you just need to type `make`. This will compile the code and then run the tests. If this exits with exit status 0, then everything is working!

53
website/docs/plugins/provider.html.md
View File

@ -32,6 +32,59 @@ of this page will assume you're familiar with
[plugin basics](/docs/plugins/basics.html) and that you already have
a basic development environment setup.
## Provider Plugin Codebases
Provider plugins live outside of the Terraform core codebase in their own
source code repositories. The official set of provider plugins released by
HashiCorp (developed by both HashiCorp staff and community contributors)
all live in repositories in
[the `terraform-providers` organization](https://github.com/terraform-providers)
on GitHub, but third-party plugins can be maintained in any source code
repository.
When developing a provider plugin, it is recommended to use a common `GOPATH`
that includes both the core Terraform repository and the repositories of any
providers being changed. This makes it easier to use a locally-built
`terraform` executable and a set of locally-built provider plugins together
without further configuration.
For example, to download both Terraform and the `template` provider into
`GOPATH`:
```
$ go get github.com/hashicorp/terraform
$ go get github.com/terraform-providers/terraform-provider-template
```
These two packages are both "main" packages that can be built into separate
executables with `go install`:
```
$ go install github.com/hashicorp/terraform
$ go install github.com/terraform-providers/terraform-provider-template
```
After running the above commands, both Terraform core and the `template`
provider will both be installed in the current `GOPATH` and `$GOPATH/bin`
will contain both `terraform` and `terraform-provider-template` executables.
This `terraform` executable will find and use the `template` provider plugin
alongside it in the `bin` directory in preference to downloading and installing
an official release.
When constructing a new provider from scratch, it's recommended to follow
a similar repository structure as for the existing providers, with the main
package in the repository root and a library package in a subdirectory named
after the provider. For more information, see
[the custom providers guide](/guides/writing-custom-terraform-providers.html).
When making changes only to files within the provider repository, it is _not_
necessary to re-build the main Terraform executable. Note that some packages
from the Terraform repository are used as library dependencies by providers,
such as `github.com/hashicorp/terraform/helper/schema`; it is recommended to
use `govendor` to create a local vendor copy of the relevant packages in the
provider repository, as can be seen in the repositories within the
`terraform-providers` GitHub organization.
## Low-Level Interface
The interface you must implement for providers is