constellation/dev-docs/workflows/terraform-provider.md

Constellation Terraform Provider

This document explains the basic ways of working with the Constellation Terraform Provider.

Building the Terraform Provider

The Constellation Terraform provider can be built through Bazel, either via the devbuild target (recommended), which will create a terraform directory with the provider binary and some utility files in the current working directory, or explicitly via this command:

bazel build //terraform-provider-constellation:tf_provider

Documentation for the provider can be generated with:

bazel run //:generate
# or
bazel run //bazel/ci:terraform_docgen

Using the Terraform Provider

If using the devbuild target, the Terraform provider binary is automatically copied to your local registry cache at ${HOME}/.terraform.d/plugins/registry.terraform.io/edgelesssys/constellation/<version>/<os>_<arch>/. After running devbuild, you can use the provider by simply adding the following to your Terraform configuration:

terraform {
  required_providers {
    constellation = {
      source = "edgelesssys/constellation"
      version = "<version>"
    }
  }
}

Make sure to add the build's pseudo-version (without the v prefix) as the <version>. Alternatively, check the available versions in your local plugin cache:

ls ~/.terraform.d/plugins/registry.terraform.io/edgelesssys/constellation

Alternatively, you can configure Terraform to use your binary by setting a development override, so that the registry path to the provider is replaced with the path to the locally built provider. A config.tfrc file containing the necessary configuration can be created with the following commands:

bazel build //terraform-provider-constellation:terraform_rc
cp bazel-bin/terraform-provider-constellation/config.tfrc .
sed -i "s|@@TERRAFORM_PROVIDER_PATH@@|$(realpath bazel-bin/terraform-provider-constellation/tf_provider_/tf_provider)|g" config.tfrc

Afterwards, all Terraform commands that should use the local provider build should be prefixed with TF_CLI_CONFIG_FILE=config.tfrc like so:

TF_CLI_CONFIG_FILE=config.tfrc terraform apply
...

Testing the Terraform Provider

Terraform acceptance tests can be run hermetically through Bazel (recommended):

bazel test --config=integration-only //terraform-provider-constellation/internal/provider:provider_test

The tests can also be run through Go, but the TF_ACC environment variable needs to be set to 1, and the host's Terraform binary is used, which may produce inaccurate test results.

cd terraform-provider-constellation
TF_ACC=1 go test -v ./...