terraform-provider-coder

Terraform provider for Coder.

Developing

Prerequisites

Go
Terraform

We recommend using nix to manage your development environment. If you have nix installed, you can run nix develop to enter a shell with all the necessary dependencies.

Alternatively, you can install the dependencies manually.

Building

Follow the instructions outlined in the Terraform documentation to setup your local Terraform to use your local version rather than the registry version.

Create a file named .terraformrc in your $HOME directory

Add the following content:

 provider_installation {
     # Override the coder/coder provider to use your local version
     dev_overrides {
       "coder/coder" = "/path/to/terraform-provider-coder"
     }

     # For all other providers, install them directly from their origin provider
     # registries as normal. If you omit this, Terraform will _only_ use
     # the dev_overrides block, and so no other providers will be available.
     direct {}
 }

(optional, but recommended) Validate your configuration:
1. Create a new main.tf file and include:
```
terraform {
    required_providers {
        coder = {
            source = "coder/coder"
        }
    }
}
```
1. Run terraform init and observe a warning like Warning: Provider development overrides are in effect
Run make build to build the provider binary, which Terraform will try locate and execute
All local Terraform runs will now use your local provider!
NOTE: we vendor in this provider into github.com/coder/coder, so if you're testing with a local clone then you should also run go mod edit -replace github.com/coder/terraform-provider-coder=/path/to/terraform-provider-coder in your clone.

Terraform Acceptance Tests

To run Terraform acceptance tests, run make testacc. This will test the provider against the locally installed version of Terraform.

Note

Our CI workflow runs a test matrix against multiple Terraform versions.

Integration Tests

The tests under the ./integration directory perform the following steps:

Build the local version of the provider,
Run an in-memory Coder instance with a specified version,
Validate the behaviour of the local provider against that specific version of Coder.

To run these integration tests locally:

Pull the version of the Coder image you wish to test:

  docker pull ghcr.io/coder/coder-preview:main-x.y.z-devel-abcd1234

Run CODER_IMAGE=ghcr.io/coder/coder-preview CODER_VERSION=main-x.y.z-devel-abcd1234 make test-integration.

Note

You can specify CODER_IMAGE if the Coder image you wish to test is hosted somewhere other than ghcr.io/coder/coder. For example, CODER_IMAGE=example.com/repo/coder CODER_VERSION=foobar make test-integration.

How to create a new release

Warning

Before creating a new release, make sure you have pulled the latest commit from the main branch i.e. git pull origin main

Create a new tag with a version number (following semantic versioning):
```
git tag -a v2.1.2 -m "v2.1.2"
```
Push the tag to the remote repository:
```
git push origin tag v2.1.2
```

A GitHub Actions workflow named "Release" will automatically trigger, run integration tests, and publish the new release.