Stack

From this article you can learn what a stack is, how to create it, and what settings you can apply to it

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.

Your first stack

Unless you're defining a stack programmatically using a Terraform provider, you will be creating one from the root of your Spacelift account:

You need to be an admin to create a stack. By default, GitHub account owners and admins are automatically given Spacelift admin privileges, but this can be customized using login policies and/or SSO integration.

The stack creation process involves four simple steps. Please see below for a step-by-step walkthrough and explanation.

Integrate VCS

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.

In this step, only GitHub repositories accessible by Spacelift are listed. If some repositories in your account appear to be missing, it's likely that you've installed the app for selected repositories only. That's fine, too, just whitelist the desired repositories and retry.

Configure state

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:

Remember - this is the only time you can ask Spacelift to be the backend for a given stack, so choose wisely. You can read more about state management here.

If you want to bring your own backend, there's no point in doing additional state locking - Spacelift itself provides a more sophisticated state access control mechanism than Terraform.

Name your stack

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.

Stack settings

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.

Administrative

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.

Another possible pattern would be for a stack to explicitly export its outputs as a context to avoid both the Terraform remote state anti-pattern and the need for external storage.

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.

Autodeploy

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.

Autoretry

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.

Autoretry is only supported for Stacks with a private Worker Pool attached.

Name and description

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.

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.

So even though you can change the stack name at any point, we strongly discourage all non-trivial changes.

Labels

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

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

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.

A branch must exist before it's pointed to in Spacelift. If it's ever deleted, the stack will stop working (ie. every Run and Task will fail trying to pull the source code) until a branch with the same name is recreated.

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.

Spacelift does not support repositories moving between GitHub accounts. In that case the best course of action is to take your Terraform state, download it and import it while recreating the stack (or multiple stacks) in a different account. After that, all the stacks pointing to the old repository can be safely deleted.

Terraform version

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.

Stack locking

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.

The owner of the lock is the only one who can trigger runs and tasks for the entire duration of the lock. Locks never expire, and only its creator and GitHub organization admins can release it.

My precious!

Stack state

Similar to runs and tasks, stacks also have states. A stack's state is the last state of its most recently processed tracked run. Only if the stack has no runs yet a special state "None" is applied:

Stack states allow users to see at a glance the overall health of their infrastructure, and the level of development activity associated with it.