DEV Community

KILLALLSKYWALKER
KILLALLSKYWALKER

Posted on

Help me, Localstack. You're my only hope.

#localstack #aws #terraform

Last year, I learned Terraform with a group on Discord. The person who taught us was very knowledgeable and explained things clearly. It was an introduction to Terraform, but it gave a strong foundation.

At that time, we learned how to set up an AWS EC2 instance inside a specific VPC and subnet. We used the latest Amazon Linux 2023 AMI and stored the Terraform state in an S3 bucket. This was a very good example to understand how Terraform helps manage and create infrastructure in a structured and repeatable way.

However, I am a normal person. If I do not practice what I learn, I will slowly forget it. In my current daily job, I do not work with AWS at all. Because of that, I need a way to keep practicing so my knowledge stays fresh and I can continue improving this skill.

To practice properly, I would normally need an AWS account. But using a real AWS account means I must be very careful to avoid unexpected charges, even though there is a free tier.

This is where LocalStack helps a lot. LocalStack allows us to emulate AWS services locally on our own machine. By using Terraform together with LocalStack, I can safely practice AWS infrastructure without worrying about costs. I believe this is one of the safest and best ways to learn and improve Terraform skills for AWS.

Setup

Below is the most simple setup to start using Terraform with LocalStack.

1. Install LocalStack

Install LocalStack based on your operating system. Please refer to the official documentation below and follow the instructions for your platform:

2. Verify LocalStack Installation

After installation, make sure LocalStack is running correctly.

Start LocalStack:

localstack start
Enter fullscreen mode Exit fullscreen mode

In another terminal, verify it is working:

curl http://localhost:4566/_localstack/health
Enter fullscreen mode Exit fullscreen mode

If LocalStack is running, you should see a JSON response showing all available services. This means LocalStack is working correctly.

3. Set Up AWS CLI Profile (Using Original AWS CLI)

Since we are not using awslocal and will use the original AWS CLI, we still need to configure an AWS profile as usual. LocalStack does not validate credentials, so dummy values are fine.

Create a new AWS profile:

aws configure --profile localstack
Enter fullscreen mode Exit fullscreen mode

Use the following example values:

  • AWS Access Key ID: test
  • AWS Secret Access Key: test
  • Default region name: us-east-1
  • Default output format: json

After that, you must update the AWS config file to point to the LocalStack endpoint.

Open ~/.aws/config and add the following:

[profile localstack]
region = us-east-1
output = json
endpoint_url = http://localhost:4566
Enter fullscreen mode Exit fullscreen mode

This tells the AWS CLI to send all requests for this profile to LocalStack instead of real AWS.

This profile will be used by Terraform and AWS CLI when working with LocalStack.

4. Ensure AWS CLI Version Supports endpoint_url in Config

Make sure you are using AWS CLI v2.13.0 or later. Versions older than this may not fully support the endpoint_url value inside the AWS config file.

Check your AWS CLI version:

aws --version
Enter fullscreen mode Exit fullscreen mode

You should see output similar to:

aws-cli/2.13.0 Python/3.x
Enter fullscreen mode Exit fullscreen mode

If your version is lower than 2.13.0, please upgrade AWS CLI before continuing.

Once this is done, your AWS CLI and profile are ready to work with LocalStack and Terraform.

Create an S3 Bucket with Terraform

After the setup is complete, we can start using Terraform with LocalStack. In this example, we will create an S3 bucket.

Terraform Files

You will need two files:

terraform.tf

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.92"
    }
  }
  required_version = ">= 1.2"
}
Enter fullscreen mode Exit fullscreen mode

main.tf

provider "aws" {
  profile = "localstack"
  region  = "us-east-1"

  s3_use_path_style           = true
  skip_credentials_validation = true
  skip_metadata_api_check     = true

  endpoints {
    s3 = "http://s3.localhost.localstack.cloud:4566"
  }

  default_tags {
    tags = {
      Environment = "tutorial"
      Project     = "localstack-terraform"
    }
  }
}

resource "aws_s3_bucket" "example" {
  bucket_prefix = "localstack-terraform"
}
Enter fullscreen mode Exit fullscreen mode

Explanation of main.tf

Below is a simple explanation for each part of main.tf.

Provider Block 

provider "aws" {
Enter fullscreen mode Exit fullscreen mode

This tells Terraform that we are using the AWS provider.

profile = "localstack"
Enter fullscreen mode Exit fullscreen mode

This uses the AWS CLI profile named localstack, which we configured earlier.

region = "us-east-1"
Enter fullscreen mode Exit fullscreen mode

This sets the AWS region. LocalStack requires a region value even though it runs locally.

S3 Specific Settings 

s3_use_path_style = true
Enter fullscreen mode Exit fullscreen mode

This forces Terraform to use path-style S3 URLs. LocalStack requires this to work correctly.

skip_credentials_validation = true
Enter fullscreen mode Exit fullscreen mode

This skips AWS credential validation because LocalStack does not check real credentials.

skip_metadata_api_check = true
Enter fullscreen mode Exit fullscreen mode

This disables calls to the EC2 metadata service, which is not needed when running locally.

Endpoints Configuration 

endpoints {
  s3 = "http://s3.localhost.localstack.cloud:4566"
}
Enter fullscreen mode Exit fullscreen mode

This tells Terraform to send all S3 requests to LocalStack instead of real AWS S3.

Default Tags 

default_tags {
  tags = {
    Environment = "tutorial"
    Project     = "localstack-terraform"
  }
}
Enter fullscreen mode Exit fullscreen mode

These tags will be automatically added to all AWS resources created by this provider.

S3 Bucket Resource 

resource "aws_s3_bucket" "example" {
  bucket_prefix = "localstack-terraform"
}
Enter fullscreen mode Exit fullscreen mode

This creates an S3 bucket. Terraform will generate a unique bucket name that starts with localstack-terraform.

At this point, you can run terraform init and terraform apply to create the S3 bucket in LocalStack.

Closing

This example is only an introduction to show how LocalStack can help you test and try AWS services locally without using a real AWS account.

However, there is an important catch. When using Terraform this way, you need to manually configure service endpoints, provider flags, and other LocalStack-specific settings. Over time, this adds unnecessary configuration and maintenance to your Terraform code.

To avoid this, Terraform provides tflocal, which is designed to work directly with LocalStack. It automatically handles service endpoints and reduces the need for extra configuration. In real projects, using tflocal is usually a cleaner and easier approach when working with LocalStack.

Top comments (0)