Spacelift Terraform Provider

The Spacelift Terraform provider is used to programmatically interact with its GraphQL API, allowing Spacelift to declaratively manage itself 🤯

Documentation

You can browse documentation on the Terraform provider registry.

Using the Provider

Terraform 0.13 and Above

You can use the provider via the Terraform provider registry.

Terraform 0.12 or Manual Installation

You can download a pre-built binary from the releases page, these are built using goreleaser (the configuration is in the repo). You can verify the signature using this key.

If you want to build from source, you can simply use go build in the root of the repository.

Development

Tools

To develop the provider locally you need the following tools:

Go 1.22.
GoReleaser.
A Spacelift account to use for testing.

Generating the Documentation

To generate the documentation, run the following command:

cd tools
go generate ./...

Using a Local Build of the Provider

Sometimes as well as running unit tests, you want to be able to run a local build of the provider against Spacelift. This involves the following steps:

Building a copy of the provider using GoReleaser.
Updating your .terraformrc file to point at your local build.
Generating an API key in Spacelift.
Running Terraform locally.

Building the Provider Using GoReleaser

To build the provider, run the following command:

goreleaser build --clean --snapshot

This will produce a number of binaries in subfolders of the dist folder for each supported architecture and OS:

dist
|-- artifacts.json
|-- config.yaml
|-- metadata.json
|-- terraform-provider-spacelift_darwin_amd64_v1
|   `-- terraform-provider-spacelift_v0.1.11-SNAPSHOT-bb215e9
|-- terraform-provider-spacelift_darwin_arm64
|   `-- terraform-provider-spacelift_v0.1.11-SNAPSHOT-bb215e9
|-- terraform-provider-spacelift_linux_amd64_v1
|   `-- terraform-provider-spacelift_v0.1.11-SNAPSHOT-bb215e9
|-- terraform-provider-spacelift_linux_arm64
|   `-- terraform-provider-spacelift_v0.1.11-SNAPSHOT-bb215e9
|-- terraform-provider-spacelift_windows_amd64_v1
|   `-- terraform-provider-spacelift_v0.1.11-SNAPSHOT-bb215e9.exe
`-- terraform-provider-spacelift_windows_arm64
    `-- terraform-provider-spacelift_v0.1.11-SNAPSHOT-bb215e9.exe

Updating your .terraformrc file

The next step is telling Terraform to use your local build, rather than a copy from the Terraform registry. You can do this by specifying dev_overrides in your .terraformrc file.

To do this, edit or create a .terraformrc in your home folder, and add the following contents:

provider_installation {
  dev_overrides {
    "spacelift.io/spacelift-io/spacelift" = "<absolute-path-to-repo>/dist/terraform-provider-spacelift_<OS>_<arch>"
  }

  direct {}
}

Make sure to replace <absolute-path-to-repo>, <OS>, and <arch> with the correct values, for example:

"spacelift.io/spacelift-io/spacelift" = "/home/my-user/github.com/spacelift-io/terraform-provider-spacelift/dist/terraform-provider-spacelift_linux_amd64_v1"

Generating an API Key

Follow the information in our API documentation page to generate an API key. Please make sure to generate an admin key since admin permissions are required for most operations you will be using the provider for.

Running Spacelift Terraform Provider Locally

To test your local build, just create the relevant Terraform files needed to test your changes, and run terraform plan, terraform apply, etc as normal. The main difference when running the provider locally rather than within Spacelift is that you need to tell it how to authenticate with your Spacelift account. Here's a minimal example:

terraform {
  required_providers {
    spacelift = {
      source = "spacelift.io/spacelift-io/spacelift"
    }
  }
}

provider "spacelift" {
  api_key_endpoint = "https://<account-name>.app.spacelift.io"
  api_key_id       = "<api-key-id>"
  api_key_secret   = "<api-key-secret>"
}

data "spacelift_account" "this" {
}

output "account_name" {
  value = data.spacelift_account.this.name
}

Make sure to replace <account-name>, <api-key-id> and <api-key-secret> with the relevant values.

Releasing New Versions of the Provider

In order to release a new version of the provider one should follow those simple steps:

Create a new tag for the latest commit on tha main branch git tag vX.Y.Z -m "Release"
Push the tag git push origin vX.Y.Z
Refer to our internal wiki on publishing the release artifacts