troubleshooting-s3-files

S3 Files のトラブルシューティング

概要

Amazon S3 Files の問題を診断し、解決します。マウントの失敗、IAM 権限、同期、競合の解決、パフォーマンスを扱います。

公式のガイダンスについては、S3 Files のトラブルシューティングを参照してください。

よくあるタスク

0. 依存関係を確認する

• aws CLI が s3files サブコマンドをサポートしていることを必ず確認してください
• 有効な AWS 認証情報があることを必ず確認してください
• ツールの存在とバージョンのみを確認してください。確認中に破壊的なコマンドや変更を伴うコマンドを実行してはいけません
• 必須ツールが不足している場合は、必ずユーザーに伝えてください
• ツールが利用できない場合、ユーザーが中止する判断を尊重してください
• コマンドを実行する前に手順を説明し、書き込みコマンドについてはユーザーの確認を待つことを推奨します

1. 問題を分類する

症状	カテゴリ
mount.s3files: command not found	A：クライアントのインストール
マウント中に接続がタイムアウトする	B：ネットワーク／セキュリティグループ
マウントが無期限に停止する（タイムアウトなし）	B：ネットワーク／セキュリティグループ
マウント中にアクセスが拒否される	C：IAM 権限
ファイルシステムが「creating」のまま停止する	C：IAM 権限
ファイル操作で権限が拒否される	C：IAM 権限
書き込み後、S3 にファイルが表示されない	D：同期
.s3files-lost+found ディレクトリにファイルがある	E：競合の解決
読み取りが遅い、またはレイテンシーが高い	F：パフォーマンス
NFS サーバーエラー	G：暗号化／KMS
DNS 名の解決に失敗する	H：VPC DNS

2. カテゴリ A — クライアントのインストール

mount.s3files: command not found は、amazon-efs-utils が存在しないか、バージョンが 3.0.0 未満であることを意味します。

sudo yum -y install amazon-efs-utils  # Amazon Linux

3. カテゴリ B — ネットワーク／セキュリティグループ

接続タイムアウトはマウント失敗の第 1 位の原因であり、ほとんどの場合、セキュリティグループが原因です。

インスタンスの AZ にマウントターゲットがあることを確認します。

aws s3files list-mount-targets --file-system-id fs-ID --region REGION

AZ をまたいだマウントも機能しますが、レイテンシーが増加します。

セキュリティグループを確認します。最もよくある解決方法です。

• マウントターゲットの SG には、コンピューティング SG からのインバウンド TCP 2049 を必ず許可してください
• コンピューティング SG には、マウントターゲット SG へのアウトバウンド TCP 2049 を必ず許可してください
• 修正方法：aws ec2 authorize-security-group-ingress --group-id sg-MT --protocol tcp --port 2049 --source-group sg-COMPUTE

接続をテストします。

nc -zv az-ID.fs-ID.s3files.REGION.on.aws 2049

注： これらの SG のトラブルシューティング手順は EFS にも適用されます。代わりに aws efs describe-mount-targets を使用してください。

分離された VPC でマウントが停止する場合： VPC にインターネットアクセスがない場合、マウントを完了するには S3 Files に CloudWatch Logs VPC エンドポイント（com.amazonaws.REGION.logs）が必要です。

4. カテゴリ C — IAM 権限

ファイルシステムのステータスが「creating」のまま停止する場合： S3 Files は作成時に IAM ロールの権限を検証しません。信頼ポリシーの誤り、または権限の不足があると、statusMessage にアクセス拒否が表示された状態で creating のまま停止します。

ステータスを確認します。

aws s3files get-file-system --file-system-id fs-ID --region REGION

statusMessage を確認してください。アクセス拒否が表示されている場合は、IAM ロールを修正してから削除し、再作成してください。

マウント時にアクセスが拒否される場合： コンピューティングロールには s3files:ClientMount が必要です。開発／テスト環境に限り、AmazonS3FilesClientFullAccess を使用できます。本番環境では避けてください。

書き込み権限が拒否される場合： コンピューティングロールには s3files:ClientWrite が必要です。

ルートアクセスが拒否される場合： コンピューティングロールには s3files:ClientRootAccess が必要です。⚠️ POSIX 権限を迂回するため、POSIX ユーザーを範囲指定できるアクセスポイントを優先してください。

ファイルシステムポリシーを確認します。

aws s3files get-file-system-policy --file-system-id fs-ID --region REGION

5. カテゴリ D — 同期

S3 にファイルが表示されない場合： 書き込みは約 60 秒以内に同期されます。ステータスを確認します。

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

よくある ExportError 値：

エラー	対処方法
S3AccessDenied	ファイルシステムの IAM ロールに S3 書き込み権限がありません
S3BucketNotFound	バケットが削除または名前変更されています
RoleAssumptionFailed	信頼ポリシーが正しく設定されていません
EncryptionKeyInaccessible	KMS キーが無効になっているか、権限が取り消されています
PathTooLong	ファイルパスが S3 キーの上限である 1,024 バイトを超えています

PendingExports CloudWatch メトリクスを監視します。増加している場合、毎秒 800 ファイルのレートを超えています。

6. カテゴリ E — 競合の解決

.s3files-lost+found-{fs-id} 内のファイル = 同期競合（FS と S3 の両方で同時に変更された場合）。S3 が優先され、FS バージョンは lost+found に移動されます。

7. カテゴリ F — パフォーマンス

初回アクセス時のレイテンシー： 正常です。初回のディレクトリアクセス時にメタデータがインポートされます。

インテリジェントな読み取りルーティングが機能しない： コンピューティングロールには、バケットに対する s3:GetObject が必要です。

書き込みが遅い： PendingExports が増加している場合は、複数のファイルシステムに分散させてください。

8. カテゴリ G — 暗号化／KMS

暗号化された FS で NFS サーバーエラーが発生する場合は、KMS の問題です。キーが有効で、ロールに KMS 権限があることを確認してください。

9. カテゴリ H — VPC DNS

DNS 解決エラーが発生する場合は、VPC の DNS 設定が無効になっています。

aws ec2 describe-vpc-attribute --vpc-id vpc-ID --attribute enableDnsHostnames
aws ec2 describe-vpc-attribute --vpc-id vpc-ID --attribute enableDnsSupport

両方とも true である必要があります。そうでない場合は、次のようにします。

aws ec2 modify-vpc-attribute --vpc-id vpc-ID --enable-dns-hostnames Value=true
aws ec2 modify-vpc-attribute --vpc-id vpc-ID --enable-dns-support Value=true

トラブルシューティング

AWS CLI のエンドポイント URL を解決できない

CLI のバージョンが古く、S3 Files に対応していません。aws --version を実行してください。v1.x の場合は、AWS CLI v2 にアップグレードします：AWS CLI のインストール。

ECS タスクで DNS 解決エラーが発生する

s3filesVolumeConfiguration ではなく efsVolumeConfiguration が使用されています。修正方法：S3 Files 専用のボリューム設定で fileSystemArn を使用してください。

S3 Files と他の製品の混同

S3 Files は Mountpoint for S3、S3 File Gateway、File Cache とは異なります。aws s3files CLI、s3files: IAM アクション、mount -t s3files を使用します。

デバッグログを有効にする

/etc/amazon/efs/s3files-utils.conf で logging_level = DEBUG を設定します。ログは /var/log/amazon/efs/mount.log にあります。

AWS サポート用にログを収集する

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

セキュリティに関する考慮事項

• IAM の問題を診断する際は、最小権限を確認してください。手っ取り早い方法として FullAccess を使用しないでください
• ファイルシステムポリシーがない場合、VPC 内のすべてのクライアントがマウントできます
• /var/log/amazon/efs/ へのアクセスを制限してください。ログには S3 キー名が含まれます

追加リソース

• S3 Files のトラブルシューティング
• S3 Files のベストプラクティス
• S3 Files のクォータ