Common Fate Terraform Provider

Common Fate Terraform provider using Terraform plugin framework

Setting up the provider locally

First create a terraformrc file in your home directory by running touch ~/.terraformrc and add the following code

• If you already have a terraformrc this step can be skipped

Then open the file just created in your editor of choice and add the following

plugin_cache_dir   = "$HOME/.terraform.d/plugin-cache"
disable_checkpoint = true

provider_installation {
  dev_overrides {
                "registry.terraform.io/common-fate/commonfate" = "/Users/PATH_TO_GITHUB_REPO/terraform-provider-commonfate"
 }

  direct {}
}

• This tells Terraform to use a local copy of the provider over the deployed instance running at registry.terraform.io

save and exit.

Then build the provider by running make provider

• This will create the binary of the provider in your local directory.

Running the example Terraform

Auth

The provider uses a m2m OIDC flow to authenticate with Common Fate API's. To successfully get creating Common Fate resources you will need to set the following environment variables:

TF_VAR_oidc_client_id

TF_VAR_oidc_client_secret

• These will be generated by the deployment terraform here... TODO: link to instructions where to find these

cd into the /examples folder and there are example terraform files that can be used for testing, make sure to cd into the example folder.

You should now be able to run terraform init and terraform plan within the example folders

In the plugins repo.

• Run make provider to build a new version of the provider

Tests

Terraform's official documentation for tests can be found here: https://developer.hashicorp.com/terraform/plugin/sdkv2/testing/acceptance-tests

Run the following to run the acceptance tests:

TF_ACC=1 go test -v ./...

Debugging

There is a vscode debugging provider called 'Debug Terraform Provider'. Run this and it will return the following message

Provider started. To attach Terraform CLI, set the TF_REATTACH_PROVIDERS environment variable with the following:

	TF_REATTACH_PROVIDERS='{"registry.terraform.io/common-fate/commonfate":{"Protocol":"grpc","ProtocolVersion":6,"Pid":39056,"Test":true,"Addr":{"Network":"unix","String":"/var/folders/6b/nks_6fns3sj3ljtwcjrt5t840000gn/T/plugin2126076831"}}}'

export this env variable to the directory where you are running your terraform code. Then run a plan/apply with breakpoints set and it will catch.

Docs

Updating docs

To update the docs, edit the template file. To update and generate the docs, follow the instructions on generating docs

Generating docs

Run the following command:

make generate

The updated docs can be found in the docs file

Releasing and change management

Minor version

1. Create a new minor version changeset and merge it to main pnpm changeset
2. Merge the automated changesets PR Version Packages for main this will tag and release a new version

Patch version

1. Create a patch changeset and merge it to main pnpm changeset
2. If you are ready to release this change, Merge the automated changesets PR Version Packages for main this will tag and release a new version

Backporting changes to older minor versions

1. Check for an existing release branch e.g release/v1.* for the minor version you are back porting to
2. If the branch doesn't exist, checkout the commit associated with the minor release you want to backport to
3. Run ./create-minor-release.sh and when prompted set the release branch version e.g v1.1 or v1.2 excluding the patch version
4. Push the branch
5. You can now push your changes to this release branch, you may choose to cherrypick the patch from main
6. Create a patch changeset and merge it to the release branch pnpm changeset
7. If you are ready to release this change, Merge the automated changesets PR matching your release branch Version Packages for release/v1.* this will tag and release a new version