Short description

Note: You can use Amazon S3 replication only for general purpose buckets. You can’t use replication for directory buckets and table buckets.

To troubleshoot Amazon S3 objects that don’t replicate for cross-Region replication (CRR) or same-Region replication (SRR), check your destination bucket permissions. Also, check the public access settings and bucket ownership settings.

After you resolve the issues that caused the replication to fail, there might be objects in the source bucket that still don’t replicate. By default, Amazon S3 replication doesn’t replicate existing objects or objects with a FAILED or REPLICA replication status. To check the replication status of objects, see How do I view objects that failed replication from one Amazon S3 bucket to another? For these objects, use S3 Batch Replication.

Resolution

Identify replication setup issues

Upload an object to the source bucket to test the replication after each configuration change. It’s a best practice to change one configuration at a time to identify any replication setup issues.

Also, activate the s3:Replication:OperationFailedReplication event type notification to determine the cause of the failure.

Grant the minimum Amazon S3 permissions

Confirm that the AWS Identity Access Management (IAM) role that you used in the replication rule has the correct permissions. If the source and destination buckets are in different AWS accounts, then confirm that the destination account’s bucket policy grants permissions to the replication role. The following example IAM policy has the minimum required permissions for replication:

{    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetReplicationConfiguration",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::SourceBucket"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObjectVersionForReplication",
                "s3:GetObjectVersionAcl",
                "s3:GetObjectVersionTagging"
            ],
            "Resource": [
                "arn:aws:s3:::SourceBucket/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ReplicateObject",
                "s3:ReplicateTags"
            ],
            "Resource": "arn:aws:s3:::DestinationBucket/*"
        }
    ]
}

Note: Replace SourceBucket with your source bucket and DestinationBucket with your destination bucket.

Based on the replication rule options, you might need to grant additional permissions.

The IAM role must have a trust policy that allows Amazon S3 to assume the role to replicate objects. Example trust policy:

{    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "s3.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Grant additional Amazon S3 permissions

If you set the replication rule to Change object ownership to the destination bucket owner, then you must configure additional permissions.

Note: If the destination bucket’s object ownership is Bucket owner enforced, then you don’t need Change object ownership to the destination bucket owner in the replication rule. The change occurs by default.

To grant the IAM role the s3:ObjectOwnerOverrideToBucketOwner permissions, add the following permission to the Amazon S3 object policy:

{    "Effect": "Allow",
    "Action": [
        "s3:ObjectOwnerOverrideToBucketOwner"
    ],
    "Resource": "arn:aws:s3:::DestinationBucket/*"
}

Note: Replace DestinationBucket with your destination bucket.

Also, add the following s3:ObjectOwnerOverrideToBucketOwner permission in the bucket policy for the destination account:

{    "Sid": "1",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::SourceBucket-account-ID:role/service-role/source-account-IAM-role"
    },
    "Action": [
        "s3:ObjectOwnerOverrideToBucketOwner"
    ],
    "Resource": "arn:aws:s3:::DestinationBucket/*"
}

Note: Replace SourceBucket-account-ID with the source bucket account, source-account-IAM-role with the source account IAM role, and DestinationBucket with the destination bucket.

If you activated delete marker replication on the replication rule, then the IAM role must have the following s3:ReplicateDelete permissions:

{    "Effect": "Allow",
    "Action": [
        "s3:ReplicateDelete"
    ],
    "Resource": "arn:aws:s3:::DestinationBucket/*"
}

Note: Replace DestinationBucket with your destination bucket.

If the destination bucket is in another account, then the destination bucket owner must also add the following permission in the bucket policy:

{    "Version": "2012-10-17",
    "Id": "PolicyForDestinationBucket",
    "Statement": [
        {
            "Sid": "Permissions on objects",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::SourceBucket-account-ID:role/service-role/source-account-IAM-role"
            },
            "Action": [
                "s3:ReplicateObject",
                "s3:ReplicateTags",
                "s3:ObjectOwnerOverrideToBucketOwner",
                "s3:ReplicateDelete"
            ],
            "Resource": "arn:aws:s3:::DestinationBucket/*"
        },
        {
            "Sid": "Permissions on bucket",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::SourceBucket-account-ID:role/service-role/source-account-IAM-role"
            },
            "Action": [
                "s3:GetBucketVersioning",
                "s3:PutBucketVersioning"
            ],
            "Resource": "arn:aws:s3:::DestinationBucket"
        }
        
    ]
}

Note: Replace arn:aws:iam::SourceBucket-account-ID:role/service-role/source-account-IAM-role with the Amazon Resource Name (ARN) of your replication role and DestinationBucket with your destination bucket.

Grant AWS KMS permissions

If you encrypted the bucket’s source objects with an AWS Key Management Service (AWS KMS) key, then the replication rule must include AWS KMS encryption.

To configure the required permissions, complete the following steps:

1. Open the Amazon S3 console.
2. Choose the source bucket.
3. Choose the Management tab, and then under Replication rules choose the replication rule.
4. Choose Edit.
5. Under Encryption, choose Replicate objects encrypted with AWS KMS.
6. Under AWS KMS key for encrypting destination objects, select an AWS KMS key. The default option is to use the AWS KMS key (aws/S3).

For example replication policies, see Example policies – Using SSE-S3 and SSE-KMS with replication.

Note: If the destination bucket is in a different account, then specify an AWS KMS customer managed key that the destination account owns. The default aws/S3 key encrypts the objects with the AWS managed key that the source account owns. However, you can’t share the AWS managed key with another account.

Grant additional AWS KMS permissions for cross-account scenarios

To use the destination account’s AWS KMS key to encrypt the destination objects, the destination account must allow the replication role in the key policy. Example policy:

{    "Sid": "AllowS3ReplicationSourceRoleToUseTheKey",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::SourceBucket-account-ID:role/service-role/source-account-IAM-role"
    },
    "Action": [
        "kms:GenerateDataKey",
        "kms:Encrypt"
    ],
    "Resource": "*"
}