So you want to take Spacelift for a spin?

This repository is designed just for this purpose. Click the Use this template button to create your own repository in a GitHub account you manage (either your private account or an organization you have admin rights on), and let's get started.

If you change the repository name, make sure to update the spacelift_stack.managed resource in the stack.tf file.

In this tutorial, you will not be using any cloud providers. You won't need any extra credentials. The only resources you will create are those managed by Spacelift's own Terraform provider.

Step 1: Setup Your Spacelift Account

On the Spacelift home page, click on the "Get Started" button.

You will be prompted to start a demo of the Spacelift platform. Feel free to do the demo, or you can skip it as well and follow this more in-depth guide.

Step 2: Connecting with GitHub

In this guide, we will be using GitHub to host our repositories. You can find more information about other supported VCS providers here.

The flow for connecting GitHub as a VCS provider is slightly different when using GitHub to sign in compared to the other sign-in options (GitLab, Google). Follow the section that is applicable to you.

GitHub was used as a sign-in option:

Install the Spacelift GitHub App if you not already installed it.
At this point, it's up to you to decide whether to give Spacelift access to all your repositories or a defined subset.

Note: don't agonize over this choice - you can always change it later.

Installing the application takes you to your first Spacelift screen, where you can create your first stack.

Google or GitLab was used as a sign-in option:

After signing up, you should have arrived on the Spacelift console.
Follow the guide for setting up the GitHub integration.
Make sure that you allow the Spacelift GitHub App installation access to the forked repository.

Step 3: Creating your first stack

Stacks are probably the most important concept in Spacelift. They connect your code and your infra, with some configuration in-between. To keep things short, a Spacelift stack maps directly to a single Terraform state file.

So without further ado, let's click on the Add stack button and go through the stack creation process step by step.

VCS integration

First, we need to tell Spacelift where the project code lives - this is the Integrate VCS step.

Make sure that the provider is GitHub, the repository is the one you just created, and lastly, the main branch is selected. These should be the default values.

Configure Backend

In the next step, we will choose the backend for this stack.

Spacelift can work with Terraform remote state providers, but it also provides its own state management. However, beyond convenience, there are no benefits to using it.

We don't have an existing state to import, so the most convenient thing is to continue with the defaults.

Stack behavior

In the next step, you will configure this stack's behavior.

Since this is meant to be a quick and easy-to-follow tutorial, we won't go into the details, but you can read more about them here.

For now, the only tweak we need to do here is to mark the stack as administrative. Why? Because only administrative stacks can manage Spacelift resources, and that's what we'll be creating as part of this lab.

Naming the stack

As they say, "there are two hard problems in computer science: cache invalidation, naming things, and off-by-1 errors". We'll make it easy this time: we've come up with a good name for your first stack, so feel free to copy it.

For now we won't care about labels or description (yes, we support Markdown), though you can read up on them when you're done with this lab.

Congratulations, you just created your first stack!

Step 4: Triggering a run

Your new stack does not show any tracked runs (AKA deployments) yet. Let's trigger the first one.

We can do that by clicking the Trigger button in the upper right-hand corner of the screen. The trigger button will create a Spacelift job that will check out your code, run the usual Terraform commands against it, and present you with the choice of applying them or not.

You can always refer to the logs directly to see is planned to be changed. In this case, we're creating 25 Spacelift resources, and they all look good. So let's click on the Confirm button and see what happens next.

Wow, 10 seconds? That was quick! Let's go back to our stacks list to see what we've just done. Clicking on the Spacelift logo on the top left will take you there.

Step 5: Exploring created resources

What we just did in Step 3 was create a bunch of very useful Spacelift resources. Looking at the main screen, we can quickly notice two things - our Terraform starter stack turned green (always a good sign!), and there's another Stack we haven't seen before, called Managed stack.

It's red but don't worry, this is expected - one of the exercises here is to fix it.

Environment

Now, where did that come from? In fact, we declared it using Terraform just here. The same file defines many things related to the environment, so let's click on the name of the new stack to be taken to its screen.

Since it doesn't contain anything interesting just yet, let's quickly navigate to the Environment screen. It is a very busy screen, so let's focus on the first section.

We see are environment variables and mounted files - some public and some secret - that we indeed saw defined in the stack.tf file we just looked at. But there are others - see the ones with the blue label to their right? Where did they come from? They're actually defined here and belong to a context attached to the new Stack.

But before we move on to the context, click the Edit button in the upper right-hand corner of the screen and play around with environment variables and mounted files.

Context

Contexts are how Spacelift does configuration reuse. Rather than having to copy and paste a bunch of configuration variables, Spacelift allows you to encapsulate them as a package and attach them to as many stacks as you want.

So if you navigate back to the main screen (hint: click on the logo) and then go to the Contexts screen, selecting it from the hamburger menu next to your name, that's what you're going to see.

Clicking on the context name takes you to the context screen, where you can see that it currently contains two environment variables (one plaintext and one secret) and two mounted files, one plaintext and one secret:

Note that you can edit the context just as you can edit the stack's own environment. That Edit button is there for a reason, so go wild before we move on to policies, which are the second most important topic in Spacelift.

Policies

When you navigate to the Policies screen, you will see that we've created six different policies.

All these policies are defined and explained in the policies.tf file, but let's go through them one by one:

DevOps are admins is a login policy that would make anyone who's a member of the DevOps team in your GitHub organization log in as a Spacelift administrator as opposed to the default situation where only GitHub admin users are automatically Spacelift admins. Note: this changes if you're using SSO instead of GitHub to authenticate;
All of Engineering gets read access is an access policy that gives any member of the Engineering GitHub team read access to every stack it's attached to;
Ignore commits outside the project root is a Git push policy that ignores push notifications which do not affect any files outside of the project root of the stack it's attached to;
Enforce password strength is a plan policy that prevents you from creating weak passwords using random_password resource type - we'll see this one in action shortly;
Trigger stacks that declare an explicit dependency is a trigger policy that will cause every stack that declares dependency to be triggered when the current one is updated - while this one is probably beyond the scope of the basic tutorial, we wanted to show you that Spacelift is Turing-complete. Also, a trigger policy is what triggered a failing run on the newly created stack 😜

Policies in practice

While it's worth mentioning that we're using an open-source language for our policies, authoring policies is outside of the scope of this tutorial.

Instead, we'd like to show you the power of policies hands-on. Let's navigate to our new stack (Managed stack) and try to figure out why the run created by the trigger policy failed. Looks like a resource we're trying to create does not comply with our policy.

Don't worry for now about fixing it, we will do that in the next step.

Step 6: Tests and pull requests

In this step, we'll try to fix the problem reported by the plan policy, and while doing that, we'll see how Spacelift deals with testing your changes and handling Pull Requests.

Let's edit the managed-stack/main.tf file to make the random password we're trying to create in this new stack just a little bit longer - let's say 24 characters. Do not push that change to the main branch but create a separate branch and open a Pull Request.

And here's the exact change we're making:

That little change causes two runs to be executed since this repository is now connected to two stacks - one that you created manually and one that is managed programmatically. It's the latter stack we've made changes to, so you will see that there are no changes to the former, but one resource would be created for the latter.

Clicking on the Details link next to the commit status check takes you to the test run for the affected stack.

Let's click on View more details on spacelift.io and see the details of the proposed run for the PR. Proposed runs are previews of changes that would be applied to your infrastructure if the new code was merged into a tracked branch, which we will do in a minute.

Now that the push policy is happy with the new length of your password, you can merge the Pull Request to the main branch.

A run will be created automatically in the Runs tab of your Managed stack which should automatically apply the changes (see the autoapply setting in stack.tf).

Congratulations! 👏🏻

You're a Spacelift expert now! If you like what you've seen so far, here are some suggestions:

learn more about policies and create one from scratch;
create some resources on a public cloud;
connect your Slack workspace;
learn about our native cloud integrations;
set up SSO for your organization;
start a Spacelift agent in your own infrastructure (yes, it will run on your laptop, too).

spacelift-io / terraform-starter