AWS Replicator

Introduction

Applications deployed on AWS often depend on shared resources defined outside their own stack, for example a VPC managed by another team. Replicating this kind of setup in LocalStack is hard: the dependencies may not live in IaC you have access to, and some resources are referenced by ARN, which is partly random, so simply recreating the resource in LocalStack produces a different ARN.

The AWS Replicator solves this by creating identical copies of existing AWS resources directly inside a running LocalStack instance. This lets you replicate external dependencies before deploying your application, without changing existing stacks or building custom bootstrap infrastructure.

Note

The AWS Replicator supports only selected resources.

Getting started

A valid LOCALSTACK_AUTH_TOKEN must be configured to start the LocalStack for AWS image.

Note

The Replicator is available from LocalStack CLI version 4.2.0. If you encounter issues, update your LocalStack CLI.

Retrieve credentials to access AWS

The AWS Replicator needs read access to your AWS account and performs a limited set of read-only operations on supported resources. These operations can be limited by creating a minimal IAM role with just the policy actions required for replication, and providing credentials to assume this role.

See the supported resources section for details of what policy actions are required for each resource.

Replication is triggered from a shell that has access to AWS. Here are some options for providing credentials:

AWS CLI v2

If you have the AWS CLI v2 installed, the CLI will read credentials from your configured AWS_PROFILE.

export AWS_PROFILE=my-aws-profile
localstack replicator ...

AWS CLI v1

If you have the AWS CLI v1 installed or no installation of the AWS CLI, the following environment variables must be set:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN (optional)
• AWS_DEFAULT_REGION

Trigger a replication job

Replication jobs can be triggered using the LocalStack CLI or an HTTP API.

Both methods have two steps:

1. Submit a replication job.
2. Check the job status.

Replication strategies

The Replicator supports different strategies depending on how many resources you want to copy and whether their related resources should be included. The supported resources table shows which strategies are available for each resource type, along with the IAM actions required for each.

• Single (SINGLE_RESOURCE): replicate a single resource identified by its identifier or ARN. This is the default.
• Batch (BATCH): discover and replicate every matching resource in a single job, for example all SSM parameters under a path prefix or all S3 buckets matching a prefix. Only some resource types support batch discovery, check the Batch badge in the supported resources table.
• Tree (TREE explore strategy): starting from a single resource, also replicate its related child resources. For example, replicating an AWS::Organizations::Organization also replicates its organizational units, accounts, and policies.

replication_type (single vs. batch discovery) and explore_strategy (SIMPLE or TREE, whether related resources are followed) are independent settings and can be combined.

Two options apply regardless of strategy:

• Cross-region source discovery: if the resource lives in a different AWS region than your credentials’ default region (or its ARN has no region component, as with S3 buckets), set a source region explicitly.
• Skip existing resources: by default a job fails if the target resource already exists. Set ignore_already_existing to skip it instead and continue the job.

Using the LocalStack CLI

The Replicator CLI is part of the LocalStack CLI. Follow the installation instructions to set it up.

Trigger a job with localstack replicator start, identifying the resource by its CloudControl type and identifier:

export LOCALSTACK_AUTH_TOKEN=<auth token>
export AWS_DEFAULT_REGION=...
# if required
# export AWS_ACCESS_KEY_ID=
# export AWS_SECRET_ACCESS_KEY=
localstack replicator start \
  --resource-type <resource-type> \
  --resource-identifier <identifier>

Or, if you have the resource’s ARN, use --resource-arn instead of --resource-type and --resource-identifier:

localstack replicator start --resource-arn <resource-arn>

The command outputs the new job, including its job_id:

{
  "job_id": "50005865-1589-4f6d-a720-c86f5a5dd021",
  "state": "TESTING_CONNECTION",
  "resources": {"succeeded": [], "failed": [], "skipped": []},
  "error_message": null,
  "type": "SINGLE_RESOURCE",
  "explore_strategy": "SIMPLE"
}

Batch replication: pass --replication-type BATCH to discover and replicate every matching resource in a single job, instead of one resource at a time. Only some resource types support batch discovery, check the Batch badge in the supported resources table. For example, to replicate all SSM parameters under /dev/:

localstack replicator start \
  --replication-type BATCH \
  --resource-type AWS::SSM::Parameter \
  --resource-identifier /dev/

--resource-identifier means something different for each resource type in batch mode: for AWS::SSM::Parameter it’s a path prefix (not a wildcard or glob). Check the supported resources table for the identifier format each resource type expects.

Targeting:

• --target-account-id sets the destination LocalStack account. Defaults to 000000000000.
• --target-region-name sets the destination region. Defaults to the source region.
• --source-region-name sets the AWS region to read the resource from. Use it when the resource lives in a different region than your credentials’ default region, or when its ARN has no region component, as with S3 buckets.

Resource-specific configuration: some resource types accept parameters that aren’t covered by the flags above. Pass them with --extra-config KEY=VALUE (repeat the flag for multiple entries). For example, replicating an AWS::RDS::DBCluster or AWS::RDS::DBInstance accepts a master_user_password:

localstack replicator start \
  --resource-type AWS::RDS::DBCluster \
  --resource-identifier my-cluster \
  --extra-config master_user_password=<password>

Check the supported resources table for which resource types accept extra configuration and which keys they support.

By default, a job fails if the target resource already exists. To skip it instead and continue the job, add --extra-config ignore_already_existing=true.

Using the HTTP API

To trigger replication via the HTTP API, send a POST request to:

http://localhost.localstack.cloud:4566/_localstack/replicator/jobs

with a payload identifying the resource, the replication strategy, and AWS credentials to read it:

{
  "replication_type": "SINGLE_RESOURCE",
  "replication_job_config": {
    "resource_type": "<resource-type>",
    "resource_identifier": "<identifier>"
  },
  "source_aws_config": {
    "aws_access_key_id": "...",
    "aws_secret_access_key": "...",
    "aws_session_token": "...", // optional
    "region_name": "...",
    "endpoint_url": "..." // optional
  },
  "target_aws_config": {} // optional, same shape as `source_aws_config`
}

Use replication_type: "BATCH" to discover and replicate every matching resource instead of one. For example, to replicate all SSM parameters under /dev/:

{
  "replication_type": "BATCH",
  "replication_job_config": {
    "resource_type": "AWS::SSM::Parameter",
    "resource_identifier": "/dev/"
  },
  "source_aws_config": {
    "aws_access_key_id": "...",
    "aws_secret_access_key": "...",
    "region_name": "..."
  }
}

Set explore_strategy to TREE to also replicate a resource’s related resources. For example, to replicate an entire organization tree:

{
  "replication_type": "SINGLE_RESOURCE",
  "explore_strategy": "TREE",
  "replication_job_config": {
    "resource_type": "AWS::Organizations::Organization",
    "resource_identifier": "o-exampleorgid"
  },
  "source_aws_config": {
    "aws_access_key_id": "...",
    "aws_secret_access_key": "...",
    "region_name": "..."
  }
}

When omitted, explore_strategy defaults to SIMPLE, which replicates only the requested resource. The related resources replicated by TREE are listed in the supported resources table, along with the additional IAM actions they require.

replication_job_config also accepts source_region_name and ignore_already_existing, and any resource-specific extra configuration such as master_user_password, as additional keys alongside resource_type/resource_identifier.

To list every replication job instead of one, send a GET request to the same /_localstack/replicator/jobs endpoint without a job ID.

Check Replication Job Status

Replication jobs run asynchronously, so you need to poll their status to check when they finish.

Using the LocalStack CLI

When creating a replication job, the response includes a job_id.

Use this ID to check the job status:

export LOCALSTACK_AUTH_TOKEN=<auth token>

localstack replicator status <job-id>

This command returns the job status in JSON format. For example, here’s a single-resource replication job:

{
  "job_id": "50005865-1589-4f6d-a720-c86f5a5dd021",
  "state": "SUCCEEDED",
  "resources": {"succeeded": ["myParameter"], "failed": [], "skipped": []},
  "error_message": null,
  "type": "SINGLE_RESOURCE",
  "explore_strategy": "SIMPLE"
}

state is one of TESTING_CONNECTION, RUNNING, SUCCEEDED, or ERROR. resources lists the identifiers of resources that succeeded, failed, or were skipped (see ignore_already_existing above) — for a single-resource job these lists have at most one entry, for a batch job they can have many:

{
  "job_id": "9acdc850-f71b-4474-b138-1668eb8b8396",
  "state": "SUCCEEDED",
  "resources": {
    "succeeded": ["/dev/param1", "/dev/param2"],
    "failed": [],
    "skipped": []
  },
  "error_message": null,
  "type": "BATCH",
  "explore_strategy": "SIMPLE"
}

For long-running jobs, the CLI can poll the status until the job reaches a terminal state. To wait for the job to finish, use the --follow flag.

Using the HTTP API

To check the status of a replication job via the HTTP API, send a GET request to http://localhost.localstack.cloud:4566/_localstack/replicator/jobs/<job-id>.

Tip

If the replication state is SUCCEEDED but the resource is missing, check in account 000000000000.

Quickstart

This quickstart example creates an SSM parameter in AWS and replicates it to LocalStack.

To start, create the parameter in AWS. This example uses an SSO profile named ls-sandbox for AWS configuration, and replicates resources from the eu-central-1 region.

AWS_PROFILE=ls-sandbox aws ssm put-parameter\
  --name myparam \
  --type String \
  --value abc123

{
    "Version": 1,
    "Tier": "Standard"
}

AWS_PROFILE=ls-sandbox aws ssm get-parameters --names myparam

{
    "Parameters": [
        {
            "Name": "myparam",
            "Type": "String",
            "Value": "abc123",
            "Version": 1,
            "LastModifiedDate": "2025-02-07T13:36:56.240000+00:00",
            "ARN": "arn:aws:ssm:eu-central-1:<account-id>:parameter/myparam",
            "DataType": "text"
        }
    ],
    "InvalidParameters": []
}

The SSM parameter has the ARN: arn:aws:ssm:eu-central-1:<account-id>:parameter/myparam.

Next, we can check that the parameter is not present in LocalStack using awslocal:

awslocal ssm get-parameters --name myparam

{
    "Parameters": [],
    "InvalidParameters": [
        "myparam"
    ]
}

Next, trigger replication from AWS to LocalStack, using the same ls-sandbox profile:

LOCALSTACK_AUTH_TOKEN=<ls-auth-token> \
  AWS_PROFILE=ls-sandbox \
  localstack replicator start \
    --resource-type AWS::SSM::Parameter \
    --resource-identifier myparam

{
  "job_id": "9acdc850-f71b-4474-b138-1668eb8b8396",
  "state": "TESTING_CONNECTION",
  "resources": {"succeeded": [], "failed": [], "skipped": []},
  "error_message": null,
  "type": "SINGLE_RESOURCE",
  "explore_strategy": "SIMPLE"
}

You can check the replication job status using the job_id:

LOCALSTACK_AUTH_TOKEN=<ls-auth-token> \
  localstack replicator status 9acdc850-f71b-4474-b138-1668eb8b8396

{
  "job_id": "9acdc850-f71b-4474-b138-1668eb8b8396",
  "state": "SUCCEEDED",
  "resources": {"succeeded": ["myparam"], "failed": [], "skipped": []},
  "error_message": null,
  "type": "SINGLE_RESOURCE",
  "explore_strategy": "SIMPLE"
}

The state is SUCCEEDED, indicating the replication job completed successfully. The SSM parameter is now accessible.

awslocal ssm get-parameters --name myparam --region eu-central-1

{
    "Parameters": [
        {
            "Name": "myparam",
            "Type": "String",
            "Value": "abc123",
            "Version": 1,
            "LastModifiedDate": 1738935663.08,
            "ARN": "arn:aws:ssm:eu-central-1:000000000000:parameter/myparam",
            "DataType": "text"
        }
    ],
    "InvalidParameters": []
}

The resource is replicated into the same AWS region by default. Use the --target-region-name flag to change it. By default, replication occurs in LocalStack account 000000000000. Use the --target-account-id flag to specify a different account.

Supported Resources

We welcome feedback and bug reports. Please open a new GitHub Discussion to request and upvote for support for new resources.

Tip

To ensure support for all resources, use the latest LocalStack Docker image.

The table below lists every supported resource type and the replication strategies available for each. Select a row to expand it and view the resource identifier, the IAM actions required for each strategy, and any related resources replicated by the Tree strategy.

SingleReplicate one resource at a time by identifier or ARN.BatchDiscover and replicate many matching resources in one job.TreeUse the TREE explore strategy to also replicate related child resources.

Resource TypeServiceReplication Strategies

AWS::DynamoDB::TableService:dynamodb

SingleBatchTree

AWS::EC2::SecurityGroupService:ec2

SingleBatchTree

AWS::EC2::SubnetService:ec2

SingleBatchTree

AWS::EC2::VPCService:ec2

SingleBatchTree

AWS::ECR::RepositoryService:ecr

SingleBatchTree

AWS::IAM::PolicyService:iam

SingleBatchTree

AWS::IAM::RoleService:iam

SingleBatchTree

AWS::KMS::KeyService:kms

SingleBatchTree

AWS::Lambda::LayerVersionService:lambda

SingleBatchTree

AWS::Organizations::AccountService:organizations

SingleBatchTree

AWS::Organizations::OrganizationService:organizations

SingleBatchTree

AWS::Organizations::OrganizationalUnitService:organizations

SingleBatchTree

AWS::Organizations::PolicyService:organizations

SingleBatchTree

AWS::RDS::DBClusterService:rds

SingleBatchTree

AWS::RDS::DBInstanceService:rds

SingleBatchTree

AWS::Route53::HostedZoneService:route53

SingleBatchTree

AWS::S3::BucketService:s3

SingleBatchTree

AWS::SNS::SubscriptionService:sns

SingleBatchTree

AWS::SNS::TopicService:sns

SingleBatchTree

AWS::SSM::ParameterService:ssm

SingleBatchTree

AWS::SecretsManager::SecretService:secretsmanager

SingleBatchTree