Creating your first stack

In this guide, you'll learn how to use Spacelift with a straightforward Terraform configuration. This configuration launches an AWS EC2 instance of type t2.micro tagged as "app-server" and outputs both the instance ID and its public IP. The AMI used is the default Linux AMI for the us-east-1 region, so if you're operating in another region, update the AMI accordingly.

Terraform Configuration

Below is the Terraform configuration that creates the EC2 instance:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.16"
    }
  }
  required_version = ">= 1.2.0"
}

provider "aws" {
  region = "us-east-1"
}

resource "aws_instance" "app_server" {
  ami           = "ami-02396cdd13e9a1257"
  instance_type = "t2.micro"

  tags = {
    Name = "app-server"
  }
}

This configuration deploys a simple EC2 instance. To retrieve essential details about this instance, such as its ID and public IP address, include the following outputs:

output "instance_id" {
  description = "ID of the EC2 instance"
  value       = aws_instance.app_server.id
}

output "instance_public_ip" {
  description = "Public IP address of the EC2 instance"
  value       = aws_instance.app_server.public_ip
}

Repository Setup

To begin, create a GitHub repository for your project. In this example, we use "spacelift-demo" as the repository name, keeping it public with default settings.

After you name the repository, click Create repository. Then, run the following commands to initialize your repository locally, add your files, commit your changes, and push your repository to GitHub:

echo "# spacelift-demo" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/Sanjeev-Thiyagarajan/spacelift-demo.git
git push -u origin main

Once the push is complete, you will see your repository populated with the corresponding files.

A default .gitignore is automatically included to prevent committing unnecessary files.

Configuring Spacelift

With your repository ready, head over to the Spacelift website and click the Get Started button on the homepage.

You can sign up using GitHub, GitLab, or Google. Using GitHub simplifies the process, as Spacelift automatically detects your repositories.

After logging in, you'll see a dashboard featuring a Stacks section. In Spacelift, stacks are the core building blocks, with each repository linked to its corresponding stack. Follow these steps to create a stack for your demo:

1. Click on Create new stack.

2. Name the stack "Spacelift-demo" and optionally add labels and a description for better management.

   

3. Click Continue and search for your GitHub repository by typing "spacelift-demo." Select the main branch.

4. If your Terraform code is inside a subdirectory, specify the project root; otherwise, leave the field with its default value.

5. Choose Terraform as the backend and keep the advanced configurations unchanged.

   

   

6. Leave additional settings (such as auto deploy or auto retry) at their defaults and click Save Stack.

   

Your "Spacelift-demo" stack is now created and visible on your dashboard. Any changes pushed to your GitHub repository will automatically trigger a run in Spacelift.

Triggering a New Run

To see Spacelift in action, make a slight modification to your Terraform configuration (such as adding a comment), then commit and push the change:

git add .
git commit -m "second commit"
git push

Once pushed, Spacelift detects the update and initiates a new run. The run status on the dashboard will change from "queued" to "preparing" as Spacelift initializes a containerized runner.

During the run, you may see output logs indicating that Spacelift is initializing the Terraform backend and provider plugins. For example, the planning phase might display an error like this:

Error: configuring Terraform AWS Provider: no valid credential sources for Terraform AWS Provider found.

Please see https://registry.terraform.io/providers/hashicorp/aws for more information about providing credentials.

AWS Error: failed to refresh cached credentials, no EC2 IMDS role found, operation error ec2imds: GetMetadata, request canceled, context deadline exceeded

with provider["registry.terraform.io/hashicorp/aws"],
on main.tf line 11, in provider "aws":
11: provider "aws" {
[...]

Conclusion

This walkthrough has demonstrated how to create your first stack with Spacelift using a simple Terraform configuration. You now understand how to set up your repository, connect it with Spacelift, and trigger runs through Git operations. Happy deploying!