Learn LocalStack - AWS Replicator

#Introduction

In episode 16 we emulated advanced services — ECS, EKS, Step Functions, up to Athena. But there's a classic problem: the data we emulate is synthetic. For scenarios demanding high realism, such as testing IaC that depends on VPCs, IAM, or other resources that already exist in an AWS account, LocalStack Pro provides AWS Replicator. This feature copies resources from a real AWS account into LocalStack at the API level, so resource names and IDs stay identical to the originals.

One important note from the start: AWS Replicator is a Pro feature, requires a license or auth token (LOCALSTACK_API_KEY), and works asynchronously through jobs.

#Setting Up the Environment

There are three prerequisites: a Pro license, AWS credentials with read-only access to the resources being copied, and the correct region. Credentials can come from a profile or environment variables:

export LOCALSTACK_API_KEY=ls_pro_placeholder
export AWS_PROFILE=readonly-sandbox
export AWS_DEFAULT_REGION=us-east-1
export AWS_ENDPOINT_URL=http://localhost:4566

The best practice is clear: never use production credentials. Use a minimal role with read-only permissions for the resources being replicated.

#Replication Job Workflow

Replicator works in two steps: submit a job, then check its status. Start by making sure the LocalStack instance is running:

localstack status
curl -s http://localhost:4566/_localstack/health

Then submit a job for a single VPC:

localstack replicator start \
  --resource-identifier vpc-05208447cff1e3482 --resource-type AWS::EC2::VPC

That command returns a job_id. Monitor its status:

localstack replicator status 4bea1141-a822-4918-8a3d-c323938cc47e

Wait until the job state is complete. After that, the resource is available in LocalStack with exactly the same ID as in AWS.

#Replication Strategies: TREE, BATCH, and Single Resources

Replicator supports several strategies depending on the number of resources and their dependencies:

For VPCs, TREE mode also copies subnets and security groups. For IAM, the 2026.06.0 release support includes role TREE (a role plus its related policies) and policy BATCH. Per-strategy capabilities can be checked via the Replicator resource metadata endpoint.

#Replicating SNS, RDS, VPC, and IAM

A concrete example: replicating resources that are often application dependencies. An SNS topic with its attributes, tags, and FIFO settings:

localstack replicator start \
  --resource-identifier arn:aws:sns:us-east-1:123456789012:notifications \
  --resource-type AWS::SNS::Topic

An RDS instance:

localstack replicator start \
  --resource-identifier db-PROD-01 --resource-type AWS::RDS::DBInstance

An IAM role (TREE mode also pulls in related policies):

localstack replicator start \
  --resource-identifier app-service-role --resource-type AWS::IAM::Role

And a VPC subnet — run it per resource, or use batch mode for several subnets at once:

localstack replicator start \
  --resource-identifier subnet-09a7b4d46eb9caf3c \
  --resource-type AWS::EC2::Subnet

#Cross-Region Discovery

Replicator discovers resources based on the region configured via AWS_DEFAULT_REGION. For resources in another region, switch the region and submit a new job:

export AWS_DEFAULT_REGION=eu-central-1
localstack replicator start \
  --resource-identifier vpc-0abc123def456 --resource-type AWS::EC2::VPC

This way, multi-region resources can be pulled into a single local instance for centralized testing.

#Regression Testing with Real Data

Replicator's main benefit: regression testing with real configuration. Imagine IaC that references the VPC ID and subnet IDs belonging to another team's stack. Without Replicator, a local deploy fails because the resources don't exist; with Replicator, the deploy runs smoothly because the IDs are exactly the same.

A common team pattern is replicate-on-demand: deploy the app in LocalStack, notice a "resource not found" error, replicate the resource in question, then redeploy. This flow is best written as a script or Makefile so it can be repeated anytime.

#!/usr/bin/env bash
set -euo pipefail
for res in "vpc-05208447cff1e3482 AWS::EC2::VPC" \
           "subnet-09a7b4d46eb9caf3c AWS::EC2::Subnet" \
           "sg-0f1e2d3c4b5a69788 AWS::EC2::SecurityGroup"; do
  set -- $res
  localstack replicator start --resource-identifier "$1" --resource-type "$2"
done

#Limitations to Know

A few important notes:

• Replicator copies resource metadata and configuration at the API level — not the data inside them, like database contents or S3 objects.
• It requires AWS credentials with read permissions; never use production credentials.
• Resource coverage depends on the version — check the documentation and changelog for the latest list.
• The process runs asynchronously, so always monitor the job status before relying on the result.

#Closing

Summary of AWS Replicator:

• A Pro feature that copies real AWS resources into LocalStack at the API level, with exactly the same IDs.
• A two-step flow: localstack replicator start then localstack replicator status.
• Single, TREE, and BATCH strategies adapt to resource dependencies.
• Perfect for regression testing IaC that depends on shared resources, including cross-Region ones.

Now that the local environment can mimic production, it's time to automate its testing. In the next episode 18 we discuss CI/CD Integration: LocalStack as a service container in GitHub Actions, parallelism, image caching, and integration with pytest, Jest, Mocha, and testcontainers. See you there!