What would you say if you could manage Spacelift resources - that is stacks, contexts, integrations, and configuration - using Spacelift? We hate ClickOps as much as anyone, so we designed everything from the ground up to be easily managed using a Terraform provider. We hope that advanced users will define most of their resources programmatically.
Taking it for a spin»
Our Terraform provider is open source and its README always contains the latest available documentation. It's also distributed as part of our Docker runner image and available through our own provider registry. The purpose of this article isn't as much to document the provider itself but to show how it can be used to incorporate Spacelift resources into your infra-as-code.
So, without further ado, let's define a stack:
1 2 3 4 5 6 7
That's awesome. But can we put Terraform to good use and integrate it with resources from a completely different provider? Sure we can, and we have a good excuse, too. Stacks accessibility can be managed by GitHub teams, so why don't we define some?
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
Now that we programmatically combine Spacelift and GitHub resources, let's add AWS to the mix and give our new stack a dedicated IAM role:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
OK, so who wants to go back to clicking on things in the web GUI? Because you will likely need to do some clicking, too, at least with your first stack.
How it works»
Depending on whether you're using Terraform 0.12.x or higher, the Spacelift provider is distributed slightly differently. For 0.12.x users, the provider is distributed as a binary available in the runner Docker image in the same folder we put the Terraform binary. If you're using Terraform 0.13 and above, you can benefit from pulling our provider directly from our own provider registry. In order to do that, just point Terraform to the right location:
1 2 3 4 5 6 7 8 9
Using inside Spacelift»
Within Spacelift, the provider is configured by an environment variable
SPACELIFT_API_TOKEN injected into each run and task belonging to stacks marked as administrative. This value is a bearer token that contains all the details necessary for the provider to work, including the full address of the API endpoint to talk to. It's technically valid for 3 hours but only when the run responsible for generating it is in Planning, Applying or Performing (for tasks) state and throughout that time it provides full administrative access to Spacelift entities that can be managed by Terraform within the same Spacelift account.
Using outside of Spacelift»
If you want to run the Spacelift provider outside of Spacelift, or you need to manage resources across multiple Spacelift accounts from the same Terraform project, the preferred method is to generate and use dedicated API keys. Note that unless you're just accessing whitelisted data resources, the Terraform use case will normally require marking the API key as administrative.
In order to set up the provider to use an API key, you will need the key ID, secret, and the API key endpoint:
1 2 3 4 5 6 7 8
These values can also be passed using environment variables, though this will only work to set up the provider for a single Spacelift account:
If you want to talk to multiple Spacelift accounts, you just need to set up provider aliases like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
If you're running from inside Spacelift, you can still use the default, zero-setup provider for the current account with providers for accounts set up through API keys:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
We suggest to first manually create a single administrative stack, and then use it to programmatically define other stacks as necessary. If you're using an integration like AWS, you should probably give the role associated with this stack full IAM access too, allowing it to create separate roles and policies for individual stacks.
If you want to share data between stacks, please consider programmatically creating and attaching contexts.
Programmatically generated stacks and contexts can still be manually augmented, for example by setting extra elements of the environment. Thanks to the magic of Terraform, these will simply be invisible to (and thus not disturbed by) your resource definitions.
Boundaries of programmatic management»
Spacelift administrative tokens are not like user tokens. Specifically, they allow access to a much smaller subset of the API. They allow managing the lifecycles of stacks, contexts, integrations, and configuration, but they won't allow you to create or even access Terraform state, runs or tasks, or their associated logs.
Administrative tokens have no superpowers either. They can't read write-only configuration elements any more than you can as a user. Unlike human users with user tokens, administrative tokens won't allow you to run
env in a task and read back the logs.
In general, we believe that things like runs or tasks do not fit the (relatively static) Terraform resource lifecycle model and that hiding those parts of the API from Terraform helps us ensure the integrity of potentially sensitive data - just see the example above.