Replicate an AWS Secrets Manager secret to other AWS Regions

You can replicate your secrets in multiple AWS Regions to support applications spread across those Regions to meet Regional access and low latency requirements. If you later need to, you can promote a replica secret to a standalone and then set it up for replication independently. Secrets Manager replicates the encrypted secret data and metadata such as tags and resource policies across the specified Regions.

The ARN for a replicated secret is the same as the primary secret except for the Region, for example:

• Primary secret: arn:aws:secretsmanager:Region1:123456789012:secret:MySecret-a1b2c3

• Replica secret: arn:aws:secretsmanager:Region2:123456789012:secret:MySecret-a1b2c3

For pricing information for replica secrets, see AWS Secrets Manager Pricing.

When you store database credentials for a source database that is replicated to other Regions, the secret contains connection information for the source database. If you then replicate the secret, the replicas are copies of the source secret and contain the same connection information. You can add additional key/value pairs to the secret for regional connection information.

If you turn on rotation for your primary secret, Secrets Manager rotates the secret in the primary Region, and the new secret value propagates to all of the associated replica secrets. You don't have to manage rotation individually for all of the replica secrets.

You can replicate secrets across all of your enabled AWS Regions. However, if you use Secrets Manager in special AWS Regions such as AWS GovCloud (US) or China Regions, you can only configure secrets and the replicas within these specialized AWS Regions. You can't replicate a secret in your enabled AWS Regions to a specialized Region or replicate secrets from a specialized region to a commercial region.

Before you can replicate a secret to another Region, you must enable that Region. For more information, see Managing AWS Regions.

It is possible to use a secret across multiple Regions without replicating it by calling the Secrets Manager endpoint in the Region where the secret is stored. For a list of endpoints, see AWS Secrets Manager endpoints. To use replication to improve your workload's resilience, see Disaster Recovery (DR) Architecture on AWS, Part I: Strategies for Recovery in the Cloud.

Secrets Manager generates a CloudTrail log entry when you replicate a secret. For more information, see Log AWS Secrets Manager events with AWS CloudTrail.

To replicate a secret to other Regions (console)

1. Open the Secrets Manager console at https://console.aws.amazon.com/secretsmanager/.

2. From the list of secrets, choose your secret.

3. On the secret details page, on the Replication tab, do one of the following:

   • If your secret is not replicated, choose Replicate secret.

   • If your secret is replicated, in the Replicate secret section, choose Add Region.

4. In the Add replica regions dialog box, do the following:

   1. For AWS Region, choose the Region you want to replicate the secret to.

   2. (Optional) For Encryption key, choose a KMS key to encrypt the secret with. The key must be in the replica Region.

   3. (Optional) To add another Region, choose Add more regions.

   4. Choose Replicate.

   You return to the secret details page. In the Replicate secret section, the Replication status shows for each Region.

AWS CLI

Example Replicate a secret to another region

The following replicate-secret-to-regions example replicates a secret to eu-west-3. The replica is encrypted with the AWS managed key aws/secretsmanager.

aws secretsmanager replicate-secret-to-regions \
    --secret-id MyTestSecret \
    --add-replica-regions Region=eu-west-3

AWS SDK

To replicate a secret, use the ReplicateSecretToRegions command. For more information, see AWS SDKs.

Troubleshooting

The following are some reasons that replication can fail.

A secret with the same name exists in the selected Region

To resolve this issue, you can overwrite the duplicate name secret in the replica Region. Retry replication, and then in the Retry replication dialog box, choose Overwrite.

No permissions available on the KMS key to complete the replication

Secrets Manager first decrypts the secret before re-encrypting with the new KMS key in the replica Region. If you don't have kms:Decrypt permission to the encryption key in the primary Region, you will encounter this error. To encrypt the replicated secret with a KMS key other than aws/secretsmanager, you need kms:GenerateDataKey and kms:Encrypt to the key. See Permissions for the KMS key.

The KMS key is disabled or not found

If the encryption key in the primary Region is disabled or deleted, Secrets Manager can't replicate the secret. This error can occur even if you have changed the encryption key, if the secret has custom labelled versions that were encrypted with the disabled or deleted encryption key. For information about how Secrets Manager does encryption, see Secret encryption and decryption in AWS Secrets Manager. To work around this issue, you can recreate the secret versions so that Secrets Manager encrypts them with the current encryption key. For more information, see Change the encryption key for a secret. Then retry replication.

aws secretsmanager put-secret-value \
    --secret-id testDescriptionUpdate \
    --secret-string "SecretValue" \
    --version-stages "MyCustomLabel"

You have not enabled the Region where the replication occurs

For information about how to enable a Region, see Managing AWS Regions. in the AWS Account Management Reference Guide.