Creating a stack

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

Info

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 nine simple steps:

1. Naming, describing and labeling;
2. Creating a link between your new stack and an existing Git repository;
3. Defining backend-specific behavior (different for each supported backend, eg. Terraform, AWS CloudFormation, Pulumi, or Kubernetes
4. Defining common behavior of the stack;
5. Creating stack hooks;
6. Attaching a cloud integration;
7. Attaching policies;
8. Attaching contexts;
9. Review the summary and create your stack;

Name your stack

Staring with the most difficult step - naming things. Here's where you give your new stack a nice informative 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.

Here you will be able to choose which space your stack belongs to. Initially, you start with a root and a legacy space. The root space is the top-level space of your account, while the legacy space exists for backward compatibility with pre-spaces RBAC.

Also, this is the opportunity to set a few labels. Labels are useful for searching and grouping things, but also work extremely well with policies.

Integrate VCS

In this step, you will need to tell Spacelift where to look for the IaC code for the stack - if you have multiple integrations per VCS type, then you'll need to choose the one which includes your repository. Please note that only those VCS integrations will appear which the stack Space (set in the previous step) has access to. For example, if the stack Space is ParentSpace and the VCS integration Space is ChildSpace with inheritance enabled, it will appear. Integrations marked as default will always appear here, regardless of the stack Space. Take a look at the source control docs for more details.

The branch that you specify set here is what we called a tracked branch. By default, anything that you push to this branch will be considered for deployment. Anything you push to a different branch will be tested for changes against the current state.

The project root configuration is where inside the repository Spacelift should look for the infra project source code (e.g. create a stack for a specific folder in the repository).

A few things worth noting:

• you can point multiple Spacelift stacks to the same repository, even the same branch;
• the default behavior can be tweaked extensively to work with all sorts of Git and deployment workflows (yes, we like monorepos, too) using push and trigger policies, which are more advanced topics;
• in order to learn what exactly our Git hosting provider integration means, please refer to GitHub and GitLab integration documentation;

Info

If you're using our default GitHub App integration, we only list the repositories you've given us access to. If some repositories appear to be missing in the selection dropdown, it's likely that you've installed the app on a few selected repositories. That's fine, too, just whitelist the desired repositories and retry.

Configure backend

At this point you'll probably know whether you want to create a Terraform, OpenTofu, Terragrunt, AWS CloudFormation, Pulumi, Ansible or Kubernetes stack. Each of the supported vendors has some settings that are specific to it, and the backend configuration step is where you can define them.

Terraform

When selecting Terraform, you can choose which version of Terraform to start with - we support Terraform 0.12.0 and above, up to the latest version of MPL Terraform. You don't need to dwell on this decision since you can change the version later - Spacelift supports full Terraform version management allowing you to even preview the impact of upgrading to a newer version.

The next decisions involves your Terraform state. First, whether you want us to provide a Terraform state backend for your state. We do offer that as a convenience feature, though Spacelift works just fine with any remote backend, like Amazon S3.

Info

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.

If you choose not to use our state backend, feel free to proceed. If you do want us to manage your state, you have an option to import an existing state file from your previous backend. This is only relevant if you're migrating an existing Terraform project to Spacelift. If you have no state yet and Spacelift will be creating resources from scratch, this step is unnecessary.

Warning

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

In addition to these options, we also offer external state access for read-only purposes, this is available for administrative stacks or users with write permission to this Stack's space.

OpenTofu

Right now, creating an OpenTofu has only one slight difference from creating a Terraform stack and that difference refers to setting the workflow tool to OpenTofu.

Pulumi

When creating a Pulumi stack, you will need to provide two things. First, the login URL to your Pulumi state backend, as currently we don't provide one like we do for Terraform, so you will need to bring your own.

Second, you need to specify the name of the Pulumi stack. This is separate from the name of the Spacelift stack, which you will specify in the next step. That said, nothing prevents you from keeping them in sync.

CloudFormation

If you're using CloudFormation with Spacelift, there are a few pieces of information you'll need to provide. First, you'll need to specify the region where your CloudFormation stack will be located.

Additionally, you'll need to provide the name of the corresponding CloudFormation stack for this Spacelift stack. This will help us keep track of the different resources in your infrastructure.

You'll also need to provide the path to the template file in your repository that describes the root CloudFormation stack and finally you'll need to specify the S3 bucket where your processed CloudFormation templates will be stored. This will enable us to manage your CloudFormation state and ensure that all changes are properly applied.

Kubernetes

When you create a Kubernetes stack in Spacelift, you have the option to specify the namespace of the Kubernetes cluster that you want to run commands on. You can leave this empty for multi-namespace Stacks.

You can also provide the version of kubectl that you want the worker to download. This is useful if you need to work with a specific version of kubectl for compatibility or testing purposes. The worker will download the specified version of kubectl at runtime, ensuring that the correct version is available for executing commands on the cluster.

Terragrunt

Creating a Terragrunt stack in Spacelift, gives you the option to specify the Terraform and Terragrunt versions you want to use.

You also have the possibility of enabling the run-all feature of Terragrunt, which is useful in scenarios where organizations rely on this in their current process and are unable to do a full migration yet.

Support is currently in Beta.

Ansible

When you create an Ansible stack in Spacelift, you have the option to select the playbook file you want to use. You can define policies for your stack as you would do for any other stack.

Support is currently in Beta.

Stack Created

With the expection of Pulumi, which requires additional mandatory steps first. After selecting the vendor for your stack, you're brought to a new screen indicating that your stack has been successfully created. This screen serves as a branching point where you can enhance the functionality of your stack through various integrations and customizations.

You have the flexibility to either take shortcuts to specific configurations or continue through the standard process of setting up your stack.

Define behavior

Regardless of which of the supported backends (Terraform, Pulumi etc.) you're setting up your stack to use, there are a few common settings that apply to all of them. You'll have a chance to define them in the next step:

The behavior settings are:

• whether the stack is administrative;
• worker pool to use, if applicable (default uses the Spacelift public worker pool);
• whether the changes should automatically deploy;
• whether obsolete tests should be automatically retried;
• whether or not to protect the stack from deletion;
• whether or not to enable the local preview spacectl CLI feature;
• whether or not run promotion is enabled;
• optionally specify a custom Docker image to use to for your job container;

Create Stack Hooks

You also have the ability to control what happens before and after each runner phase using Stack Hooks. In this phase, you can define commands that run in between the following phases:

• Initialization
• Planning
• Applying
• Destroying
• Performing
• Finally

You can read more about stack hooks here.

Attach Stack Cloud Integration

Here you have the ability to attach any Cloud Integrations you have configured.

Cloud integrations allow Spacelift to manage your resources without the need for long-lived static credentials.

Spacelift integrates with identity management systems from major cloud providers to dynamically generate short-lived access tokens that can be used to configure their corresponding Terraform providers.

Currently, AWS, Azure and GCP are natively supported.

You can read more about Cloud ingrations here.

Attach Stack Policies

Spacelift as a development platform is built around the concept of policies and allows defining policies that involve various decision points in the application.

In this section, you can attach the following policy types:

• Approval: who can approve or reject a run and how a run can be approved;
• Plan: which changes can be applied;
• Push: how Git push events are interpreted;
• Trigger: what happens when blocking runs terminate;

Policies can be automatically attached to stacks using the autoattach:label special label where label is the name of a label attached to stacks and/or modules in your Spacelift account you wish the policy to be attached to.

You can read more about policies here.

Attach Stack Contexts

Contexts are sets of environment variables and related configuration,including hooks that can be shared across multiple stacks. By attaching a context, you ensure your stack has all the necessary configuration elements it needs to operate, without repeating the setup for each stack.

Contexts can be automatically attached to stacks using the autoattach:label special label where label is the name of a label attached to stacks and/or modules in your Spacelift account you wish the context to be attached to.

You can read more about contexts here.

Summary

On the summary section, you can now review your settings before finalizing the creation of your stack. This modular approach ensures your stack gets set up with all the necessary components.

Congratulations on creating your stack! 🚀