The Spacelift Terraform provider is used to programmatically interact with its GraphQL API, allowing Spacelift to declaratively manage itself 🤯
You can browse documentation on the Terraform provider registry.
You can use the provider via the Terraform provider registry.
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.
To develop the provider locally you need the following tools:
- Go 1.21.
- GoReleaser.
- A Spacelift account to use for testing.
To generate the documentation, run the following command:
cd tools
go generate ./...
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.
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
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"
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.
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.
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