S3 Batch Operations 문제 해결 - Amazon Simple Storage Service
NoSuchJobExceptionInvalidManifestContent

S3 Batch Operations 문제 해결

Amazon S3 Batch Operations를 사용하면 Amazon S3 객체에 대해 대규모 작업을 수행할 수 있습니다. 이 가이드는 발생할 수 있는 일반적인 문제를 해결하는 데 도움이 됩니다.

S3 배치 복제와 관련된 문제를 해결하려면 복제 문제 해결 섹션을 참조하세요.

배치 작업 오류가 발생하는 두 가지 기본 유형의 실패가 있습니다.

  1. API 실패 - 요청된 API(예: CreateJob)를 실행하지 못했습니다.

  2. 작업 실패 - 초기 API 요청이 성공했지만 매니페스트 문제 또는 매니페스트에 지정된 객체에 대한 권한으로 인해 작업이 실패했습니다.

NoSuchJobException

유형: API 실패

NoSuchJobException은 S3 Batch Operations가 지정된 작업을 찾을 수 없을 때 발생합니다. 이 오류는 간단한 작업 만료 이후 여러 시나리오에서 발생할 수 있습니다. 일반적인 원인은 다음과 같습니다.

  1. 작업 만료 - 작업이 터미널 상태(Complete, Cancelled 또는 Failed)에 도달한 후 90일이 지나면 자동으로 삭제됩니다.

  2. 잘못된 작업 ID - DescribeJob 또는 UpdateJobStatus에 사용된 작업 ID가 CreateJob에서 반환한 ID와 일치하지 않습니다.

  3. 잘못된 리전 - 생성된 리전과 다른 리전의 작업에 액세스하려고 시도합니다.

  4. 잘못된 계정 - 다른 AWS 계정의 작업 ID를 사용합니다.

  5. 작업 ID 형식 오류 - 작업 ID에 오타, 추가 문자 또는 잘못된 형식이 있습니다.

  6. 타이밍 문제 - 작업이 완전히 등록되기도 전에 생성 직후 작업 상태를 확인합니다.

관련 오류 메시지로는 다음이 있습니다.

  1. No such job

  2. The specified job does not exist

NoSuchJobException API 실패를 방지하기 위한 모범 사례

  1. 작업 ID 즉시 저장 - 후속 API 직접 호출을 수행하기 전에 CreateJob 응답에서 작업 ID를 저장합니다.

  2. 재시도 로직 구현 - 생성 직후 작업 상태를 확인할 때 지수 백오프를 추가합니다.

  3. 모니터링 설정 - CloudWatch 경보를 생성하여 90일 만료 전에 작업 완료를 추적합니다. 자세한 내용은 Amazon CloudWatch 사용 설명서의 CloudWatch 경보 사용 섹션을 참조하세요.

  4. 일관된 리전 사용 - 모든 작업이 작업 생성과 동일한 리전을 사용하는지 확인합니다.

  5. 입력 검증 - API 직접 호출 전에 작업 ID 형식을 확인합니다.

작업이 만료되는 경우

터미널 상태의 작업은 90일 후에 자동으로 삭제됩니다. 작업 정보가 손실되지 않도록 하려면 다음을 고려하세요.

  1. 만료 전 완료 보고서 다운로드 - 작업 결과 검색 및 저장에 대한 지침은 섹션을 참조하세요.

  2. 자체 시스템에 작업 메타데이터 보관 - 데이터베이스 또는 모니터링 시스템에 중요한 작업 정보를 저장합니다.

  3. 90일 기한 전에 자동 알림 설정 - Amazon EventBridge를 사용하여 작업이 완료되면 알림을 트리거하는 규칙을 생성합니다. 자세한 내용은 Amazon S3 이벤트 알림 섹션을 참조하세요.

NoSuchJobException 문제 해결

  1. 다음 명령을 사용하여 작업이 계정 및 리전에 존재하는지 확인합니다.

    
aws s3control list-jobs --account-id 111122223333 --region us-east-1

  2. 다음 명령을 사용하여 모든 작업 상태를 검색합니다. 가능한 작업 상태는 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

  3. 다음 명령을 사용하여 일반적으로 작업을 생성하는 다른 리전에 작업이 존재하는지 확인합니다.

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

  4. 작업 ID 형식을 검증합니다. 작업 ID는 일반적으로 12345678-1234-1234-1234-123456789012처럼 36자로 구성됩니다. 추가 공백, 누락된 문자 또는 대/소문자 구분 문제가 있는지 확인하고 CreateJob 명령에서 반환된 전체 작업 ID를 사용하고 있는지 확인합니다.

  5. 다음 명령을 사용하여 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에서 가장 일반적인 오류 중 하나입니다. 일반적인 원인은 다음과 같습니다.

  1. IAM 권한 누락 - IAM 자격 증명에 Batch Operations API에 필요한 권한이 없습니다.

  2. S3 권한 부족 - 소스 또는 대상 버킷 및 객체에 액세스할 수 있는 권한이 없습니다.

  3. 작업 실행 역할 문제 - 작업 실행 역할에 지정된 작업을 수행할 권한이 없습니다.

  4. 지원되지 않는 작업 - 현재 리전 또는 버킷 유형에서 지원되지 않는 작업을 사용하려고 시도합니다.

  5. 교차 계정 액세스 문제 - 교차 계정 버킷 또는 객체 액세스에 대한 권한이 없습니다.

  6. 리소스 기반 정책 제한 - 작업을 차단하는 버킷 정책 또는 객체 ACL이 있습니다.

  7. 서비스 제어 정책(SCP) 제한 - 작업을 방지하는 조직 수준 정책이 있습니다.

관련 오류 메시지:

  1. Access Denied

  2. User: arn:aws:iam::account:user/username is not authorized to perform: s3:operation

  3. Cross-account pass role is not allowed

  4. The bucket policy does not allow the specified operation

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

  1. 최소 권한 원칙 사용 - 특정 작업에 필요한 최소 권한만 부여합니다.

  2. 대규모 작업 전 권한 테스트 - 수천 개의 객체를 처리하기 전에 소규모 테스트 작업을 실행하여 권한을 검증합니다.

  3. IAM 정책 시뮬레이터 사용 - IAM 정책 시뮬레이터를 사용하여 배포하기 전에 정책을 테스트합니다. 자세한 내용은 IAM 사용 설명서의 IAM 정책 시뮬레이터로 IAM 정책 테스트 섹션을 참조하세요.

  4. 적절한 교차 계정 설정 구현 - 교차 계정 액세스 구성에서 교차 계정 작업 구성을 확인합니다. 자세한 내용은 IAM 사용 설명서의 IAM 튜토리얼: IAM 역할을 사용한 AWS 계정 간 액세스 권한 위임 섹션을 참조하세요.

  5. 권한 변경 모니터링 - Batch Operations에 영향을 미칠 수 있는 IAM 정책 수정에 대한 CloudTrail 알림을 설정합니다.

  6. 문서 역할 요구 사항 - 각 작업 유형에 필요한 권한을 명확하게 문서화합니다.

  7. 공통 권한 템플릿 사용 - 권한 예제 및 정책 템플릿을 사용합니다.

    1. 배치 작업에 대한 권한 부여

    2. IAM 사용 설명서의 IAM의 교차 계정 리소스.

    3. AWS PrivateLink 가이드의 엔드포인트 정책을 사용하여 VPC 엔드포인트로 액세스 제어.

AccessDeniedException 문제 해결

다음 단계를 체계적으로 수행하여 권한 문제를 식별하고 해결합니다.

  1. S3 배치 작업에서 지원하는 작업를 검토하여 리전별로 지원되는 작업을 확인합니다. 디렉터리 버킷 작업을 리전 및 영역 엔드포인트에서만 사용할 수 있는지 확인합니다. 버킷의 스토리지 클래스에 작업이 지원되는지 확인합니다.

  2. 다음 명령을 사용하여 작업을 나열할 수 있는지 확인합니다.

    
 aws s3control list-jobs --account-id 111122223333

  3. 다음 명령을 사용하여 요청하는 자격 증명에 대한 IAM 권한을 확인합니다. 작업을 실행하는 계정에는 s3:CreateJob, s3:DescribeJob, s3:ListJobs-s3:UpdateJobPriority, s3:UpdateJobStatus-iam:PassRole 등 권한이 필요합니다.

    
aws sts get-caller-identity 111122223333

  4. 다음 명령을 사용하여 역할이 존재하고 수임 가능한지 확인합니다.

    
aws iam get-role --role-name role-name

  5. 다음 명령을 사용하여 역할의 신뢰 정책을 검토합니다. 작업을 실행하는 역할에는 다음이 있어야 합니다.

    1. batchoperations.s3.amazonaws.com이 해당 역할을 맡도록 허용하는 신뢰 관계.

    2. Batch Operations가 수행 중인 작업(예: 태그 지정 작업에 관한 s3:PutObjectTagging).

    3. 소스 및 대상 버킷에 대한 액세스 권한.

    4. 매니페스트 파일을 읽을 수 있는 권한.

    5. 완료 보고서를 작성할 수 있는 권한.

    
aws iam get-role --role-name role-name --query 'Role.AssumeRolePolicyDocument'

  6. 매니페스트 및 소스 버킷에 대한 액세스를 중지하려면 다음 명령을 사용합니다.

    
aws s3 ls s3://bucket-name

  7. Batch Operations에서 수행 중인 작업을 테스트합니다. 예를 들어 Batch Operations가 태그 지정을 수행하는 경우 소스 버킷의 샘플 객체에 태그를 지정합니다.

  8. 버킷 정책을 검토하여 작업을 거부할 수 있는 정책이 있는지 확인합니다.

    1. 레거시 액세스 제어로 작업하는 경우 객체 ACL를 확인합니다.

    2. 작업을 차단하는 서비스 제어 정책(SCPs)이 없는지 확인합니다.

    3. VPC 엔드포인트를 사용하는 경우 VPC 엔드포인트 정책이 Batch Operations를 허용하는지 확인합니다.

  9. 다음 명령을 사용하여 CloudTrail로 권한 실패를 식별합니다.

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

SlowDownError

유형: API 실패

계정에서 S3 Batch Operations API에 대한 요청 속도 제한을 초과한 경우 SlowDownError 예외가 발생합니다. 이는 너무 많은 요청으로 인해 서비스에 부담이 가중되는 것을 방지하기 위한 스로틀링 메커니즘입니다. 일반적인 원인은 다음과 같습니다.

  1. 높은 API 요청 빈도 - 짧은 시간 내에 너무 많은 API 직접 호출을 수행합니다.

  2. 동시 작업 - 여러 애플리케이션 또는 사용자가 동시에 작업을 생성/관리합니다.

  3. 속도 제한이 없는 자동 스크립트 - 적절한 백오프 전략을 구현하지 않는 스크립트입니다.

  4. 너무 잦은 작업 상태 폴링 - 작업 상태를 필요 이상으로 자주 확인합니다.

  5. 버스트 트래픽 패턴 - 피크 처리 시간 동안 API 사용량이 갑자기 급증합니다.

  6. 리전 용량 제한 - 리전에 할당된 요청 용량을 초과합니다.

관련 오류 메시지:

  1. SlowDown

  2. Please reduce your request rate

  3. Request rate exceeded

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

  1. 클라이언트 측 속도 제한 구현 - 애플리케이션의 API 직접 호출 사이에 지연을 추가합니다.

  2. 지터와 함께 지수 백오프 사용 - 폭주 문제를 방지하기 위해 재시도 지연을 무작위화합니다.

  3. 적절한 재시도 로직 설정 - 일시적 오류에 대한 지연이 증가함에 따라 자동 재시도를 구현합니다.

  4. 이벤트 기반 아키텍처 사용 - 폴링을 작업 상태 변경에 대한 EventBridge 알림으로 바꿉니다.

  5. 시간별 로드 분산 - 여러 기간에 걸쳐 작업 생성 및 상태 확인을 분산합니다.

  6. 속도 제한 모니터링 및 알림 - CloudWatch 경보를 설정하여 제한에 근접한 시기를 감지합니다.

대부분의 SDK에는 속도 제한 오류에 대한 재시도 로직이 내장되어 있습니다. 다음과 같이 구성합니다.

  1. AWS CLI - cli-read-timeout 및 cli-connect-timeout 파라미터를 사용합니다.

  2. Python용 AWS SDK (Boto3) - 클라이언트 구성에서 재시도 모드와 최대 시도 횟수를 구성합니다.

  3. Java용 AWS SDK – RetryPolicy 및 ClientConfiguration 설정을 사용합니다.

  4. JavaScript용 AWS SDK – maxRetries 및 retryDelayOptions를 구성합니다.

재시도 패턴 및 모범 사례에 대한 자세한 내용은 AWS 규범적 지침 가이드의 백오프 패턴으로 재시도 섹션을 참조하세요.

SlowDownError 문제 해결

  1. 코드에서 지수 백오프를 즉시 구현합니다.

    예 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

  2. 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]'

  3. 폴링 빈도를 검토합니다.

    1. 활성 작업에 대해 30초에 두 번 이상 작업 상태를 확인하지 마세요.

    2. 가능하면 폴링 대신 작업 완료 알림을 사용합니다.

    3. 동기화된 요청을 방지하려면 폴링 간격에 지터를 구현합니다.

  4. API 사용 패턴을 최적화합니다.

    1. 가능하면 여러 작업을 일괄 처리합니다.

    2. ListJobs를 사용하여 한 번의 직접 호출로 여러 작업의 상태를 가져옵니다.

    3. 작업 정보를 캐시하여 중복 API 직접 호출을 줄입니다.

    4. 여러 작업을 동시에 생성하는 대신 시간 경과에 따라 작업 생성을 분산합니다.

  5. 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

유형: 작업 실패

매니페스트 파일 형식, 콘텐츠, 구조에 S3 Batch Operations의 작업 처리에 방해가 되는 문제가 있는 경우 InvalidManifestContent 예외가 발생합니다. 일반적인 원인은 다음과 같습니다.

  1. 형식 위반 - 필수 열 누락, 잘못된 구분 기호 또는 잘못된 CSV 구조.

  2. 콘텐츠 인코딩 문제 - 잘못된 문자 인코딩, BOM 마커 또는 non-UTF-8 문자.

  3. 객체 키 문제 - 잘못된 문자, 잘못된 URL 인코딩 또는 길이 제한을 초과하는 키.

  4. 크기 제한 - 작업이 지원하는 것보다 많은 객체가 포함된 매니페스트.

  5. 버전 ID 형식 오류 - 버전이 지정된 객체의 잘못된 버전 ID.

  6. ETag 형식 문제 - ETag가 필요한 작업에 대해 잘못된 ETag.

  7. 일관되지 않은 데이터 - 동일한 매니페스트 또는 일관되지 않은 열 수 내의 혼합 형식.

관련 오류 메시지:

  1. Required fields are missing in the schema: + missingFields

  2. Invalid Manifest Content

  3. The S3 Batch Operations job failed because it contains more keys than the maximum allowed in a single job

  4. Invalid object key format

  5. Manifest file is not properly formatted

  6. Invalid version ID format

  7. ETag format is invalid

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

  1. 업로드 전 검증 - 대규모 데이터세트를 처리하기 전에 작은 작업으로 매니페스트 형식을 테스트합니다.

  2. 일관된 인코딩 사용 - 매니페스트 파일에 대해 항상 BOM 없이 UTF-8 인코딩을 사용합니다.

  3. 매니페스트 생성 표준 구현 - 매니페스트 생성을 위한 템플릿 및 검증 절차를 생성합니다.

  4. 특수 문자를 올바르게 처리 - 특수 문자가 포함된 객체 키를 URL 인코딩합니다.

  5. 객체 수 모니터링 - 매니페스트 크기를 추적하고 대규모 작업을 사전에 분할합니다.

  6. 객체 존재 확인 - 매니페스트에 객체를 포함하기 전에 객체가 존재하는지 확인합니다.

  7. 매니페스트 생성을 위한 AWS 도구 사용 - AWS CLI s3api list-objects-v2를 활용하여 적절한 형식의 객체 목록을 생성합니다.

일반적인 매니페스트 문제 및 해결 방법:

  1. 필수 열 누락 - 매니페스트에 작업 유형에 필요한 모든 열이 포함되어 있는지 확인합니다. 가장 일반적인 누락된 열은 버킷과 키입니다.

  2. 잘못된 CSV 형식 - 쉼표 구분 기호를 사용하고 모든 행에서 일관된 열 수를 보장하며 필드 내에 포함된 줄 바꿈을 방지합니다.

  3. 객체 키의 특수 문자 - 공백, 유니코드 문자 또는 XML 특수 문자(<, >, &, ", ')가 포함된 객체 키를 URL 인코딩합니다.

  4. 대용량 매니페스트 파일 - 작업 한도 이상의 매니페스트를 여러 개의 작은 매니페스트로 분할하고 별도의 작업을 생성합니다.

  5. 잘못된 버전 ID- 버전 ID 형식이 올바른 영숫자 문자열인지 확인합니다. 필요하지 않은 경우 버전 ID 열을 제거합니다.

  6. 문제 인코딩 - 매니페스트 파일을 BOM 없이 UTF-8로 저장합니다. 인코딩을 변경할 수 있는 시스템을 통해 매니페스트를 복사하지 마세요.

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

  1. 매니페스트 지정

  2. S3 배치 작업에서 지원하는 작업

  3. Amazon S3 객체 이름 지정

InvalidManifestContent 문제 해결

  1. 매니페스트 파일을 다운로드 및 검사합니다. 매니페스트가 다음의 형식 요구 사항을 충족하는지 수동으로 확인합니다.

    1. 쉼표 구분 기호가 있는 CSV 형식일 것.

    2. BOM을 사용하지 않는 UTF-8 인코딩일 것.

    3. 모든 행에서 열 수가 일관적일 것.

    4. 빈 줄이나 후행 공백이 없을 것.

    5. 객체 키에 특수 문자가 포함된 경우에는, 제대로 인코딩된 URL일 것.

    매니페스트 파일을 다운로드하려면 다음 명령을 사용합니다.

    
aws s3 cp s3://amzn-s3-demo-bucket1/manifest-key ./manifest.csv

  2. 작업에 필요한 열을 확인합니다.

    1. 모든 작업: Bucket, Key

    2. 복사 작업: VersionId(선택 사항)

    3. 복원 작업: VersionId(선택 사항)

    4. 태그 교체 작업: 추가 열이 필요하지 않습니다.

    5. ACL 교체 작업: 추가 열이 필요하지 않습니다.

    6. 복원 시작: VersionId(선택 사항)

  3. 객체 수 제한을 확인합니다.

    1. 복사: 최대 10억 개의 객체.

    2. 삭제: 최대 10억 개의 객체.

    3. 복원: 최대 10억 개의 객체.

    4. 태그 지정: 최대 10억 개의 객체.

    5. ACL: 최대 10억 개의 객체.

  4. 원본 매니페스트의 몇 가지 객체를 사용하여 테스트 매니페스트를 생성합니다.

  5. 매니페스트의 객체 샘플이 존재하는 경우 다음 명령을 사용하여 확인합니다.

    
aws s3 ls s3://amzn-s3-demo-bucket1/object-key

  6. 작업 실패 세부 정보를 확인하고 작업 설명에서 실패 이유와 특정 오류 세부 정보를 검토합니다.

    
aws s3control describe-job --account-id 111122223333 --job-id job-id