# Replicate AWS Secrets Manager secrets across Regions Multi-region replication 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](standalone-secret.md) 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](https://aws.amazon.com/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.](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html#rande-manage-enable) 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](asm_access.md#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](https://aws.amazon.com/blogs/architecture/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](monitoring-cloudtrail.md). **To replicate a secret to other Regions (console)** 1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/). 1. From the list of secrets, choose your secret. 1. 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**. 1. In the **Add replica regions** dialog box, do the following: 1. For **AWS Region**, choose the Region you want to replicate the secret to. 1. (Optional) For **Encryption key**, choose a KMS key to encrypt the secret with. The key must be in the replica Region. 1. (Optional) To add another Region, choose **Add more regions**. 1. 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 [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/replicate-secret-to-regions.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/replicate-secret-to-regions.html) 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 ``` **Example Create a secret and replicate it** The following [ example ](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/create-secret.html) creates a secret and replicates it to eu-west-3. The replica is encrypted with the AWS managed key **aws/secretsmanager**. ``` aws secretsmanager create-secret \ --name MyTestSecret \ --description "My test secret created with the CLI." \ --secret-string "{\"user\":\"diegor\",\"password\":\"EXAMPLE-PASSWORD\"}" --add-replica-regions Region=eu-west-3 ``` ## AWS SDK To replicate a secret, use the [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_ReplicateSecretToRegions.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_ReplicateSecretToRegions.html) command. For more information, see [AWS SDKs](asm_access.md#asm-sdks). # Promote a replica secret to a standalone secret in AWS Secrets Manager Promote a replica secret to a standalone secret A replica secret is a secret that is replicated from a primary in another AWS Region. It has the same secret value and metadata as the primary, but it can be encrypted with a different KMS key. A replica secret can't be updated independently from its primary secret, except for its encryption key. Promoting a replica secret disconnects the replica secret from the primary secret and makes the replica secret a standalone secret. Changes to the primary secret won't replicate to the standalone secret. You might want to promote a replica secret to a standalone secret as a disaster recovery solution if the primary secret becomes unavailable. Or you might want to promote a replica to a standalone secret if you want to turn on rotation for the replica. If you promote a replica, be sure to update the corresponding applications to use the standalone secret. Secrets Manager generates a CloudTrail log entry when you promote a secret. For more information, see [Log AWS Secrets Manager events with AWS CloudTrail](monitoring-cloudtrail.md). **To promote a replica secret (console)** 1. Log in to the Secrets Manager at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/). 1. Navigate to the replica region. 1. On the **Secrets** page, choose the replica secret. 1. On the replica secret details page, choose **Promote to standalone secret**. 1. In the **Promote replica to standalone secret** dialog box, enter the Region and then choose **Promote replica**. ## AWS CLI **Example Promote a replica secret to a primary** The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/stop-replication-to-replica.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/stop-replication-to-replica.html) example removes the link between a replica secret to the primary. The replica secret is promoted to a primary secret in the replica region. You must call [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/stop-replication-to-replica.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/stop-replication-to-replica.html) from within the replica region. ``` aws secretsmanager stop-replication-to-replica \ --secret-id MyTestSecret ``` ## AWS SDK To promote a replica to a standalone secret, use the [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_StopReplicationToReplica.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_StopReplicationToReplica.html) command. You must call this command from the replica secret Region. For more information, see [AWS SDKs](asm_access.md#asm-sdks). # Prevent AWS Secrets Manager replication Prevent replication Because secrets can be replicated using [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_ReplicateSecretToRegions.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_ReplicateSecretToRegions.html) or when they are created using [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html), if you want to prevent users from replicating secrets, we recommend you prevent actions that contain the `AddReplicaRegions` parameter. You can use a `Condition` statement in your permission policies to only allow actions that don't add replica regions. See the following policy examples for Condition statements you can use. **Example Prevent replication permission** The following policy example shows how to allow all actions that don't add replica regions. This prevents users from replicating secrets through both `ReplicateSecretToRegions` and `CreateSecret`. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "secretsmanager:*", "Resource": "*", "Condition": { "Null": { "secretsmanager:AddReplicaRegions": "true" } } } ] } ``` **Example Allow replication permission only to specific Regions** The following policy shows how to allow all of the following: + Create secrets without replication + Create secrets with replication to Regions only in United States and Canada + Replicate secrets to Regions only in United States and Canada **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:CreateSecret", "secretsmanager:ReplicateSecretToRegions" ], "Resource": "*", "Condition": { "ForAllValues:StringLike": { "secretsmanager:AddReplicaRegions": [ "us-*", "ca-*" ] } } } ] } ``` # Troubleshoot AWS Secrets Manager replication Troubleshoot replication AWS Secrets Manager replication might fail for various reasons. To check why a secret failed to replicate, you can do one of the following: + Call the `DescribeSecret` API operation + Review AWS CloudTrail events When replication fails: + If there are no usable secret versions, Secrets Manager removes the secret from the replica Region. + If there are successfully replicated secret versions, they remain in the replica Region until you explicitly remove them using the `RemoveRegionsFromReplication` API operation. The following sections describe some common reasons for replication failures. ## 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](security-encryption.md#security-encryption-authz). ## 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](whats-in-a-secret.md#term_version) 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](security-encryption.md). 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](manage_update-encryption-key.md#manage_update-encryption-key_CLI). 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.](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html#rande-manage-enable) in the *AWS Account Management Reference Guide*.