복제 문제 해결하기

이 섹션은 Amazon S3 Replication에 대한 문제 해결 팁과 S3 Batch Replication 오류에 대한 정보를 정리해요.

출처: 문서

S3 Replication 문제 해결 팁

복제를 구성한 뒤 객체 복제본이 대상 버킷에 나타나지 않으면 다음 문제 해결 팁으로 문제를 식별하고 해결해 보세요.

대부분의 객체는 15분 안에 복제돼요. Amazon S3가 객체를 복제하는 데 걸리는 시간은 소스·대상 리전 쌍과 객체 크기 등 여러 요인에 따라 달라집니다. 큰 객체의 경우 복제에 몇 시간까지 걸릴 수 있어요. 복제 시간에 대한 가시성을 얻으려면 *S3 Replication Time Control(S3 RTC)*을 사용할 수 있어요.
복제 중인 객체가 크다면 대상에 나타나는지 확인하기 전에 잠시 기다리세요. 소스 객체의 복제 상태도 확인할 수 있어요. 객체 복제 상태가 PENDING이면 Amazon S3가 아직 복제를 완료하지 않은 거예요. 상태가 FAILED라면 소스 버킷에 설정된 복제 구성을 확인하세요.
복제 중 실패에 대한 정보를 받으려면 Amazon S3 Event Notifications 복제를 설정해서 실패 이벤트를 받을 수도 있어요. 자세한 내용은 Amazon S3 Event Notifications로 복제 실패 이벤트 받기 문서를 참고하세요.
객체의 복제 상태를 확인하려면 HeadObject API 작업을 호출할 수 있어요. HeadObject API 작업은 객체의 PENDING, COMPLETED, FAILED 복제 상태를 반환합니다. HeadObject API 호출 응답에서 복제 상태는 x-amz-replication-status 헤더로 반환돼요.
- 참고: HeadObject를 실행하려면 요청하는 객체에 대한 읽기 액세스가 있어야 해요. HEAD 요청은 GET 요청과 같은 옵션을 가지되 GET 작업을 수행하지는 않아요. 예를 들어 AWS Command Line Interface(AWS CLI)로 HeadObject 요청을 실행하려면 다음 명령을 실행할 수 있어요. user input placeholders를 자신의 정보로 바꾸세요.

aws s3api head-object --bucket amzn-s3-demo-source-bucket --key index.html

HeadObject가 FAILED 복제 상태의 객체를 반환한다면 S3 Batch Replication을 사용해 그 실패한 객체들을 복제할 수 있어요. 자세한 내용은 Batch Replication으로 기존 객체 복제 문서를 참고하세요. 또는 실패한 객체를 소스 버킷에 다시 업로드해서 새 객체에 대한 복제를 시작할 수도 있어요.
- 참고: 복제 규칙이 객체 소유권을 대상 버킷 소유자로 변경 옵션을 사용하고 객체가 대상 버킷에 있는데 FAILED 복제 상태를 보여준다면 S3 Batch Replication이 이 상태를 해결하지 못할 수 있어요. 이 상황이 발생하면 AWS Support에 문의해서 영향을 받는 객체의 복제 상태를 확인하세요.
소스 버킷의 복제 구성에서 다음을 확인해요.
- 대상 버킷의 Amazon 리소스 이름(ARN)이 올바른지 확인합니다.
- 키 이름 접두사가 올바른지 확인해요. 예를 들어 Tax 접두사를 가진 객체를 복제하도록 구성을 설정했다면 Tax/document1이나 Tax/document2 같은 키 이름을 가진 객체만 복제됩니다. document3 키 이름을 가진 객체는 복제되지 않아요.
- 복제 규칙의 상태가 Enabled인지 확인합니다.
복제 구성의 어떤 버킷에서도 버전 관리가 일시 중지되지 않았는지 확인해요. 소스 버킷과 대상 버킷 모두 버전 관리가 활성화되어 있어야 합니다.
복제 규칙이 객체 소유권을 대상 버킷 소유자로 변경으로 설정되어 있다면 복제에 사용되는 AWS Identity and Access Management(IAM) 역할에 s3:ObjectOwnerOverrideToBucketOwner 권한이 있어야 해요. 이 권한은 리소스(이 경우 대상 버킷)에 대해 부여됩니다. 예를 들어 다음 Resource 문장은 대상 버킷에 이 권한을 부여하는 방법을 보여줘요.

{
   "Effect":"Allow",
   "Action":[
      "s3:ObjectOwnerOverrideToBucketOwner"
   ],
   "Resource":"arn:aws:s3:::amzn-s3-demo-destination-bucket/*"
}

대상 버킷이 다른 계정이 소유한다면 대상 버킷 소유자도 대상 버킷 정책을 통해 소스 버킷 소유자에게 s3:ObjectOwnerOverrideToBucketOwner 권한을 부여해야 해요. 다음 예시 버킷 정책을 쓰려면 user input placeholders를 자신의 정보로 바꾸세요.

{
   "Version":"2012-10-17",
   "Id": "Policy1644945280205",
   "Statement": [
      {
         "Sid": "Stmt1644945277847",
         "Effect": "Allow",
         "Principal":{
            "AWS": "arn:aws:iam::123456789101:role/s3-replication-role"
         },
         "Action": [
            "s3:ReplicateObject",
            "s3:ReplicateTags",
            "s3:ObjectOwnerOverrideToBucketOwner"
         ],
         "Resource": "arn:aws:s3:::amzn-s3-demo-destination-bucket/*"
      }
   ]
}

참고: 대상 버킷의 객체 소유권 설정에 Bucket owner enforced가 포함되어 있다면 복제 규칙에서 객체 소유권을 대상 버킷 소유자로 변경으로 설정을 변경할 필요가 없어요. 객체 소유권 변경은 기본으로 발생합니다. 복제본 소유권 변경에 대한 자세한 내용은 복제본 소유자 변경 문서를 참고하세요.
계정 간 시나리오, 즉 소스·대상 버킷이 서로 다른 AWS 계정에 속할 때 복제 구성을 설정한다면 대상 버킷을 Requester Pays 버킷으로 구성할 수 없어요. 자세한 내용은 스토리지 전송과 사용을 위한 Requester Pays 일반 목적 버킷 사용 문서를 참고하세요.
버킷의 소스 객체가 AWS KMS 키(SSE-KMS)를 사용한 서버 측 암호화로 암호화되어 있다면 복제 규칙에 AWS KMS로 암호화된 객체가 포함되도록 구성해야 해요. Amazon S3 콘솔의 암호화(Encryption) 설정에서 AWS KMS로 암호화된 객체 복제를 선택했는지 확인하고, 대상 객체를 암호화할 AWS KMS 키를 선택해요.
- 참고: 대상 버킷이 다른 계정에 있다면 대상 계정이 소유한 AWS KMS 고객 관리형 키를 지정하세요. 기본 Amazon S3 관리형 키(aws/s3)는 사용하지 마세요. 기본 키를 사용하면 소스 계정이 소유한 Amazon S3 관리형 키로 객체를 암호화해서 객체를 다른 계정과 공유할 수 없게 되고, 결과적으로 대상 계정이 대상 버킷의 객체에 액세스할 수 없어요.
대상 계정에 속한 AWS KMS 키로 대상 객체를 암호화하려면 대상 계정이 KMS 키 정책에서 복제 역할에 kms:GenerateDataKey와 kms:Encrypt 권한을 부여해야 해요. KMS 키 정책에서 다음 예시 문장을 쓰려면 user input placeholders를 자신의 정보로 바꾸세요.

{
   "Sid": "AllowS3ReplicationSourceRoleToUseTheKey",
   "Effect": "Allow",
   "Principal":{
      "AWS": "arn:aws:iam::123456789101:role/s3-replication-role"
   },
   "Action": ["kms:GenerateDataKey", "kms:Encrypt"],
   "Resource": "*"
}

AWS KMS 키 정책의 Resource 문장에 별표(*)를 사용하면 정책이 KMS 키를 사용할 권한을 복제 역할에만 부여해요. 이 정책은 복제 역할이 자신의 권한을 높일 수 있게 하지는 않습니다.
기본적으로 KMS 키 정책은 루트 사용자에게 키에 대한 전체 권한을 부여해요. 이 권한은 같은 계정의 다른 사용자에게 위임할 수 있어요. 소스 KMS 키 정책에 Deny 문장이 없다면 IAM 정책으로 복제 역할에 소스 KMS 키 권한을 부여하는 것으로 충분합니다.
참고: 특정 CIDR 범위, 가상 사설 클라우드(VPC) 엔드포인트, S3 액세스 포인트로 액세스를 제한하는 KMS 키 정책은 복제를 실패하게 할 수 있어요.
소스 KMS 키나 대상 KMS 키가 암호화 컨텍스트를 기준으로 권한을 부여한다면 버킷에 Amazon S3 Bucket Keys가 켜져 있는지 확인해요. 버킷에 S3 Bucket Keys가 켜져 있다면 암호화 컨텍스트는 버킷 수준 리소스여야 해요. 아래처럼 말이죠.

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

KMS 키 정책이 부여한 권한 외에도 소스 계정은 복제 역할의 IAM 정책에 다음 최소 권한을 추가해야 해요.

{
   "Effect": "Allow",
   "Action": [
       "kms:Decrypt",
       "kms:GenerateDataKey"
   ],
   "Resource": [
       "Source-KMS-Key-ARN"
   ]
},
{
   "Effect": "Allow",
   "Action": [
       "kms:GenerateDataKey",
       "kms:Encrypt"
   ],
   "Resource": [
       "Destination-KMS-Key-ARN"
   ]
}

중요: S3 Batch Replication으로 데이터 세트를 리전 간에 복제하는데 객체의 서버 측 암호화 유형이 이전에 SSE-S3에서 SSE-KMS로 변경된 적이 있다면 추가 권한이 필요할 수 있어요. 소스 리전 버킷에는 kms:decrypt 권한이 있어야 하고, 대상 리전의 버킷에는 kms:decrypt와 kms:encrypt 권한이 필요합니다.
AWS KMS로 암호화된 객체를 복제하는 방법에 대한 자세한 내용은 암호화된 객체 복제 문서를 참고하세요.
대상 버킷이 다른 AWS 계정이 소유한다면 버킷 소유자가 대상 버킷에 소스 버킷 소유자가 객체를 복제할 수 있게 하는 버킷 정책을 갖고 있는지 확인해요. 예시는 다른 계정의 버킷 복제 구성하기 문서를 참고하세요.
복제에 Object Lock을 쓰려면 복제를 설정할 때 사용하는 AWS Identity and Access Management(IAM) 역할의 소스 S3 버킷에 두 가지 추가 권한을 부여해야 해요. 그 두 권한은 s3:GetObjectRetention과 s3:GetObjectLegalHold예요. 역할에 s3:Get* 권한 문장이 있다면 그 문장으로 요구 사항을 충족합니다. 자세한 내용은 S3 복제와 함께 Object Lock 사용 문서를 참고하세요.
권한을 검증했는데도 객체가 여전히 복제되지 않는다면 다음 위치에서 명시적인 Deny 문장이 있는지 확인해요.
- 소스 버킷 정책이나 대상 버킷 정책의 Deny 문장. 복제 역할에 대해 다음 작업 중 하나라도 버킷 정책이 액세스를 거부하면 복제가 실패해요.
  - 소스 버킷: s3:GetReplicationConfiguration, s3:ListBucket, s3:GetObjectVersionForReplication, s3:GetObjectVersionAcl, s3:GetObjectVersionTagging
  - 대상 버킷: s3:ReplicateObject, s3:ReplicateDelete, s3:ReplicateTags
- IAM 역할에 연결된 Deny 문장이나 권한 경계는 복제를 실패하게 할 수 있어요.
- 소스 계정이나 대상 계정에 연결된 AWS Organizations 서비스 제어 정책(SCP)의 Deny 문장은 복제를 실패하게 할 수 있어요.
- 소스 버킷이나 대상 버킷에 연결된 AWS Organizations 리소스 제어 정책(RCP)의 Deny 문장은 복제를 실패하게 할 수 있어요.
객체 복제본이 대상 버킷에 나타나지 않는다면 다음 문제 때문에 복제가 막혔을 수 있어요.
- Amazon S3는 다른 복제 구성이 만든 복제본인 소스 버킷의 객체는 복제하지 않아요. 예를 들어 버킷 A에서 버킷 B로, 버킷 B에서 버킷 C로 복제 구성을 설정했다면 Amazon S3는 버킷 B의 객체 복제본을 버킷 C로 복제하지 않습니다.
- 소스 버킷 소유자는 다른 AWS 계정에 객체를 업로드할 권한을 부여할 수 있어요. 기본적으로 소스 버킷 소유자는 다른 계정이 만든 객체에 대한 권한이 없습니다. 복제 구성은 소스 버킷 소유자가 액세스 권한을 가진 객체만 복제해요. 이 문제를 피하려면 소스 버킷 소유자가 다른 AWS 계정에 조건부로 객체를 만들 권한을 부여해서, 그 객체들에 대한 명시적 액세스 권한을 요구하게 할 수 있어요. 예시 정책은 버킷 소유자가 전체 제어권을 갖도록 보장하면서 다른 계정에 객체 업로드 권한 부여 문서를 참고하세요.
복제 구성에서 특정 태그를 가진 객체 하위 집합을 복제하는 규칙을 추가했다고 가정해 볼게요. 이 경우 Amazon S3가 객체를 복제하게 하려면 객체를 만들 때 특정 태그 키와 값을 할당해야 해요. 객체를 먼저 만든 뒤 기존 객체에 태그를 추가하면 Amazon S3는 그 객체를 복제하지 않습니다.
객체가 대상 AWS 리전으로 복제되지 않는 경우를 알려 주도록 Amazon S3 Event Notifications를 사용해요. Amazon S3 Event Notifications는 Amazon Simple Queue Service(Amazon SQS), Amazon Simple Notification Service(Amazon SNS), AWS Lambda를 통해 사용할 수 있어요. 자세한 내용은 Amazon S3 Event Notifications로 복제 실패 이벤트 받기 문서를 참고하세요.
Amazon S3 Event Notifications로 복제 실패 이유도 볼 수 있어요. 실패 이유 목록을 검토하려면 Amazon S3 복제 실패 이유 문서를 참고하세요.

Batch Replication 오류

대상 버킷으로 복제되지 않는 객체를 문제 해결하려면 버킷, 복제 역할, Batch Replication 작업을 만드는 데 사용된 IAM 역할에 대한 여러 유형의 권한을 확인하세요. 버킷의 Block Public Access 설정과 S3 Object Ownership 설정도 확인해야 합니다.

Batch Operations 사용에 대한 추가 문제 해결 팁은 S3 Batch Operations 문제 해결 문서를 참고하세요. 복제를 설정했는데 객체가 복제되지 않는다면 AWS re:Post Knowledge Center의 버킷 간에 복제를 설정했는데 내 Amazon S3 객체가 복제되지 않는 이유는 무엇인가요? 문서를 참고하세요.

Batch Replication을 사용하는 동안 다음 오류 중 하나를 만날 수 있어요.

매니페스트 생성에서 필터 기준과 일치하는 키를 찾지 못했습니다. 이 오류는 다음 이유 중 하나로 발생합니다.
- 소스 버킷의 객체가 S3 Glacier Flexible Retrieval 또는 S3 Glacier Deep Archive 스토리지 클래스에 저장되어 있는 경우. 이런 객체에 Batch Replication을 사용하려면 먼저 Batch Operations 작업에서 Restore (S3InitiateRestoreObjectOperation) 작업으로 객체를 S3 Standard 스토리지 클래스로 복원하세요. 자세한 내용은 보관 객체 복원과 객체 복원(Batch Operations) 문서를 참고하세요. 객체를 복원한 뒤에는 Batch Replication 작업으로 복제할 수 있어요.
- 제공된 필터 기준이 소스 버킷의 어떤 유효한 객체와도 일치하지 않는 경우. 필터 기준을 확인하고 수정하세요. 예를 들어 Batch Replication 규칙에서 필터 기준이 Tax/ 접두사를 가진 소스 버킷의 모든 객체를 찾는다고 해 볼게요. 접두사 이름을 부정확하게 입력해서 시작과 끝 모두에 슬래시를 넣어 /Tax/로 만들면(Tax/처럼 끝에만 넣어야 함) S3 객체가 하나도 발견되지 않아요. 오류를 해결하려면 복제 규칙에서 접두사를 /Tax/에서 Tax/로 수정하세요.
배치 작업 상태가 실패, 이유: 작업 보고서를 보고서 버킷에 쓸 수 없습니다. 이 오류는 Batch Operations 작업에 사용된 IAM 역할이 작업을 만들 때 지정한 위치에 완료 보고서를 넣지 못할 때 발생해요. 이 오류를 해결하려면 IAM 역할에 Batch Operations 완료 보고서를 저장하려는 버킷에 대한 s3:PutObject 권한이 있는지 확인하세요. 보고서는 소스 버킷과 다른 버킷에 전달하는 걸 권장해요.
배치 작업이 실패와 함께 완료되었고 Total failed가 0이 아닙니다. 이 오류는 실행 중인 Batch Replication 작업에 객체 권한이 충분하지 않은 문제가 있을 때 발생해요. Batch Replication 작업에 복제 규칙을 사용한다면 복제에 사용되는 IAM 역할에 소스 버킷이나 대상 버킷에서 객체에 액세스할 적절한 권한이 있는지 확인하세요. Batch Replication 완료 보고서를 확인해 특정 Amazon S3 복제 실패 이유를 검토할 수도 있어요.
배치 작업은 성공적으로 실행됐지만 대상 버킷에서 예상되는 객체 수가 같지 않습니다. 이 오류는 Batch Replication 작업에 제공된 매니페스트에 나열된 객체와 작업을 만들 때 선택한 필터 사이에 불일치가 있을 때 발생해요. 소스 버킷의 객체가 어떤 복제 규칙과도 일치하지 않아 생성된 매니페스트에 포함되지 않은 경우에도 이 메시지를 받을 수 있어요.
기존 복제 구성에 새 복제 규칙을 추가한 후 Batch Operations 실패가 발생합니다. Batch Operations는 소스 버킷의 복제 구성에 있는 모든 규칙에 대해 기존 객체 복제를 시도해요. 기존 복제 규칙 중 하나라도 문제가 있으면 실패가 발생할 수 있어요.
- Batch Operations 작업의 완료 보고서가 작업 실패 이유를 설명합니다. 일반적인 오류 목록은 Amazon S3 복제 실패 이유 문서를 참고하세요.

복제 문제 해결하기