Template Dependencies

When creating Coder templates, it is unlikely that you will just be using built-in providers. Part of Terraform's flexibility stems from its rich plugin ecosystem, and it makes sense to take advantage of this.

That having been said, here are some recommendations to follow, based on the Terraform documentation.

Following these recommendations will:

• Prevent unexpected changes: Your templates will use the same versions of Terraform providers each build. This will prevent issues related to changes in providers.
• Improve build performance: Coder caches provider versions on each build. If the same provider version can be re-used on subsequent builds, Coder will simply re-use the cached version if it is available.
• Improve build reliability: As some providers are hundreds of megabytes in size, interruptions in connectivity to the Terraform registry during a workspace build can result in a failed build. If Coder is able to re-use a cached provider version, the likelihood of this is greatly reduced.

Lock your provider and module versions

If you add a Terraform provider to required_providers without specifying a version requirement, Terraform will always fetch the latest version on each invocation:

terraform {
  required_providers {
    coder = {
      source = "coder/coder"
    }
    frobnicate = {
      source = "acme/frobnicate"
    }
  }
}

Any new releases of the coder or frobnicate providers will be picked up upon the next time a workspace is built using this template. This may include breaking changes.

To prevent this, add a version constraint to each provider in the required_providers block:

terraform {
  required_providers {
    coder = {
      source = "coder/coder"
      version = ">= 0.2, < 0.3"
    }
    frobnicate = {
      source = "acme/frobnicate"
      version = "~> 1.0.0"
    }
  }
}

In the above example, the coder/coder provider will be limited to all versions above or equal to 0.2.0 and below 0.3.0, while the acme/frobnicate provider will be limited to all versions matching 1.0.x.

The above also applies to Terraform modules. In the below example, the module razzledazzle is locked to version 1.2.3.

module "razzledazzle" {
  source  = "registry.example.com/modules/razzle/dazzle"
  version = "1.2.3"
  foo     = "bar"
}

Use a Dependency Lock File

Terraform allows creating a dependency lock file to track which provider versions were selected previously. This allows you to ensure that the next workspace build uses the same provider versions as with the last build.

To create a new Terraform lock file, run the terraform init command inside a folder containing the Terraform source code for a given template.

This will create a new file named .terraform.lock.hcl in the current directory. When you next run coder templates push, the lock file will be stored alongside with the other template source code.

Note: Terraform best practices also recommend checking in your .terraform.lock.hcl into Git or other VCS.

The next time a workspace is built from that template, Coder will make sure to use the same versions of those providers as specified in the lock file.

If, at some point in future, you need to update the providers and versions you specified within the version constraints of the template, run

terraform init -upgrade

This will check each provider, check the newest satisfiable version based on the version constraints you specified, and update the .terraform.lock.hcl with those new versions. When you next run coder templates push, again, the updated lock file will be stored and used to determine the provider versions to use for subsequent workspace builds.