Replacing a Terraform Provider with a Locally Compiled Version

Terraform uses providers to allow for the management of various types of infrastructure. These providers are downloaded to the machine that executes Terraform as a binary. Sometimes, you may need to replace an existing provider binary with a version you have compiled. This can be useful for testing changes to a provider or using a version not yet available through the Terraform Registry. Here’s a step-by-step guide on using a locally compiled version of a Terraform provider after a binary has been compiled for the appropriate platform.

1. Delete the Terraform Lock File (if it exists)

Before making any changes to your provider, you must remove Terraform’s lock file, if it exists, usually named .terraform.lock.hcl, in your project directory where you typically use Terraform. This file contains hashes of the existing provider binaries, which will clash with your custom binary’s hash. Either use your file system’s delete function or the command:

rm .terraform.lock.hcl

2. Create or Edit .terraform.rc File

Next, you need to either create or edit a file named .terraform.rc in your home directory. Add the following configuration to the file:

provider_installation {
  dev_overrides {
    "registry.terraform.io/rancher/rke" = "/Users/wjdj/terraform-provider-custom"
  }
  direct {}
}

This configuration tells Terraform to use the provider binary at the specified path instead of the one from the Terraform Registry. The direct {} block tells Terraform to use the provider from the Terraform Registry if it’s not available locally. Any other providers not specified in dev_overrides will still be downloaded from the Terraform Registry.

Make sure to replace the provider identifier, in this example, registry.terraform.io/rancher/rke, and the path to it, in this example, /Users/wjdj/terraform-provider-custom, with the provider identifier and path to the binary for your use case.

3. Set Environment Variable for Terraform Configuration

Set the TF_CLI_CONFIG_FILE environment variable to point to your .terraform.rc file. This directs Terraform to use your custom configuration. Use the following command to set this variable:

export TF_CLI_CONFIG_FILE=~/.terraform.rc

4. Run Terraform

Now, run Terraform commands as you normally would, such as terraform apply. Terraform will use the compiled binary from the path specified in dev_overrides. When you use a provider override, Terraform will display a warning indicating that this provider version may not match any released version.

> terraform apply

╷
│ Warning: Provider development overrides are in effect
│
│ The following provider development overrides are set in the CLI configuration:
│  - registry.terraform.io/rancher/rke in /Users/wjdj/terraform-provider-custom
│
│ The behavior may therefore not match any released version of the provider and applying changes may cause the state to become incompatible with published releases.