S3 Batch Operations 문제 해결

S3 Batch Operations로 대규모 작업을 하다 보면 만나는 흔한 오류들을 정리해 드릴게요. 실패는 크게 API 실패와 작업(Job) 실패 두 종류로 나뉘는데, 각 오류의 원인과 예방 방법, 그리고 실제로 진단하는 명령까지 하나씩 살펴볼게요.

출처: 문서

본문

Amazon S3 Batch Operations는 S3 객체에 대한 대규모 작업을 수행할 수 있게 해 줘요. 이 가이드는 직면할 수 있는 흔한 문제를 해결하는 데 도움을 줘요.

S3 Batch Replication 문제를 해결하려면 Troubleshooting replication 문서를 참고하세요.

Batch 작업 오류를 일으키는 실패에는 크게 두 종류가 있어요.

API 실패 – 요청한 API(예: CreateJob)가 실행에 실패했어요.
작업 실패 – 초기 API 요청은 성공했지만, 매니페스트나 매니페스트에 지정된 객체에 대한 권한 문제 같은 이유로 작업이 실패했어요.

NoSuchJobException

유형: API 실패

NoSuchJobException은 S3 Batch Operations가 지정된 작업을 찾을 수 없을 때 발생해요. 이 오류는 단순한 작업 만료 외에도 여러 시나리오에서 나타날 수 있어요. 흔한 원인은 다음과 같아요.

작업 만료 – 작업은 종료 상태(Complete, Cancelled, Failed)에 도달한 지 90일 후 자동으로 삭제돼요.
잘못된 작업 ID – DescribeJob이나 UpdateJobStatus에 사용한 작업 ID가 CreateJob이 반환한 ID와 일치하지 않아요.
잘못된 리전 – 작업을 만든 리전이 아닌 다른 리전에서 작업에 접근하려 해요.
잘못된 계정 – 다른 AWS 계정의 작업 ID를 사용하고 있어요.
작업 ID 형식 오류 – 작업 ID의 오타, 추가 문자, 잘못된 형식.
시점 문제 – 작업이 완전히 등록되기 전에 생성 직후에 작업 상태를 확인하는 경우.

관련 오류 메시지는 다음과 같아요.

No such job
The specified job does not exist

NoSuchJobException API 실패를 예방하는 모범 사례

작업 ID를 즉시 저장 – 후속 API 호출 전에 CreateJob 응답에서 작업 ID를 저장해요.
재시도 로직 구현 – 생성 직후에 작업 상태를 확인할 때 지수 백오프(exponential backoff)를 추가해요.
모니터링 설정 – 90일 만료 전에 작업 완료를 추적하는 CloudWatch 알람을 만들어요. 자세한 내용은 Amazon CloudWatch User Guide의 Using CloudWatch alarms 문서를 참고하세요.
일관된 리전 사용 – 모든 작업 작업이 작업 생성과 같은 리전을 사용하는지 확인해요.
입력 검증 – API 호출 전에 작업 ID 형식을 확인해요.

작업이 만료될 때

종료 상태의 작업은 90일 후에 자동으로 삭제돼요. 작업 정보를 잃지 않으려면 다음을 고려하세요.

만료 전에 완료 보고서 다운로드 – 작업 결과를 검색하고 저장하는 방법은 Completion reports 문서를 참고하세요.
작업 메타데이터를 자체 시스템에 보관 – 중요한 작업 정보를 데이터베이스나 모니터링 시스템에 저장해요.
90일 마감 전에 자동 알림 설정 – 작업이 완료될 때 알림을 트리거하는 규칙을 만들려면 Amazon EventBridge를 사용해요. 자세한 내용은 Amazon S3 Event Notifications 문서를 참고하세요.

NoSuchJobException 문제 해결

다음 명령으로 작업이 계정과 리전에 존재하는지 확인해요.
```
aws s3control list-jobs --account-id 111122223333 --region us-east-1
```
다음 명령으로 모든 작업 상태를 검색해요. 가능한 작업 상태는 Active, Cancelled, Cancelling, Complete, Completing, Failed, Failing, New, Paused, Pausing, Preparing, Ready, Suspended예요.
```
aws s3control list-jobs --account-id 111122223333 --job-statuses your-job-status
```

다음 명령으로 작업을 자주 만드는 다른 리전에 작업이 존재하는지 확인해요.

aws s3control list-jobs --account-id 111122223333 --region job-region-1
aws s3control list-jobs --account-id 111122223333 --region job-region-2

작업 ID 형식을 검증해요. 작업 ID는 일반적으로 12345678-1234-1234-1234-123456789012 같은 36자로 구성돼요. 추가 공백, 누락 문자, 대소문자 구분 문제를 확인하고 CreateJob 명령이 반환한 전체 작업 ID를 사용하고 있는지 확인해요.

다음 명령으로 작업 생성 이벤트에 대한 CloudTrail 로그를 확인해요.

aws logs filter-log-events --log-group-name CloudTrail/S3BatchOperations \
--filter-pattern "{ $.eventName = CreateJob }" \
--start-time timestamp

AccessDeniedException

유형: API 실패

AccessDeniedException은 S3 Batch Operations 요청이 권한 부족, 지원되지 않는 작업, 또는 정책 제한으로 인해 차단될 때 발생해요. Batch Operations에서 가장 흔한 오류 중 하나에요. 흔한 원인은 다음과 같아요.

IAM 권한 누락 – IAM 자격 증명에 Batch Operations API에 필요한 권한이 없어요.
S3 권한 부족 – 소스·대상 버킷과 객체에 접근할 권한이 없어요.
작업 실행 역할 문제 – 작업 실행 역할이 지정된 작업을 수행할 권한이 없어요.
지원되지 않는 작업 – 현재 리전이나 버킷 유형에서 지원되지 않는 작업을 사용하려 해요.
교차 계정 접근 문제 – 교차 계정 버킷 또는 객체 접근에 대한 권한이 없어요.
리소스 기반 정책 제한 – 버킷 정책 또는 객체 ACL이 작업을 차단해요.
서비스 제어 정책(SCP) 제한 – 조직 수준의 정책이 작업을 방해해요.

AccessDeniedException API 실패를 예방하는 모범 사례

최소 권한 원칙 사용 – 특정 작업에 필요한 최소 권한만 부여해요.
대규모 작업 전에 권한 테스트 – 수천 개의 객체를 처리하기 전에 작은 테스트 작업으로 권한을 검증해요.
IAM 정책 시뮬레이터 사용 – 배포 전에 IAM 정책 시뮬레이터로 정책을 테스트해요. 자세한 내용은 IAM User Guide의 IAM policy testing with the IAM policy simulator 문서를 참고하세요.
올바른 교차 계정 설정 – 교차 계정 작업 구성에 대해 교차 계정 접근 구성을 확인해요. 자세한 내용은 IAM User Guide의 IAM tutorial: Delegate access across AWS accounts using IAM roles 문서를 참고하세요.
권한 변경 모니터링 – Batch Operations에 영향을 줄 수 있는 IAM 정책 수정에 대한 CloudTrail 알림을 설정해요.
역할 요구 사항 문서화 – 각 작업 유형에 필요한 권한에 대한 명확한 문서를 유지해요.
공통 권한 템플릿 사용 – Granting permissions for Batch Operations 문서의 권한 예제와 정책 템플릿, IAM User Guide의 Cross account resources in IAM, AWS PrivateLink Guide의 Control access to VPC endpoints using endpoint policies 문서를 사용해요.

AccessDeniedException 문제 해결

다음 단계를 체계적으로 따라 권한 문제를 파악하고 해결해요.

Operations supported by S3 Batch Operations 문서에서 리전별 지원 작업을 확인해요. 디렉터리 버킷 작업은 Regional 및 Zonal 엔드포인트에서만 사용 가능한지 확인하고, 버킷의 스토리지 클래스에 대해 작업이 지원되는지 확인해요.
다음 명령으로 작업을 나열할 수 있는지 확인해요.
```
aws s3control list-jobs --account-id 111122223333
```
다음 명령으로 요청하는 자격 증명의 IAM 권한을 확인해요. 작업을 실행하는 계정에는 s3:CreateJob, s3:DescribeJob, s3:ListJobs, s3:UpdateJobPriority, s3:UpdateJobStatus, iam:PassRole 권한이 필요해요.
```
aws sts get-caller-identity 111122223333
```
다음 명령으로 역할이 존재하고 맡을 수 있는지 확인해요.
```
aws iam get-role --role-name role-name
```
다음 명령으로 역할의 신뢰 정책을 검토해요. 작업을 실행하는 역할에는 다음이 있어야 해요. batchoperations.s3.amazonaws.com이 역할을 맡을 수 있게 하는 신뢰 관계. 배치 작업이 수행하는 작업(예: 태깅 작업의 경우 s3:PutObjectTagging). 소스·대상 버킷에 대한 접근. 매니페스트 파일을 읽을 권한. 완료 보고서를 쓸 권한.
```
aws iam get-role --role-name role-name --query 'Role.AssumeRolePolicyDocument'
```
다음 명령으로 매니페스트와 소스 버킷에 대한 접근을 테스트해요.
```
aws s3 ls s3://amzn-s3-demo-bucket
```
배치 작업이 수행하는 작업을 테스트해요. 예를 들어 배치 작업이 태깅을 수행한다면 소스 버킷에서 샘플 객체에 태그를 붙여 보세요.
작업을 거부할 수 있는 버킷 정책을 검토해요. 레거시 접근 제어를 사용한다면 객체 ACL을 확인하고, 서비스 제어 정책(SCP)이 작업을 막고 있는지 확인하며, VPC 엔드포인트를 사용한다면 VPC 엔드포인트 정책이 Batch Operations를 허용하는지 확인해요.

다음 명령으로 CloudTrail을 사용해 권한 실패를 식별해요.

aws logs filter-log-events --log-group-name CloudTrail/S3BatchOperations \
    --filter-pattern "{ $.errorCode = AccessDenied }" \
    --start-time timestamp

SlowDownError

유형: API 실패

SlowDownError 예외는 계정이 S3 Batch Operations API에 대한 요청 비율 한도를 초과했을 때 발생해요. 이는 서비스가 너무 많은 요청에 압도되지 않도록 보호하는 스로틀링(throttling) 메커니즘이에요. 흔한 원인은 다음과 같아요.

높은 API 요청 빈도 – 짧은 시간에 너무 많은 API 호출을 하는 경우.
동시 작업 작업 – 여러 애플리케이션이나 사용자가 동시에 작업을 만들거나 관리하는 경우.
속도 제한이 없는 자동화 스크립트 – 적절한 백오프 전략을 구현하지 않은 스크립트.
작업 상태를 너무 자주 폴링 – 필요 이상으로 자주 작업 상태를 확인하는 경우.
버스트 트래픽 패턴 – 피크 처리 시간에 API 사용이 갑자기 급증하는 경우.
리전 용량 한도 – 리전에 할당된 요청 용량을 초과하는 경우.

SlowDownError API 실패를 예방하는 모범 사례

클라이언트 측 속도 제한 구현 – 애플리케이션의 API 호출 사이에 지연을 추가해요.
지터가 포함된 지수 백오프 사용 – 재시도 지연을 무작위화해 동시 충돌(thundering herd) 문제를 피해요.
적절한 재시도 로직 설정 – 일시적 오류에 대해 지연을 늘려 가는 자동 재시도를 구현해요.
이벤트 기반 아키텍처 사용 – 작업 상태 변경에 대한 폴링 대신 EventBridge 알림을 사용해요.
시간에 걸쳐 부하 분산 – 작업 생성과 상태 확인을 서로 다른 시간대에 분산해요.
요율 한도 모니터링 및 알림 – 한도에 가까워지고 있음을 감지하는 CloudWatch 알람을 설정해요.

대부분의 AWS SDK에는 요율 제한 오류에 대한 내장 재시도 로직이 있어요. 다음과 같이 구성해요.

AWS CLI – cli-read-timeout 및 cli-connect-timeout 매개변수를 사용해요.
AWS SDK for Python(Boto3) – 클라이언트 구성에서 retry modes와 max attempts를 구성해요.
AWS SDK for Java – RetryPolicy와 ClientConfiguration 설정을 사용해요.
AWS SDK for JavaScript – maxRetries와 retryDelayOptions를 구성해요.

재시도 패턴과 모범 사례에 대한 자세한 내용은 AWS Prescriptive Guidance 가이드의 Retry with backoff pattern 문서를 참고하세요.

SlowDownError 문제 해결

코드에서 즉시 지수 백오프를 구현해요. bash에서 지수 백오프 예시:

for attempt in {1..5}; do
    if aws s3control describe-job --account-id 111122223333 --job-id job-id ; then
        break
    else
        wait_time=$((2**attempt))
        echo "Rate limited, waiting ${wait_time} seconds..."
        sleep $wait_time
    fi
done

CloudTrail로 높은 요청 볼륨의 원인을 식별해요.

aws logs filter-log-events \
    --log-group-name CloudTrail/S3BatchOperations \
    --filter-pattern "{ $.eventName = CreateJob || $.eventName = DescribeJob }" \
    --start-time timestamp \
    --query 'events[*].[eventTime,sourceIPAddress,userIdentity.type,eventName]'

폴링 빈도를 검토해요. 활성 작업의 경우 작업 상태를 30초에 한 번 이상 확인하지 마세요. 가능하면 폴링 대신 작업 완료 알림을 사용해요. 동기화된 요청을 피하려면 폴링 간격에 지터(jitter)를 구현해요.
API 사용 패턴을 최적화해요. 가능하면 여러 작업을 일괄 처리하고, ListJobs로 한 번의 호출로 여러 작업의 상태를 얻고, 중복 API 호출을 줄이기 위해 작업 정보를 캐시하며, 많은 작업을 동시에 만들기보다 시간에 걸쳐 분산해요.

API 호출용 CloudWatch 지표로 요청 패턴을 모니터링해요.

aws logs put-metric-filter \
       --log-group-name CloudTrail/S3BatchOperations \
       --filter-name S3BatchOpsAPICallCount \
       --filter-pattern "{ $.eventSource = s3.amazonaws.com && $.eventName = CreateJob }" \
       --metric-transformations \
       metricName=S3BatchOpsAPICalls,metricNamespace=Custom/S3BatchOps,metricValue=1

InvalidManifestContent

유형: 작업 실패

InvalidManifestContent 예외는 S3 Batch Operations가 작업을 처리하지 못하게 하는 매니페스트 파일 형식, 내용, 구조에 문제가 있을 때 발생해요. 흔한 원인은 다음과 같아요.

형식 위반 – 필수 열 누락, 잘못된 구분자, 잘못된 형태의 CSV 구조.
콘텐츠 인코딩 문제 – 잘못된 문자 인코딩, BOM 마커, 비 UTF-8 문자.
객체 키 문제 – 잘못된 문자, 부적절한 URL 인코딩, 길이 한도를 초과하는 키.
크기 한도 – 매니페스트에 작업이 지원하는 것보다 많은 객체가 포함된 경우.
버전 ID 형식 오류 – 버전 관리 객체의 잘못되거나 유효하지 않은 버전 ID.
ETag 형식 문제 – ETag가 필요한 작업에 대한 잘못된 ETag 형식 또는 누락된 따옴표.
일관되지 않은 데이터 – 같은 매니페스트 안의 혼합 형식 또는 일관되지 않은 열 수.

InvalidManifestContent 작업 실패를 예방하는 모범 사례

업로드 전 검증 – 대규모 데이터셋을 처리하기 전에 작은 작업으로 매니페스트 형식을 테스트해요.
일관된 인코딩 사용 – 매니페스트 파일에는 항상 BOM 없는 UTF-8 인코딩을 사용해요.
매니페스트 생성 표준 구현 – 매니페스트 생성을 위한 템플릿과 검증 절차를 만들어요.
특수 문자 제대로 처리 – 특수 문자가 포함된 객체 키는 URL 인코딩해요.
객체 수 모니터링 – 매니페스트 크기를 추적하고 큰 작업을 사전에 분할해요.
객체 존재 검증 – 객체를 매니페스트에 포함하기 전에 존재하는지 확인해요.
AWS 도구로 매니페스트 생성 – AWS CLI s3api list-objects-v2를 활용해 올바른 형식의 객체 목록을 생성해요.

흔한 매니페스트 문제와 해결책:

필수 열 누락 – 매니페스트가 작업 유형에 필요한 모든 열을 포함하는지 확인해요. 가장 흔히 누락되는 열은 Bucket과 Key예요.
잘못된 CSV 형식 – 쉼표 구분자를 사용하고, 모든 행에서 열 수를 일관되게 유지하며, 필드 내 임베디드 줄바꿈을 피해요.
객체 키의 특수 문자 – 공백, 유니코드 문자, XML 특수 문자(, >, &, ", '`)가 포함된 객체 키는 URL 인코딩해요.
큰 매니페스트 파일 – 작업 한도를 초과하는 매니페스트는 여러 개의 작은 매니페스트로 분할하고 별도의 작업을 만들어요.
유효하지 않은 버전 ID – 버전 ID가 올바른 형식의 영숫자 문자열인지 확인해요. 필요하지 않으면 버전 ID 열을 제거해요.
인코딩 문제 – 매니페스트 파일을 BOM 없는 UTF-8로 저장해요. 인코딩을 변경할 수 있는 시스템을 통해 매니페스트를 복사하지 마세요.

자세한 매니페스트 형식 사양과 예제는 다음을 참고하세요.

Specifying a manifest
Operations supported by S3 Batch Operations
Naming Amazon S3 objects

InvalidManifestContent 문제 해결

매니페스트 파일을 다운로드해 검사해요. 매니페스트가 형식 요구 사항을 충족하는지 직접 확인해요: 쉼표 구분자가 있는 CSV 형식, BOM 없는 UTF-8 인코딩, 모든 행에서 일관된 열 수, 빈 줄이나 후행 공백 없음, 특수 문자가 포함된 경우 객체 키가 올바르게 URL 인코딩되어 있음. 다음 명령으로 매니페스트 파일을 다운로드해요.
```
aws s3 cp s3://amzn-s3-demo-bucket1/manifest-key ./manifest.csv
```
작업에 필요한 열을 확인해요. 모든 작업: Bucket, Key. 복사 작업: VersionId(선택). 복원 작업: VersionId(선택). 태그 교체 작업: 추가 열 필요 없음. ACL 교체 작업: 추가 열 필요 없음. 복원 시작(Initiate restore): VersionId(선택).
객체 수 한도를 확인해요. 복사: 최대 10억 개 객체. 삭제: 최대 10억 개 객체. 복원: 최대 10억 개 객체. 태깅: 최대 10억 개 객체. ACL: 최대 10억 개 객체.
원래 매니페스트의 몇 개 객체로 테스트 매니페스트를 만들어요.
다음 명령으로 매니페스트의 객체 샘플이 존재하는지 확인해요.
```
aws s3 ls s3://amzn-s3-demo-bucket1/object-key
```
작업 실패 세부 정보를 확인하고 작업 설명에서 실패 사유와 특정 오류 세부 정보를 검토해요.
```
aws s3control describe-job --account-id 111122223333 --job-id job-id
```