AWS Replicator

Introduction

Infrastructure deployed on AWS often requires access to shared resources defined externally. For example a VPC defined by another team to contain the application infrastructure. This makes it harder to deploy applications into LocalStack as these resource dependencies must be deployed first. These dependencies may not live in IaC where deployment is easy, or accessing the IaC may not be easy. Some resources may be referred to by ARN, for example Secrets Manager secrets, but these ARNs are partly random meaning that simply creating a new resource in LocalStack will generate a resource with a different ARN.

LocalStack AWS Replicator creates identical copies of AWS resources in a running LocalStack instance. This means that external resources can easily be replicated before deploying the main application, and removes the need to change existing stacks or create custom infrastructure, making LocalStack setup easier.

Note

The AWS Replicator is in a preview state, supporting only selected resources.

Getting started

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

Note

The Replicator is in limited preview and 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.

When the replication is triggered using the LocalStack CLI, which must run in a shell configured to access AWS. Here are some options:

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.

Using the LocalStack CLI

The Replicator CLI is part of the LocalStack CLI.

Follow the installation instructions to set it up.

To start a replication job, get the ARN of the resource to replicate. Then, trigger the job using the command:

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> \
  [--target-account-id <account-id>] \
  [--target-region-name <region-name>]

Note

Resources that supports replicating with arn can be replicated by providing --resource-arn instead of --resource-type and --resource-identifier.

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

You can also trigger batch replication jobs using the --replication-type BATCH flag.

This currently supports the AWS::SSM::Parameter resource type and allows you to replicate all parameters under a given path prefix.

For example, to replicate all parameters under /dev/:

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

The --resource-identifier in this case must be a path prefix (not a wildcard or glob). All parameters under that prefix will be discovered and replicated.

If --replication-type is not specified, the default is SINGLE_RESOURCE.

The command triggers a replication job. The output will look similar to:

{
  "job_id": "50005865-1589-4f6d-a720-c86f5a5dd021",
  "state": "TESTING_CONNECTION",
  "error_message": null,
  "type": "SINGLE_RESOURCE",
  "replication_config": {
    "resource_type": "AWS::SSM::PARAMETER",
    "identifier": "myParameter"
  }
}

Note

• --target-account-id specifies the destination AWS account for replication. If not set, the resource is replicated into account 000000000000.

• --target-region-name specifies the destination AWS region. If not set, the resource is replicated into the default region from the provided credentials.

Using the HTTP API

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

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

Use the following payload:

{
  "replication_type": "SINGLE_RESOURCE",
  "replication_job_config": {
    "resource_type": "<resource-type>",
    "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`
}

To replicate multiple SSM parameters under a shared path, you can use replication_type: "BATCH" with the same resource_type and a path-style identifier.

For example:

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

This triggers a batch replication job that discovers and replicates all SSM parameters under the /dev/ path prefix.

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",
  "error_message": null,
  "type": "SINGLE_RESOURCE",
  "replication_config": {
    "resource_type": "AWS::SSM::PARAMETER",
    "identifier": "myParameter"
  }
}

For a batch replication job, the output may include additional fields indicating how many resources were successfully replicated or failed:

{
  "job_id": "9acdc850-f71b-4474-b138-1668eb8b8396",
  "state": "SUCCEEDED",
  "error_message": null,
  "type": "BATCH",
  "replication_config": {
    "resource_type": "AWS::SSM::Parameter",
    "identifier": "/dev/"
  },
  "result": {
    "resources_succeeded": 2,
    "resources_failed": 0
  }
}

Jobs of type BATCH may include a result object with resources_succeeded and resources_failed fields.

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. This example uses an SSO profile named ls-sandbox for AWS configuration.

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

Configured credentials from the AWS CLI

{
  "job_id": "9acdc850-f71b-4474-b138-1668eb8b8396",
  "state": "TESTING_CONNECTION",
  "error_message": null,
  "type": "SINGLE_RESOURCE",
  "replication_config": {
    "resource_type": "AWS::SSM::PARAMETER",
    "identifier": "myparam"
  }
}

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",
  "error_message": null,
  "type": "SINGLE_RESOURCE",
  "replication_config": {
    "resource_arn": "arn:aws:ssm:eu-central-1:<account-id>:parameter/myparam"
  }
}

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

The project is still in preview state and we welcome feedback and bug reports. We have opened a github issue where you can request and upvote to help us prioritize our efforts and support the resources with the most impact. For any other requests or reports, please open a new github issue.

Tip

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

Resource Type	Service	Identifier	Required Actions	Arn Support
AWS::EC2::SecurityGroup	ec2	GroupId	cloudformation:GetResource ec2:DescribeSecurityGroups	✔️
AWS::EC2::Subnet	ec2	SubnetId	cloudformation:GetResource ec2:DescribeSubnets	✔️
AWS::EC2::VPC	ec2	VpcId	cloudformation:GetResource ec2:DescribeVpcs	✔️
AWS::ECR::Repository	ecr	RepositoryName:<ImageTag[Optional]>	cloudformation:GetResource ecr:BatchCheckLayerAvailability ecr:BatchGetImage ecr:DescribeRepositories ecr:GetAuthorizationToken ecr:GetDownloadUrlForLayer ecr:GetLifecyclePolicy ecr:GetRepositoryPolicy ecr:ListTagsForResource	✔️
AWS::IAM::Policy	iam	Arn	iam:GetPolicy	✔️
AWS::IAM::Role	iam	RoleName	cloudformation:GetResource iam:GetRole	✔️
AWS::KMS::Key	kms	KeyId	kms:DescribeKey kms:ListResourceTags	✔️
AWS::Lambda::LayerVersion	lambda	LayerVersionArn	cloudformation:GetResource lambda:GetLayerVersion	✔️
AWS::Route53::HostedZone	route53	Id	cloudformation:GetResource route53:GetHostedZone route53:ListQueryLoggingConfigs route53:ListTagsForResource	✔️
AWS::SSM::Parameter	ssm	Name	cloudformation:GetResource ssm:DescribeParameters ssm:GetParameters	✔️
AWS::SecretsManager::Secret	secretsmanager	Arn	cloudformation:GetResource secretsmanager:DescribeSecret	✔️