Migration from Terraform Cloud to Spacelift

You can use several SaaS solutions to manage your Terraform state. Spacelift (opens in a new tab) was on my list since the end of 2022 and I finally had a chance to migrate migrate from Terraform Cloud to Spacelift.

Motivation

As usual, my primary motivation was to learn something new. Spacelift has been considered as a tool for managing Terraform state at my work. I wanted to get some experience with it before we start using it at work.

Prerequisites

Before you start, you need:

• Spacelift account,
• Terraform Cloud workspace(s),
• GitHub repository with your Terraform code,
• Terraform CLI,
• Spacelift CLI.

Migration

Spacelift has a really nice guide on how to migrate from Terraform Cloud (opens in a new tab).

And yet, this guide has some gaps and I want to share my experience.

Login to Spacelift and Terraform Cloud

Before you start, make sure that you logged in to Spacelift and Terraform Cloud:

terraform login spacelift.io

terraform login

Use Spacelift migration kit

Spacelift Migration Kit (opens in a new tab) helps you to migrate your Terraform state from Terraform Cloud to Spacelift. Make sure you cloned it before you start.

I've successfully managed to:

• export Terraform Cloud resources,
• generate Spacelift configuration.

But later on, I've experienced some issues with creating the stacks.

A primary reason for this was that my VCS integration was not configured exact the same way as it was in the guide.

The guide expects that you have installed the Spacelift GitHub app (opens in a new tab). I created my Spacelift account using my Google account and therefore I had to use GitHub custom app (opens in a new tab).

Therefore, the Terraform configuration generated by the migration kit did not work for me. To fix that, you need to specify in the spacelift_stack.manager resource the github_enterpise block with namespace parameter, where namespace is the name of your GitHub organization or account.

resource "spacelift_stack" "manager" {
  administrative = true
  branch         = var.branch
  description    = var.stack_description
  name           = var.stack_name
  github_enterprise {
    namespace = "change-me-github-organisation-or-account-name"
  }
  project_root   = var.project_root
  repository     = var.repository
}

See Spacelift provider documentation (opens in a new tab) for more details.

Once, I've managed to resolve this issue, I was able to create the stack, import the resources, and apply the configuration.

Unfortunately, you need to update the secret environment variables manually.

The final state of my Terraform infrastructure can be found in the repository (opens in a new tab).

Learning points

There are several differences I've noticed between Terraform Cloud and Spacelift. I want to highlight the most important ones.

Working with Terraform state

If Terraform Cloud allows you to work with Terraform state with Terraform CLI locally, Spacelift uses [Spacelift Stack Task][spacelift-stack-task] to run custom operations on the Terraform state. Fortunaltey, you can use Spacelift CLI to create these tasks.

For example, I wanted to import the Spacelift Stack resource to the Terraform. To do that, I had to create a custom task:

spacectl stack task --id dev 'terraform import spacelift_stack.stacks[\"dev\"] dev'

Preview runs

Terraform Cloud is a powerful tool when it comes to speculative plans (opens in a new tab).

In Spacelift this functionality is not enabled by default. To enable it, you need to update the configuration of your Spacelift stack with enable_local_preview (opens in a new tab).

Then running

spacectl stack local-preview --id dev

gives you exact the same experience as you have with Terraform Cloud.

Conclusion

I've successfully migrated my Terraform state from Terraform Cloud to Spacelift. In general Spacelift is a great tool and I'm looking forward to using it further.

See the current state of my infrastructure as code github.com/dev/infrastructure/terraform (opens in a new tab)