How do I troubleshoot cross-account Amazon S3 replication issues?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Check the IAM policy that's associated with the replication IAM role

To resolve Amazon S3 replication failures, make sure that you grant the correct permissions.

If your source bucket object contains tags, then make sure that the policies for the replication AWS Identity and Access Management (IAM) role and destination bucket allow the s3:ReplicateTags action.

If you set the replication rule to Change object ownership to the destination bucket owner, then the IAM role must have the s3:ObjectOwnerOverrideToBucketOwner permission.

The S3 replication rule automatically creates the replication IAM role with the required permissions.

Example IAM policy for a replication IAM role:

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "s3:GetReplicationConfiguration",
            "s3:ListBucket"
         ],
         "Resource":[
            "arn:aws:s3:::amzn-s3-demo-source-bucket"
         ]
      },
      {
         "Effect":"Allow",
         "Action":[
            "s3:GetObjectVersionForReplication",
            "s3:GetObjectVersionAcl",
            "s3:GetObjectVersionTagging"
         ],
         "Resource":[
            "arn:aws:s3:::amzn-s3-demo-source-bucket/"
         ]
      },
      {
         "Effect":"Allow",
         "Action":[
            "s3:ReplicateObject",
            "s3:ReplicateDelete",
            "s3:ReplicateTags",
            "s3:ObjectOwnerOverrideToBucketOwner"
         ],
         "Resource":"arn:aws:s3:::amzn-s3-demo-destination-bucket/"
      }
   ]
}

If you manually create the IAM role, then create a trust policy to allow Amazon S3 to assume the role. Then, use the IAM console or the AWS CLI to attach the policy.

Example trust policy:

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

Add the necessary permissions to the destination bucket policy

Make sure that the destination bucket policy allows the source account's replication IAM role to replicate objects.

Add the following permissions to the bucket policy:

• s3:ReplicateDelete
• s3:ReplicateObject
• s3:ReplicateTags
• s3:ObjectOwnerOverrideToBucketOwner

Example destination bucket policy:

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

Specify AWS KMS key permissions

To use server-side encryption with AWS Key Management Service (AWS KMS) keys (SSE-KMS), you must specify the destination account's AWS KMS key in the replication rule. Also, the AWS KMS key policies must allow the replication IAM role to use the keys for encryption and decryption. For more information see, Add a key policy statement in the local account.

Example replication IAM role policy for SSE-KMS:

{
    "Version": "2012-10-17",
    "Statement": [

        {
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:GenerateDataKey"
            ],
            "Resource": [
                "SourceKmsKeyArn"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:GenerateDataKey",
                "kms:Encrypt"
            ],
            "Resource": [
                "DestinationKmsKeyArn"
            ]
        }
    ]
}

Example destination bucket policy for SSE-KMS:

{
    "Sid": "Allow an external account to use this KMS key",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::444455556666:role/ReplicationIAMRole"
    },
    "Action": [
        "kms:Encrypt"
    ],
    "Resource": "*"
}

If the source or destination AWS KMS key policy grants permission based on the encryption context, then check whether you're using Amazon S3 Bucket Keys.

If you're using Amazon S3 Bucket Keys, then the encryption context must be for the bucket-level resource.

Example policy:

"kms:EncryptionContext:aws:s3:arn": [     "arn:aws:s3:::amzn-s3-demo-source-bucket"     ]
"kms:EncryptionContext:aws:s3:arn": [     "arn:aws:s3:::amzn-s3-demo-destination-bucket"   ]

If you aren't using Amazon S3 Bucket Keys, then the encryption context must be for the object-level resource.

Example policy:

"kms:EncryptionContext:aws:s3:arn": [     "arn:aws:s3:::amzn-s3-demo-source-bucket/*"     ]
"kms:EncryptionContext:aws:s3:arn": [     "arn:aws:s3:::amzn-s3-demo-destination-bucket/*"   ]

Note: In the preceding example policies, replace amzn-s3-demo-source-bucket and amzn-s3-demo-destination-bucket with your source bucket name and destination bucket name.

Check the SCPs for the source and destination accounts 

Make sure that the service control policies (SCPs) in the source and destination accounts don't contain Deny statements.

Related information

Monitoring replication with metrics, event notifications, and statuses

Replicating encrypted objects (SSE-S3, SSE-KMS, DSSE-KMS, SSE-C)

Why aren't my Amazon S3 objects replicating when I set up replication between my buckets?