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 マネージドポリシー」を参照してください。ルートアクセスがない – root (UID 0) が所有するファイルにアクセスするときにアクセス許可エラーが発生した場合、IAM ロールに
s3files:ClientRootAccessアクセス許可がない可能性があります。このアクセス許可がない場合、すべてのオペレーションは NFS 匿名ユーザー (通常は nfsnobody) として実行され、ファイルにアクセスできない可能性があります。AmazonS3FilesClientFullAccessマネージドポリシーをアタッチするか、ポリシーにs3files:ClientRootAccessを追加します。ファイルシステムポリシーによるアクセス拒否 – ファイルシステムポリシーをアタッチしている場合は、クライアントが必要とするアクションが拒否されていないことを確認します。アクセスするには、アイデンティティベースのポリシーまたはファイルシステムポリシーのいずれかの「許可」で十分です。詳細については、「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 サポートにお問い合わせください。
ファイルシステムの書き込み後に 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 は循環依存関係 (2 つのファイルの名前を互いの名前に変更した場合など) を解決できませんでした。このエラーを解決するには、ディレクトリパスを短くします。 |
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 キー名へのアクセスをサポートしていません。互換性のないキー名を持つオブジェクトは、ファイルシステムにインポートされません。
lost and found ディレクトリに表示されるファイル
ファイルは、ファイルシステムのルートディレクトリにある .s3files-lost+found- ディレクトリに表示されます。この場合、file-system-idLostAndFoundFiles CloudWatch メトリクスの増加を確認できます。これは、同期の競合が発生した場合に発生します。競合は、同じファイルがファイルシステムを介して変更され、S3 Files がファイルシステムの変更を S3 に同期する前に対応する S3 オブジェクトが変更された場合に発生します。S3 Files は、S3 バケットを信頼できるソースとして扱い、競合するファイルを lost and found ディレクトリに移動し、S3 バケットからファイルシステムに最新バージョンをインポートします。
lost and found ディレクトリ内のファイルを識別する
S3 Files がファイルを lost and found ディレクトリに移動すると、時間の経過とともに移動される可能性がある同じファイルの複数のバージョンを区別するために、ファイル名の前に 16 進数の識別子を付加します。ファイル名が 100 文字を超える場合は、この識別子のためのスペースを確保するために切り捨てられます。ファイルの元のディレクトリパスは、lost and found ディレクトリには保持されません。
実行するアクション
ファイルの元のパスと対応する 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 バケットから最新バージョンを保持し、lost and found ディレクトリからファイルを削除するか、lost and found ディレクトリから元のパスにファイルをコピーして S3 バージョンを上書きすることができます。
注記
lost and found ディレクトリ内のファイルは無期限に残り、ファイルシステムのストレージコストにカウントされます。不要になったファイルは、lost and found ディレクトリから削除します。
同期が遅れる
PendingExports CloudWatch メトリクスが増加しており、ワークロードが S3 Files が S3 と同期できる速度よりも速く変更を生成していることを示しています。
つまり、ワークロードが同期レートを超えている可能性があることを意味します。S3 Files は、ファイルシステムごとに 1 秒あたり最大 800 ファイルをエクスポートします。ファイル変更の速度を下げたり、複数のファイルシステムに作業を分散することを検討してください。PendingExports メトリクスを経時的にモニタリングします。安定または減少すると、S3 Files は追い付いてきます。増加が続く場合は、AWS サポートにお問い合わせください。
クライアントデバッグログを有効にする
マウント、接続、または読み取りバイパスの問題をトラブルシューティングする場合は、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 ログを 1 つのファイルに保存するには、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
デフォルトはログファイル 1 つあたり 1 MB で、ローテーションされるファイルは 10 個、ログタイプあたり最大 10 MB です。
AWS サポートとのログの共有
AWS サポートに連絡するときは、クライアントログと設定を 1 つのアーカイブにまとめます。
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 を含めます。
