Unless you're defining a stack programmatically using our 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 Git repository and one of its existing branches. 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.
A few things worth noting:
you can point multiple Spacelift stacks to the same repository, even the same branch;
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 basic settings are:
whether the stack is administrative;
project root (optional), i.e. where inside the repository Spacelift should look for the infra project source code;
worker pool to use, if applicable;
The advanced settings are:
whether the changes should automatically deploy;
whether obsolete tests should be automatically retried;
list of commands to run before project initialization;
Docker image to use to for your job container;
At this point you'll probably know whether you want to create a Terraform or a Pulumi 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.
When selecting Terraform, you can choose which version of Terraform to start with - we support Terraform 0.12.0 and above. 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 two 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 S3.
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.
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.
We're almost there, but here comes 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.
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.