S3 Files 문제 해결
이 페이지에서는 S3 Files의 일반적인 문제를 진단하고 해결할 수 있습니다.
탑재 명령 실패
mount -t s3files 명령이 실패하고 오류가 발생합니다.
일반적인 원인 및 작업:
‘mount.s3files: 명령을 찾을 수 없음’ – S3 Files 클라이언트(amazon-efs-utils)가 설치되지 않았거나 버전 3.0.0 미만입니다. 클라이언트를 설치 또는 업그레이드합니다. 자세한 내용은 S3 Files의 사전 조건 섹션을 참조하세요.
‘파일 시스템 DNS 이름 확인 실패’ - EC2 인스턴스가 실행 중인 가용 영역에 탑재 대상이 없습니다. 해당 가용 영역에서 탑재 대상을 생성하거나 탑재 대상이 있는 가용 영역에서 인스턴스를 시작합니다. 자세한 내용은 탑재 대상 생성 섹션을 참조하세요.
연결 시간 초과 - 보안 그룹 구성이 NFS 트래픽을 허용하지 않습니다. 탑재 대상의 보안 그룹이 인스턴스의 보안 그룹에서 포트 2049의 인바운드 TCP를 허용하고 인스턴스의 보안 그룹이 포트 2049의 아웃바운드 TCP를 탑재 대상의 보안 그룹으로 허용하는지 확인합니다. 자세한 내용은 S3 Files의 사전 조건 섹션을 참조하세요.
탑재 중 ‘액세스 거부됨’ - 컴퓨팅 리소스에 연결된 IAM 역할에 필요한 S3 Files 권한이 없습니다. 역할에
AmazonS3FilesClientFullAccess또는AmazonS3FilesClientReadOnlyAccess관리형 정책이 연결되어 있는지 또는 최소한s3files:ClientMount권한이 연결되어 있는지 확인합니다. 자세한 내용은 S3 Files의 사전 조건 섹션을 참조하세요.botocore가 설치되지 않음 - 탑재 도우미가 AWS 서비스와 상호 작용하려면 botocore가 필요합니다. GitHub의 amazon-efs-utils README의 지침에 따라 botocore를 설치합니다.
파일 작업에 대한 권한 거부
파일 시스템을 탑재할 수 있지만 파일을 읽거나 쓰거나 액세스할 때 ‘권한 거부’ 또는 "작업이 허용되지 않음" 오류가 발생합니다.
일반적인 원인 및 작업:
쓰기 권한 누락 - 읽을 수 있지만 쓸 수 없는 경우 컴퓨팅 리소스에 연결된 IAM 역할에
s3files:ClientWrite권한이 포함되어 있는지 확인하거나AmazonS3FilesClientReadWriteAccess또는AmazonS3FilesClientFullAccess관리형 정책을 연결합니다. 자세한 내용은 Amazon S3 Files용 AWS 관리형 정책을 참조하세요.루트 액세스 누락 - 루트(UID 0)가 소유한 파일에 액세스할 때 권한 오류가 발생하면 IAM 역할에
s3files:ClientRootAccess권한이 없을 수 있습니다. 이 권한이 없으면 모든 작업이 파일에 액세스할 수 없는 NFS 익명 사용자(일반적으로 nfsnobody)로 수행됩니다.AmazonS3FilesClientFullAccess관리형 정책을 연결하거나 정책에s3files:ClientRootAccess를 추가합니다.파일 시스템 정책 액세스 거부 - 파일 시스템 정책을 연결한 경우 클라이언트에 필요한 작업을 거부하지 않는지 확인합니다. 자격 증명 기반 정책 또는 파일 시스템 정책의 ‘허용’이면 액세스하기에 충분합니다. 자세한 내용은 IAM과 함께 S3 Files을 사용하는 방법 섹션을 참조하세요.
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의 사전 조건 섹션을 참조하세요. |
S3BucketNotFound |
소스 S3 버킷이 더 이상 존재하지 않거나 이름이 변경되었습니다. 예상 AWS 리전 및 계정에 존재하는지 확인합니다. |
InternalError |
내부 시스템 오류가 발생했습니다. |
S3UserMetadataTooLarge |
S3 사용자 메타데이터 크기 제한을 초과했습니다. 이러한 한도에 대한 내용은 지원되지 않는 기능, 제한 및 할당량 섹션을 참조하세요. |
FileSizeExceedsS3Limit |
파일 크기가 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바이트를 초과하는 키 이름이 있는 S3 키 이름에 대한 액세스를 지원하지 않습니다. 호환되지 않는 키 이름을 가진 객체는 파일 시스템으로 가져오지 않습니다.
분실한 디렉터리에 나타나는 파일
파일이 파일 시스템의 루트 .s3files-lost+found- 디렉터리에 있는 디렉터리에 표시되었습니다. 이 경우 file-system-idLostAndFoundFiles 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 클라이언트에서 디버그 수준 로깅을 활성화하여 자세한 내용을 캡처할 수 있습니다.
탑재 도우미 및 감시 로그
/etc/amazon/efs/s3files-utils.conf를 편집하여 로깅 수준을 INFO에서 DEBUG로 변경합니다.
[DEFAULT] logging_level = DEBUG
변경 사항을 적용하려면 파일 시스템을 탑재 해제했다가 다시 탑재합니다.
sudo umount /mnt/s3files sudo mount -t s3filesfile-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
기본값은 교체된 파일 10개가 있는 로그 파일당 1MB이며 로그 유형당 최대 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를 포함합니다.
