View a markdown version of this page

Monitor cross-account replication - AWS Secrets Manager
Replication status fieldsReplication status valuesDetermine the cause of a failed replicationRecover from a failed replication

Monitor cross-account replication

Cross-account replication is asynchronous. To monitor progress, call DescribeSecret periodically from either account and check the ReplicationStatus field.

Replication status fields

The fields that DescribeSecret returns depend on whether you describe the replica or the primary secret:

  • When you describe the replica secret, Secrets Manager returns CrossAccountPrimary, which contains PrimarySecretARN, ReplicationStatus, and StatusMessage.

  • When you describe the primary secret, Secrets Manager returns CrossAccountReplicas, a list in which each entry contains ReplicaSecretARN, ReplicationRoleARN, ReplicationStatus, and StatusMessage.

The StatusMessage field provides details when replication fails or stalls, for example, when a AWS KMS key permission is missing.

Replication status values

The ReplicationStatus field reports one of the following values:

Pending

Secrets Manager has recorded the replication relationship but has not yet started copying the secret value. Only the replica secret shows this status.

InProgress

Secrets Manager is copying the secret value from the primary to the replica.

InSync

The replica holds the same secret value as the primary.

Failed

Secrets Manager could not complete replication. See Determine the cause of a failed replication.

Detached

One of the two accounts stopped replication, so the primary and replica secrets are no longer linked. For more information, see Stop cross-account replication.

Determine the cause of a failed replication

A Failed status means that Secrets Manager was unable to complete the replication. Review the StatusMessage to determine why replication failed; it contains additional information about the cause. The most common reasons for replication to fail are related to authorization. These failures are usually one of the following:

  • Secrets Manager does not have permission to call kms:Decrypt on the primary KMS key or kms:Encrypt on the replica KMS key.

  • Secrets Manager is unable to assume the replication role.

For AWS KMS failures, review the StatusMessage to identify the source of the failure. If you use a forward access session (FAS) instead of a replication role, verify that the caller's identity has the required kms:Decrypt and kms:Encrypt permissions. For more information about the permissions that replication requires, see How Secrets Manager authorizes cross-account replication.

Example StatusMessage values

The following examples show common StatusMessage values for failed replications.

Example kms:Decrypt denied on the primary secret's key
Replication failed: User: arn:aws:sts::111122223333:assumed-role/CrossAccountReplicationRole-1234567890123456789/SecretsManagerCrossAccountReplication-444455556666 is not authorized to perform: kms:Decrypt on resource: arn:aws:kms:us-west-2:111122223333:key/a8c8999a-a026-4df3-a42a-d0972222fe36 because no resource-based policy allows the kms:Decrypt action (Service: AWSKMS; Status Code: 400; Error Code: AccessDeniedException; Request ID: 12345678-1234-1234-1234-123456781234; Proxy: null)
Example kms:Encrypt denied on the replica secret's key
Replication failed: User: arn:aws:sts::111122223333:assumed-role/CrossAccountReplicationRole-9876543210987654321/SecretsManagerCrossAccountReplication-444455556666 is not authorized to perform: kms:Encrypt on this resource because the resource does not exist in this Region, no resource-based policies allow access, or a resource-based policy explicitly denies access (Service: AWSKMS; Status Code: 400; Error Code: AccessDeniedException; Request ID: 87654321-4321-4321-4321-aaaabbbbcccc; Proxy: null)
Example Unable to assume the replication role
Replication failed: Secrets Manager failed to assume role arn:aws:iam::111122223333:role/CrossAccountReplicationRole

Recover from a failed replication

After you correct the permissions, the primary-account owner calls AssociateCrossAccountReplica again for the same replica to retry replication. This call does not fix permissions; it only re-triggers the replication attempt. If permission issues remain, Secrets Manager will update the StatusMessage. When all permission issues are resolved, replication completes and the status changes to InSync.

Example Retry a failed replication
aws secretsmanager associate-cross-account-replica \
    --secret-id MyPrimarySecret \
    --cross-account-replica-arn arn:aws:secretsmanager:us-east-2:444455556666:secret:MyReplicaSecret-a1b2c3 \
    --replication-role-arn arn:aws:iam::111122223333:role/SecretsManagerCrossAccountReplicationRole