S3 Files 문제 해결

S3 Files 문제 해결 (Troubleshooting S3 Files)

이 페이지는 S3 Files의 일반적인 문제를 진단하고 해결하는 데 도움을 줘요.

출처: 문서

본문

마운트 명령 실패

mount -t s3files 명령이 오류와 함께 실패해요.

일반적인 원인과 조치:

"mount.s3files: command not found" – S3 Files 클라이언트(amazon-efs-utils)가 설치되지 않았거나 버전 3.0.0 미만이에요. 클라이언트를 설치하거나 업그레이드하세요. 자세한 내용은 S3 Files 전제 조건을 참고하세요.
"Failed to resolve file system DNS name" – EC2 인스턴스가 실행 중인 가용 영역에 마운트 타겟이 없어요. 해당 가용 영역에 마운트 타겟을 만들거나 마운트 타겟이 있는 가용 영역에서 인스턴스를 시작하세요. 자세한 내용은 마운트 타겟 생성을 참고하세요.
연결 시간 초과(Connection timed out) – 보안 그룹 구성이 NFS 트래픽을 허용하지 않아요. 마운트 타겟의 보안 그룹이 인스턴스의 보안 그룹에서 포트 2049의 인바운드 TCP를 허용하고, 인스턴스의 보안 그룹이 마운트 타겟의 보안 그룹으로 포트 2049의 아웃바운드 TCP를 허용하는지 확인하세요. 자세한 내용은 S3 Files 전제 조건을 참고하세요.
마운트 중 "Access denied" – 컴퓨팅 리소스에 연결된 IAM 역할에 필요한 S3 Files 권한이 없어요. 역할에 AmazonS3FilesClientFullAccess 또는 AmazonS3FilesClientReadOnlyAccess 관리형 정책이 연결되어 있는지, 또는 최소한 s3files:ClientMount 권한이 있는지 확인하세요. 자세한 내용은 S3 Files 전제 조건을 참고하세요.
botocore가 설치되지 않음 – 마운트 헬퍼는 AWS 서비스와 상호작용하기 위해 botocore가 필요해요. GitHub의 amazon-efs-utils README 지침에 따라 botocore를 설치하세요.

파일 작업 시 권한 거부

파일 시스템을 마운트할 수는 있지만 파일을 읽거나, 쓰거나, 액세스할 때 "Permission denied" 또는 "Operation not permitted" 오류가 발생해요.

일반적인 원인과 조치:

쓰기 권한 누락 – 읽을 수는 있지만 쓸 수 없다면 컴퓨팅 리소스에 연결된 IAM 역할에 s3files:ClientWrite 권한이 포함되어 있는지 확인하거나 AmazonS3FilesClientReadWriteAccess 또는 AmazonS3FilesClientFullAccess 관리형 정책을 연결하세요. 자세한 내용은 Amazon S3 Files용 AWS 관리형 정책을 참고하세요.
루트 액세스 누락 – root(UID 0)가 소유한 파일에 액세스할 때 권한 오류가 발생하면 IAM 역할에 s3files:ClientRootAccess 권한이 없을 수 있어요. 이 권한이 없으면 모든 작업이 NFS 익명 사용자(일반적으로 nfsnobody)로 수행되며, 이 사용자는 파일에 액세스하지 못할 수 있어요. AmazonS3FilesClientFullAccess 관리형 정책을 연결하거나 정책에 s3files:ClientRootAccess를 추가하세요.
파일 시스템 정책이 액세스 거부 – 파일 시스템 정책을 연결했다면 클라이언트가 필요로 하는 작업을 거부하지 않는지 확인하세요. ID 기반 정책 또는 파일 시스템 정책 중 하나의 "허용(allow)"이면 액세스에 충분해요. 자세한 내용은 S3 Files가 IAM과 함께 작동하는 방식을 참고하세요.
POSIX 권한 불일치 – S3 Files는 파일과 디렉터리에 표준 POSIX 권한(소유자, 그룹, 기타)을 적용해요. 애플리케이션이 파일의 소유자나 그룹과 일치하지 않는 사용자로 실행되면 IAM 권한이 올바르더라도 액세스가 거부될 수 있어요. 모든 요청에 특정 UID/GID를 적용하려면 액세스 포인트를 사용하세요. 자세한 내용은 S3 파일 시스템용 액세스 포인트 생성을 참고하세요.

지능형 읽기 라우팅이 작동하지 않음

S3 Files는 일관성, 잠금, POSIX 권한을 포함한 전체 파일 시스템 의미 체계를 유지하면서 읽기 요청을 가장 적합한 스토리지 계층으로 자동 라우팅하는 지능형 읽기 라우팅을 수행해요. 적극적으로 사용되는 파일에 대한 작고 무작위한 읽기는 저지연을 위해 고성능 스토리지에서 처리되고, 대용량 순차 읽기와 파일 시스템에 없는 데이터의 읽기는 높은 처리량을 위해 S3 버킷에서 직접 처리되며 파일 시스템 데이터 요금이 없어요.

클라이언트 연결성 메트릭 중 하나(NFSConnectionAccessible, S3BucketAccessible, S3BucketReachable)가 0을 표시하거나 예상한 읽기 처리량이 나오지 않으면 지능형 읽기 라우팅이 작동하지 않을 수 있어요.

일반적인 원인과 조치:

컴퓨팅 역할에 S3 인라인 정책 누락 – 컴퓨팅 리소스에 연결된 IAM 역할에는 연결된 S3 버킷에 대해 s3:GetObject와 s3:GetObjectVersion을 부여하는 인라인 정책이 포함되어야 해요. 이 정책이 없으면 마운트 헬퍼가 S3에서 직접 읽을 수 없고 모든 읽기가 파일 시스템을 통해 이루어져요. 자세한 내용은 S3 Files 전제 조건을 참고하세요.
S3 버킷에 연결할 수 없음 – S3BucketReachable 메트릭을 확인하세요. 0을 표시하면 컴퓨팅 리소스가 S3에 대한 네트워크 액세스(VPC 엔드포인트 또는 NAT 게이트웨이를 통해)가 있는지 확인하세요.
파일이 수정됨 – 파일이 파일 시스템을 통해 수정되지 않은 경우에만 S3에서 직접 읽기가 처리돼요. 파일에 쓰고 변경 사항이 아직 S3에 동기화되지 않았다면 동기화가 완료될 때까지 읽기가 파일 시스템을 통해 이루어져요.

파일 시스템이 지속적으로 NFS 서버 오류 반환

암호화된 파일 시스템이 지속적으로 NFS 서버 오류를 반환해요. S3 Files가 다음 이유 중 하나로 AWS KMS에서 KMS 키를 검색할 수 없을 때 이러한 오류가 발생할 수 있어요.

키가 비활성화되었음.
키가 삭제되었음.
S3 Files가 키를 사용할 권한이 철회되었음.
AWS KMS를 일시적으로 사용할 수 없음.

취해야 할 조치

먼저 AWS KMS 키가 활성화되어 있는지 확인하세요. AWS KMS 콘솔에서 키를 볼 수 있어요. 자세한 내용은 AWS Key Management Service 개발자 가이드의 키 보기를 참고하세요.

키가 활성화되지 않았다면 활성화하세요. 자세한 내용은 AWS Key Management Service 개발자 가이드의 키 활성화 및 비활성화를 참고하세요.

키가 삭제 대기 중이라면 삭제를 취소하고 키를 다시 활성화하세요. 자세한 내용은 AWS Key Management Service 개발자 가이드의 키 삭제 예약 및 취소를 참고하세요.

키가 활성화되었는데도 계속 문제가 발생하면 AWS Support에 문의하세요.

파일 시스템 쓰기 후 S3 버킷에 객체 없음

파일 시스템을 통해 파일을 썼고 S3 버킷에 객체로 나타날 것으로 예상했지만 객체가 없어요. S3 Files는 변경 사항을 S3 버킷으로 내보내기 전에 쓰기 비활성 기간(60초)을 기다려요. 이 기간 후에도 객체가 나타나지 않으면 내보내기가 실패했을 수 있어요. 이 경우 FailedExports CloudWatch 메트릭이 증가하는 것을 볼 수 있어요.

취해야 할 조치

확장 속성을 사용해 파일의 내보내기 상태를 확인하세요.

getfattr -n "user.s3files.status;$(date -u +%s)" missing-file.txt --only-values

속성 이름의 타임스탬프는 최신 상태를 얻도록 보장해요. 예시 출력:

S3Key: s3://bucket/prefix/missing-file.txt
ExportError: PathTooLong

내보내기 실패가 없으면 ExportError는 표시되지 않아요. 파일에 연결된 S3 객체가 없으면 S3Key는 비어 있어요.

다음 표는 가능한 모든 ExportError 값을 나열해요.

오류	원인
`S3AccessDenied`	S3 Files가 가정하는 IAM 역할에 S3 버킷에 쓸 충분한 권한이 없어요. 자세한 내용은 S3 Files 전제 조건을 참고하세요.
`InternalError`	내부 시스템 오류가 발생했어요.
`S3UserMetadataTooLarge`	S3 사용자 메타데이터 크기 제한을 초과했어요. 이러한 제한에 대한 정보는 지원되지 않는 기능, 제한 및 할당량을 참고하세요.
`EncryptionKeyInaccessible`	S3 버킷이 사용하는 암호화 키에 S3 Files가 액세스할 수 없어요. S3 Files에 암호화 키에 대한 액세스를 부여하세요. 자세한 내용은 암호화를 참고하세요.
`RoleAssumptionFailed`	역할을 가정할 수 없어요. 신뢰 정책을 확인하세요. 자세한 내용은 S3 Files 전제 조건을 참고하세요.
`KeyTooLongToBreakCycle`	파일 경로가 S3 키 길이 제한을 초과하여 S3 Files가 순환 종속성(예: 두 파일을 서로의 이름으로 바꿔서 발생)을 해결할 수 없어요. 디렉터리 경로를 줄여 이 오류를 해결하세요.
`PathTooLong`	파일 경로가 S3 키 길이 제한을 초과했어요. 이러한 제한에 대한 정보는 지원되지 않는 기능, 제한 및 할당량을 참고하세요.
`DependencyExportFailed`	상위 항목 또는 종속 항목에 재시도 불가능한 내보내기 실패가 있어요. `getfattr`를 사용해 상위 항목 또는 종속 항목의 상태를 확인하세요.
`S3ObjectArchived`	S3 객체가 보관되었고(S3 Glacier Flexible Retrieval 또는 S3 Glacier Deep Archive) 읽을 수 없어요. S3 API를 사용해 객체를 먼저 복원하세요.

S3 Files는 실패한 내보내기를 자동으로 재시도해요. ExportError는 재시도 불가능한 오류에만 표시돼요.

파일 시스템에 S3 객체가 보이지 않음

S3 버킷에 객체가 있지만 파일 시스템에 나타나지 않아요. 객체 키 이름이 유효한 POSIX 파일 경로로 매핑되지 않을 수 있어요. S3 Files는 빈 경로 구성 요소(foo//bar), 상대 경로 구성 요소(foo/./bar, foo/../bar), null 바이트를 포함하는 키 이름, 또는 경로 구성 요소가 255바이트를 초과하는 키 이름에 대한 액세스를 지원하지 않아요. 호환되지 않는 키 이름을 가진 객체는 파일 시스템으로 가져오지 않아요.

분실물 보관함 디렉터리에 파일 나타남

파일 시스템의 루트 디렉터리에 있는 .s3files-lost+found-파일시스템ID 디렉터리에 파일이 나타났어요. 이 경우 LostAndFoundFiles CloudWatch 메트릭이 증가하는 것을 볼 수 있어요. 이는 동기화 충돌이 발생할 때 생겨요. 같은 파일이 파일 시스템을 통해 수정되고 S3 Files가 파일 시스템 변경 사항을 S3로 동기화하기 전에 해당 S3 객체가 변경되면 충돌이 발생해요. S3 Files는 S3 버킷을 진실 원천으로 간주하고 충돌한 파일을 분실물 보관함 디렉터리로 이동하며 S3 버킷에서 최신 버전을 파일 시스템으로 가져와요.

분실물 보관함 디렉터리의 파일 식별

S3 Files가 파일을 분실물 보관함 디렉터리로 이동할 때 시간이 지나면서 이동될 수 있는 같은 파일의 여러 버전을 구분하기 위해 파일 이름 앞에 16진수 식별자를 붙여요. 100자보다 긴 파일 이름은 이 식별자를 위한 공간을 확보하기 위해 잘려요. 파일의 원래 디렉터리 경로는 분실물 보관함 디렉터리에 보존되지 않아요.

취해야 할 조치

파일의 원래 경로와 해당 S3 객체 키를 가져오세요.

getfattr -n "user.s3files.status;$(date -u +%s)" .s3files-lost+found-fs-12345678/abcdef1234_report.csv --only-values

예시 출력:

S3Key: s3://bucket/prefix/report.csv
FilePath: /data/report.csv

필드	설명
`S3Key`	충돌을 일으킨 객체의 전체 S3 경로. 객체가 S3 버킷에서 삭제된 경우 비어 있어요.
`FilePath`	충돌 이전 파일의 상대 경로.

그런 다음 S3 버킷의 최신 버전을 유지하고 분실물 보관함 디렉터리에서 파일을 삭제하거나, 분실물 보관함 디렉터리에서 파일을 원래 경로로 다시 복사해 S3 버전을 덮어쓸 수 있어요.

참고 분실물 보관함 디렉터리의 파일은 그곳에 무기한 남아 파일 시스템 저장 비용에 포함돼요. 더 이상 필요하지 않으면 분실물 보관함 디렉터리에서 파일을 삭제하세요.

동기화 지연

PendingExports CloudWatch 메트릭이 증가하고 있으며, 이는 워크로드가 S3 Files가 S3로 동기화할 수 있는 것보다 빠르게 변경 사항을 생성하고 있다는 것을 나타내요.

이는 워크로드가 동기화 속도를 초과할 수 있음을 의미해요. S3 Files는 파일 시스템당 초당 최대 800개 파일을 내보내요. 파일 수정 속도를 줄이거나 여러 파일 시스템에 작업을 분산하는 것을 고려하세요. 시간에 따른 PendingExports 메트릭을 모니터링하세요. 안정화되거나 감소하면 S3 Files가 따라잡고 있는 것이에요. 계속 증가하면 AWS Support에 문의하세요.

클라이언트 디버그 로그 활성화

마운트, 연결 또는 읽기 우회 문제를 해결하는 경우 S3 Files 클라이언트에 디버그 수준 로깅을 활성화해 더 자세한 내용을 캡처할 수 있어요.

마운트 헬퍼 및 watchdog 로그

/etc/amazon/efs/s3files-utils.conf를 편집하고 로깅 수준을 INFO에서 DEBUG로 변경하세요.

[DEFAULT]
logging_level = DEBUG

변경 사항을 적용하려면 파일 시스템을 마운트 해제하고 다시 마운트하세요.

sudo umount /mnt/s3files
sudo mount -t s3files file-system-id:/ /mnt/s3files

로그는 /var/log/amazon/efs/에 기록돼요. 마운트 헬퍼 로그는 mount.log예요.

프록시(efs-proxy) 로그

프록시는 NFS 트래픽과 S3 읽기 우회를 처리해요. 프록시에 디버그 로깅을 활성화하려면 /etc/amazon/efs/s3files-utils.conf를 편집하세요.

[proxy]
proxy_logging_level = DEBUG

변경 사항을 적용하려면 마운트 해제 후 다시 마운트하세요. 프록시 로그는 /var/log/amazon/efs/에 기록돼요.

TLS 터널(stunnel) 로그

TLS 터널 로그는 기본적으로 비활성화되어 있어요. 활성화하려면 /etc/amazon/efs/s3files-utils.conf를 편집하고 다음을 설정하세요.

[mount]
stunnel_debug_enabled = true

파일 시스템의 모든 stunnel 로그를 단일 파일에 저장하려면 stunnel_logs_file 줄의 주석도 해제하세요.

stunnel_logs_file = /var/log/amazon/efs/{fs_id}.stunnel.log

로그 크기 제한

로그 파일은 자동으로 회전돼요. s3files-utils.conf에서 최대 크기와 회전 파일 수를 구성할 수 있어요.

[DEFAULT]
logging_max_bytes = 1048576
logging_file_count = 10

기본값은 로그 파일당 1MB에 회전 파일 10개로, 로그 유형당 최대 10MB예요.

AWS Support와 로그 공유

AWS Support에 문의할 때 클라이언트 로그와 구성을 단일 아카이브로 수집하세요.

sudo tar -czf /tmp/s3files-support-logs.tar.gz \
  /var/log/amazon/efs/ \
  /etc/amazon/efs/s3files-utils.conf

지원 케이스에 /tmp/s3files-support-logs.tar.gz를 포함하세요.

오류 메시지

다음 표는 발생할 수 있는 오류 메시지와 각각에 대한 권장 조치를 나열해요.

메시지	필요한 조치
Access denied: The provided role does not have permission to call `s3:HeadObject` on the provided bucket.	파일 시스템 IAM 역할에 버킷과 동기화할 충분한 권한이 없어요. 모든 필수 S3 Files 권한을 포함하도록 IAM 정책을 업데이트하세요. 자세한 내용은 S3 Files 전제 조건을 참고하세요.
계정에 허용된 것보다 더 많은 파일 시스템을 만들려고 했어요.	자세한 내용은 지원되지 않는 기능, 제한 및 할당량을 참고하세요. 한도 증가를 요청하는 방법에 대한 정보는 지원되지 않는 기능, 제한 및 할당량을 참고하세요.