Skip to content

Commit

Permalink
Clarified local provider usage (#8702)
Browse files Browse the repository at this point in the history
Simplified instructions for the common use case of using a prebuilt terraform binary with a local provider binary
  • Loading branch information
melinath authored Mar 17, 2021
1 parent 307fac5 commit 0c3db9b
Showing 1 changed file with 16 additions and 24 deletions.
40 changes: 16 additions & 24 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,39 +75,31 @@ resource.TestStep{

## Instructing terraform to use a local copy of the provider

There are three different consumption strategies you can utilize

* Using a local version of terraform

1. If you are building Terraform from source with a Google provider built from source, Terraform will automatically use the
local `terraform-provider-google` and `terraform-provider-google-beta` plugins in `$GOPATH/bin`.

* Using a release version of terraform

Note that these instructions apply to `0.13+`. For prior Terraform versions, look at past versions of this page for instructions.

Before using a local provider version, you'll need to set up [0.13+'s expected directory structure](https://www.terraform.io/upgrade-guides/0-13.html#new-filesystem-layout-for-local-copies-of-providers).
### Using released terraform binary with local provider binary

You can set up the directories required with the following commands. You should substitute your system's architecture or a different path if desired:

```
Setup:
```bash
mkdir -p ~/.terraform.d/plugins/registry.terraform.io/hashicorp/google/5.0.0/darwin_amd64
mkdir -p ~/.terraform.d/plugins/registry.terraform.io/hashicorp/google-beta/5.0.0/darwin_amd64
ln -s $GOPATH/bin/terraform-provider-google ~/.terraform.d/plugins/registry.terraform.io/hashicorp/google/5.0.0/darwin_amd64/terraform-provider-google_v5.0.0
ln -s $GOPATH/bin/terraform-provider-google-beta ~/.terraform.d/plugins/registry.terraform.io/hashicorp/google-beta/5.0.0/darwin_amd64/terraform-provider-google-beta_v5.0.0
```

Once this setup is complete, terraform will automatically use the binaries generated by the `make build` commands in the `terraform-provider-google` and `terraform-provider-google-beta` repositories instead of downloading the latest versions. To undo this, you can run:

```bash
rm -rf ~/.terraform.d/plugins/registry.terraform.io/hashicorp/
```

For more information, check out Hashicorp's documentation on the [0.13+ filesystem layout](https://www.terraform.io/upgrade-guides/0-13.html#new-filesystem-layout-for-local-copies-of-providers).

If multiple versions are available in a plugin directory (for example after `terraform providers mirror` is used), Terraform will pick the most up-to-date provider version within version constraints. As such, we recommend using a version that is several major versions ahead for your local copy of the provider, such as `5.0.0`.

2. When you run `terraform init` supply the local binary registry location using the [-plugin-dir](https://www.terraform.io/docs/commands/init.html#plugin-dir-path) parameter. ie `terraform init -plugin-dir=$GOPATH/.terraform` with the provider located at`$GOPATH/.terraform/registry.terraform.io/hashicorp/google/5.0.0/darwin_amd64/terraform-provider-google_v5.0.0`
* note: terraform will not download additional providers remotely. All requested providers should be in the -plugin-dir
* note: each time you rebuild the binary you will have to rerun `terraform init -plugin-dir=<your-binary-registry-location>` as the hash is invalidated.
3. Use the [provider discovery directory](https://www.terraform.io/docs/extend/how-terraform-works.html#discovery) at `~/.terraform.d/plugins`. Terraform will attempt to use the provider binaries here.
* note: if a provider is managed in the discovery directory, Terraform will not pull it from the registry. `terraform providers mirror ~/.terraform.d/plugins` will mirror any versions required by the current config into the discovery directory from the registry.
* note: you can either copy the provider binary to this location or do a symlink to the build output
```bash
# this symlink keeps the fake 5.0.0 version up-to-date with `make build`'s output automatically
ln -s $GOPATH/bin/terraform-provider-google ~/.terraform.d/plugins/registry.terraform.io/hashicorp/google/5.0.0/darwin_amd64/terraform-provider-google_v5.0.0
ln -s $GOPATH/bin/terraform-provider-google-beta ~/.terraform.d/plugins/registry.terraform.io/hashicorp/google-beta/5.0.0/darwin_amd64/terraform-provider-google-beta_v5.0.0
```
### Building terraform binary from source

If you build the terraform binary from source, it will automatically use the binaries generated by the `make build` commands in the `terraform-provider-google` and `terraform-provider-google-beta` repositories instead of downloading the latest versions.

### FAQ

Expand Down

0 comments on commit 0c3db9b

Please sign in to comment.