Stack is one of the core concepts in Spacelift. A stack is an isolated, independent entity and the choice of the word mirrors similar products like AWS CloudFormation or Pulumi. You can think about a stack as a combination of Terraform code and configuration in the form of environment variables and mounted files. In order to be of any use, your Spacelift account will need to contain one or more stacks, so let's create one to see what gives. If you're well familiar with the process and only want to understand individual stack settings, you can skip directly to this section.
Unless you're defining a stack programmatically using a Terraform provider, you will be creating one from the root of your Spacelift account:
The stack creation process involves four simple steps. Please see below for a step-by-step walkthrough and explanation.
In the first step you will need to tell Spacelift where to look for the Terraform code for the stack - a combination of GitHub repository and one of its existing branches. Don't worry, more sophisticated setup is still possible as a separate step - this is just to get your started.
At this stage you can also do two other things - first, you can mark the stack as administrative, that is to allow it to manage other stacks through Terraform. You can read more about it here. You can also set up autodeploy mode. When that's set to true, any change to the tracked branch can be automatically applied if the planning phase was successful and there are no plan policy warnings. You can read more about this setting here.
Here comes a momentous decision - do you want Spacelift to take care of the Terraform state, or would you rather prefer to bring your own Terraform backend. Both are supported and each choice comes with its advantages and drawbacks, so it's time to make up your mind:
Note that even if you're migrating from an existing Terraform backend you can still have Spacelift take over if you're able to get the state file. Just make sure you have it handy for this step:
OK, this is what we've all been waiting for. Give your new stack a nice name and an optional description - this one even supports Markdown:
You'll be able to change the name and description later, too - with one caveat. Based on the original name, Spacelift generates an immutable slug that serves as a unique identifier of this stack. If the name and the slug diverge significantly, things may become confusing.
The list below covers all settings that are set directly on the stack. It's important to note that these are not the only settings that affect how runs and tasks within a given stack are processed - environment, attached contexts, runtime configuration and various integrations will all play a role here, too.
This setting indicates whether a stack has administrative privileges. Administrative stacks receive a runtime environment variable giving their Runs full administrative access to other stacks within the same account using a built-in Terraform provider.
One possible pattern would be to first manually create a single administrative stack, and then use it to programmatically define other stacks in order to avoid ClickOps.
If this sounds interesting and you want to give it a try, please refer to the help article exclusively dedicated to Spacelift's Terraform provider.
Indicates whether changes to the stack can be applied automatically. When autodeploy is set to true, any change to the tracked branch will be automatically applied if the planning phase was successful and there are no plan policy warnings.
Consider setting it to true when you always do a code review before merging to the tracked branch, and/or want to rely on plan policies to automatically flag potential problems. If each candidate change goes through a meaningful human code review with stack writers as reviewers, having a separate step to confirm deployment may be an overkill. You may also want refer to a dedicated section on using plan policies for automated code review.
Indicates whether obsolete proposed changes will be retried automatically. When autoretry is set to true and a change gets applied, all Pull Requests to the tracked branch conflicting with that change will be reevaluated based on the changed state.
This saves you from manually retrying runs on Pull Requests when the state changes. This way it also gives you more confidence, that the proposed changes will actually be the actual changes you get after merging the Pull Request.
Stack name and description are pretty self-explanatory. The required name is what you'll see in the stack list on the home screen and menu selection dropdown. Make sure that it's informative enough to be able to immediately communicate the purpose of the stack, but short enough so that it fits nicely in the dropdown, and no important information is cut off.
The optional description is completely free-form and it supports Markdown. This is a good place perhaps for a thorough explanation of the purpose of the stack, perhaps a link or two, and an obligatory cat GIF.
Labels are arbitrary, user-defined selectors that can be attached to Stacks. A single Stack can have an arbitrary number of these, but they must be unique. Labels can be used for any purpose, including UI filtering, but one area where they shine the most is user-defined policies which can modify their behavior based on the presence (or lack thereof) of a particular label.
Project root points to the directory within the repo where Terraform should start executing. This is especially useful for monorepos, or indeed repositories hosting multiple somewhat independent projects. This setting plays very well with Git push policy, allowing you to easily express generic rules on what it means for the stack to be affected by code change.
Repository and branch point to the location of the Terraform source code for a stack. The repository must belong to the GitHub account linked to Spacelift and its choice may be further limited by the way Spacelift GitHub app has been installed. When installing the app, the user can make a choice whether to enable it for the entire account, or to only whitelist selected repositories. It's the usual convenience vs. security trade-off so whichever choice you make you need to be aware of potential consequences. In particular, if you install the app for selected repositories, you will need to individually whitelist each and every GitHub repository you want to link to a Spacelift stack.
Branch signifies the main branch tracked by the stack. Changes made to this branch can be applied (or discarded) by the stack while changes to other branches will be treated as CI test runs where the outcome of a Terraform plan is communicated via a GitHub commit status. You can refer to the GitHub integration documentation for even more details.
Thanks to the strong integration between GitHub and Spacelift, the link between a stack and a repository can survive the latter being renamed - under the hood we store a GitHub unique repository ID and if that's renamed, we receive a webhook notification and can point the stack to the new location.
Terraform version is a dynamic setting. It can only be directly applied to the stack through the Terraform provider where it basically defines the minimum version of Terraform that can run your workloads. Please refer to the dedicated article to better understand the concept of Terraform version management in Spacelift.
Spacelift supports locking the stack for one person's exclusive use. This can be very handy if a delicate operation is taking place that could easily be affected by someone else making changes in the meantime. Every stack writer can lock the stack unless it's already locked.
Stack states allow users to see at a glance the overall health of their infrastructure, and the level of development activity associated with it.