Back Story

I was learning Terraform and wanted to test my configurations without racking up AWS bills. That's when I discovered LocalStack - it simulates AWS services right on your machine! Perfect for development and testing without spending a dime. This post documents my journey of getting Terraform and LocalStack to play nicely together.

What We'll Build

By the end of this tutorial, you'll have:

LocalStack running locally (your personal mini-AWS!)
A Terraform config that spins up an EC2 instance
The ability to SSH into your local "cloud" instance

Introduction

In this guide, we'll use Terraform with LocalStack to create and manage cloud infrastructure - all without touching real AWS. LocalStack is basically a fake AWS that runs in Docker, letting you test your infrastructure code for free.

Prerequisites

Before we dive in, make sure you have these installed:

Docker - LocalStack runs inside a container
Terraform - our infrastructure-as-code tool
LocalStack CLI - makes managing LocalStack easier
AWS CLI - for verifying our resources

Setting Up LocalStack

First, let's configure AWS CLI to talk to LocalStack instead of real AWS.

Set up credentials for LocalStack:

Add the following to your AWS credentials and config files. Create them if they don't exist - they live in your home directory under ~/.aws/.
~/.aws/credentials
```
1[localstack]
2aws_access_key_id=test
3aws_secret_access_key=test
```
~/.aws/config
```
1[profile localstack]
2region=us-east-1
3output=json
```
Don't worry about the test values - LocalStack accepts any credentials. It's just for compatibility with AWS tools.
Start LocalStack:
localstack start
Verify it's running (in another terminal):
localstack status
You can also check the LocalStack Dashboard in your browser - it's a nice way to see what's running.

That's it! LocalStack is now up and running. You've got your own little AWS cloud on your machine.

Now let's put it to work with Terraform!

Creating an EC2 Instance with Terraform

Here's the fun part - we'll spin up an EC2 instance using Terraform, complete with SSH access and security groups.

Create a project directory:

mkdir terraform-localstack && cd terraform-localstack

Generate an SSH key pair (we'll need this to connect to our instance):
ssh-keygen -f terra-key -N ""
This creates terra-key (private) and terra-key.pub (public) in your current directory.

Create main.tf with the following content:

main.tf

1# =============================================
2# TERRAFORM CONFIGURATION
3# =============================================
4# Tell Terraform which providers we need
5terraform {
6  required_providers {
7    aws = {
8      source  = "hashicorp/aws"
9      version = "6.27.0"
10    }
11  }
12}
13
14# =============================================
15# AWS PROVIDER SETUP
16# =============================================
17# Use our "localstack" profile from ~/.aws/config
18# This tells Terraform to talk to LocalStack, not real AWS!
19provider "aws" {
20  profile = "localstack"
21  region  = "us-east-1"
22}
23
24# =============================================
25# SSH KEY PAIR
26# =============================================
27# Upload our public key so we can SSH into the instance
28resource "aws_key_pair" "ec2_ssh_key" {
29  key_name   = "ssh-key"
30  public_key = file("terra-key.pub")  # reads the file we generated earlier
31}
32
33# =============================================
34# NETWORKING
35# =============================================
36# Use the default VPC (LocalStack creates one automatically)
37resource "aws_default_vpc" "default" {}
38
39# Create a security group (like a firewall for our instance)
40resource "aws_security_group" "allow_tls" {
41  name        = "allow_tls"
42  description = "Allow TLS inbound traffic and all outbound traffic"
43  vpc_id      = aws_default_vpc.default.id
44}
45
46# Allow HTTPS traffic (port 443)
47resource "aws_vpc_security_group_ingress_rule" "allow_tls_ipv4" {
48  security_group_id = aws_security_group.allow_tls.id
49  cidr_ipv4         = "0.0.0.0/0"  # from anywhere
50  from_port         = 443
51  to_port           = 443
52  ip_protocol       = "tcp"
53}
54
55# Allow SSH traffic (port 22) - so we can connect!
56resource "aws_vpc_security_group_ingress_rule" "allow_ssh" {
57  security_group_id = aws_security_group.allow_tls.id
58  cidr_ipv4         = "0.0.0.0/0"  # from anywhere (fine for local dev)
59  from_port         = 22
60  to_port           = 22
61  ip_protocol       = "tcp"
62}
63
64# Allow all outbound traffic (instance can reach the internet)
65resource "aws_vpc_security_group_egress_rule" "allow_all_traffic_ipv4" {
66  security_group_id = aws_security_group.allow_tls.id
67  cidr_ipv4         = "0.0.0.0/0"
68  ip_protocol       = "-1"  # -1 means all protocols/ports
69}
70
71# =============================================
72# EC2 INSTANCE
73# =============================================
74# Finally, the star of the show - our virtual machine!
75resource "aws_instance" "ec2_machine" {
76  # LocalStack's special AMI ID (see: https://docs.localstack.cloud/aws/services/ec2/#amis)
77  ami           = "ami-df5de72bdb3b"
78  instance_type = "a1.medium"
79
80  # Attach our security group and SSH key
81  security_groups = [aws_security_group.allow_tls.name]
82  key_name        = aws_key_pair.ec2_ssh_key.key_name
83
84  # Configure the root disk
85  root_block_device {
86    volume_type = "gp3"
87    volume_size = 2  # 2 GB is plenty for testing
88  }
89
90  tags = {
91    Name = "localstack-ec2-instance"
92  }
93}

Initialize Terraform (downloads the AWS provider):
terraform init
Validate your configuration (catches syntax errors):
terraform validate
Preview what will be created:
terraform plan
This shows you exactly what Terraform will do without actually doing it.
Apply the configuration (create the resources!):
terraform apply
Type yes when prompted. Terraform will now create your EC2 instance in LocalStack.

Verifying & Connecting to Your Instance

Nice! Your EC2 instance should now be running. Let's verify and connect to it.

Check your instance with AWS CLI:

aws --endpoint-url=http://localhost:4566 ec2 describe-instances --profile localstack

You can also see it in the LocalStack Dashboard - look for your instance under EC2.

Tip: Run docker ps to see the LocalStack container. Everything is running locally inside Docker!

SSH into your instance:

First, secure your private key (SSH requires this):

chmod 600 ./terra-key

Then connect:

ssh -i ./terra-key root@<instance-public-dns>

Replace <instance-public-dns> with the DNS from the describe-instances output, or grab it from the LocalStack Dashboard.

You're now inside your "cloud" instance - running entirely on your machine!

Cleaning Up

When you're done experimenting, tear everything down with:

terraform destroy

Type yes to confirm. This removes all the resources Terraform created.

Wrapping Up

And that's it! You've successfully:

Set up LocalStack as a local AWS alternative
Configured Terraform to work with LocalStack
Created an EC2 instance with security groups and SSH access
Connected to your local "cloud" instance

This setup is great for:

Learning - experiment without fear of AWS bills
Testing - validate your Terraform configs before deploying to real AWS
Development - build cloud-native apps without internet dependency

Feel free to explore other AWS services that LocalStack supports - S3, Lambda, DynamoDB, and more!

Terraform + LocalStack