Storage Gateway (S3 File Gateway) のキャッシュレポート機能を試してみた

はじめに

テクニカルサポートの 片方 です。
少し前になりますが 2025 年 3 月 31 日に、S3 File Gateway にキャッシュレポート機能が追加されました。

https://docs.aws.amazon.com/ja_jp/filegateway/latest/files3/DocumentHistory.html

キャッシュレポート機能を追加
S3 ファイルゲートウェイは、特定のファイル共有のローカルアップロードキャッシュに現在含まれているファイルについて、メタデータのレポートを生成できるようになりました。

この機能を利用すると、S3 File Gateway の特定のファイル共有について、ローカルアップロードキャッシュに現在含まれているファイルのメタデータを CSV 形式で出力できます。
特に、S3 バケットへのアップロードに失敗しているファイルについて、ファイルパスや S3 オブジェクトキー、アップロード失敗理由などを確認できる点が便利です。
これまで CloudWatch メトリクスを確認することで、アップロードに失敗しているファイルが存在することは把握できました。一方で、どのファイルが、どのような理由でアップロードに失敗しているのかを確認するには、追加の調査が必要でした。
本ブログでは、EC2 インスタンス上に S3 File Gateway をデプロイし、別の EC2 インスタンスから NFS マウントして検証します。そのうえで、S3 バケットポリシーを利用して意図的に S3AccessDenied を発生させ、キャッシュレポートにアップロード失敗ファイルがどのように出力されるのかを確認していきます。

S3 File Gateway のキャッシュレポート機能とは

S3 File Gateway のキャッシュレポートは、特定のファイル共有について、ローカルアップロードキャッシュ内にあるファイルのメタデータを CSV 形式で出力する機能です。

https://docs.aws.amazon.com/ja_jp/filegateway/latest/files3/create-cache-report.html

このレポートを利用すると、指定したフィルター条件に一致するファイルを CSV 形式で確認できます。特に、S3 バケットへのアップロードに失敗しているファイルの確認に利用できます。
レポートには、ファイルパス、S3 オブジェクトキー、アップロード状態、アップロード失敗理由などが含まれます。
例えば、S3 バケットへの書き込み権限が不足している場合、対象ファイルの UploadError に S3AccessDenied が出力されます。これにより、CloudWatch メトリクスでアップロード失敗を検知したあと、どのファイルが、どのような理由で失敗しているのかを確認しやすくなります。
キャッシュレポートでは、主に以下のような情報を確認できます。

キャッシュレポートのフィルターで指定できるアップロード失敗理由には、S3AccessDenied、ObjectMissing、InvalidObjectState、InaccessibleStorageClass があります。

https://docs.aws.amazon.com/ja_jp/filegateway/latest/files3/manage-cache-reports.html
https://docs.aws.amazon.com/ja_jp/filegateway/latest/files3/understand-cache-reports.html

冒頭でもお伝えした通り本ブログでは、このうち S3AccessDenied を意図的に発生させ、キャッシュレポートにどのように出力されるかを確認します。

本機能の前提条件/考慮事項

キャッシュレポートを作成するには、いくつかの前提条件があります。今回の検証で特に意識した点をドキュメントに沿って整理しました。

前提条件

考慮事項

今回の検証では、以下の点を考慮しました。

• データ保存用 S3 バケットと、キャッシュレポート出力用 S3 バケットは分ける
• レポート出力先の S3 バケットには、検証対象のデータファイルとは別のライフサイクルルールやアクセス制御を設定できるようにする
• キャッシュレポートにはファイルパスや S3 オブジェクトキーが含まれるため、レポート出力先 S3 バケットへのアクセス権限に注意する
• 今回はアップロード失敗理由として S3AccessDenied を確認するため、データ保存用 S3 バケットの一部プレフィックスに対して意図的に s3:PutObject を拒否する
• 検証後は、追加した Deny のバケットポリシーを必ず削除する
• ファイルのアップロード失敗フラグは 24 時間ごと、および Gateway の再起動時にリセットされるため、アップロード失敗が発生してから 24 時間以内にレポートを作成する
• 通常運用で VPC エンドポイントを利用して S3 バケットに接続している場合は、キャッシュレポート作成時も同じ VPC エンドポイントの利用を検討する

また、キャッシュレポートのレコードを Storage Gateway コンソールから削除しても、S3 バケットに出力された CSV ファイルは削除されません。不要になったレポートファイルは、S3 ライフサイクルルールや手動削除などで管理するのをお勧めします。

検証環境の構成

今回は、EC2 インスタンス上にデプロイした S3 File Gateway を利用し、別の EC2 インスタンスから NFS マウントする構成で検証しました。
本ブログではキャッシュレポート機能の確認に焦点を当てるため、S3 File Gateway の作成手順や EC2 インスタンスから NFS マウントする手順の詳細は省略します。
上記を実装する流れについては、以下の弊社ブログをご参考ください。

https://dev.classmethod.jp/articles/storage-gateway-ec2-2021/

キャッシュレポートを作成する手前まで、以下の状態を準備しておきます。

• S3 File Gateway が作成済みであること
• S3 File Gateway がオンラインであること
• S3 File Gateway にキャッシュ用ディスクが割り当て済みであること
• NFS ファイル共有が作成済みであること
• EC2 インスタンスから NFS ファイル共有をマウント済みであること
• NFS マウント先に作成したファイルが、データ保存用 S3 バケットへアップロードされることを確認済みであること

なお、データ保存用 S3 バケットと、キャッシュレポート出力用 S3 バケットは分けています。
今回の検証では、データ保存用 S3 バケットの一部プレフィックスに対して、意図的に s3:PutObject を拒否します。レポート出力先まで同じ S3 バケットにしていると、権限設定の影響でキャッシュレポートの出力自体が失敗する可能性があります。
そのため、以下のように用途ごとに S3 バケットを分けました。

やってみた

ここからは、NFS マウント済みの状態を前提に進めます。
まずは通常のファイルアップロードができることを再度確認し、その後、データ保存用 S3 バケットの一部プレフィックスに対して意図的に s3:PutObject を拒否します。これにより、S3 File Gateway から S3 へのアップロードに失敗する状態を作ります。

正常に S3 へアップロードされることを再確認する

データ保存用 S3 バケットへアップロードされることを確認します。
NFS マウント先に移動し、テストファイルを作成します。

$ cd /storage/
$ touch test-v1

S3 バケットへアップロードされていますので、S3 File Gateway と NFS マウントの基本的な動作に問題がないことを確認できました。

意図的に S3AccessDenied を発生させる

次に、キャッシュレポートでアップロード失敗ファイルを確認するため、意図的に S3AccessDenied を発生させます。
今回は、データ保存用 S3 バケットの access-denied-test オブジェクトに対して、S3 File Gateway のファイル共有が利用する IAM ロールからの s3:PutObject を拒否します。
データ保存用 S3 バケットのバケットポリシーに、以下のステートメントを追加します。

{
  "Sid": "DenyFileGatewayPutObjectForCacheReportTest",
  "Effect": "Deny",
  "Principal": {
    "AWS": "<FILE_SHARE_S3_ACCESS_ROLE_ARN>"
  },
  "Action": "s3:PutObject",
  "Resource": "arn:aws:s3:::<DATA_BUCKET_NAME>/access-denied-test"
}

• <FILE_SHARE_S3_ACCESS_ROLE_ARN> は、S3 File Gateway のファイル共有が利用している IAM ロール ARN に置き換えてください
• <DATA_BUCKET_NAME> は、S3 File Gateway のファイル共有に紐づけているデータ保存用 S3 バケット名に置き換えてください

バケットポリシーを設定したら、NFS マウント先に拒否対象のファイルを作成します。

$ cd /storage/
$ echo "access denied test" > access-denied-test
$ sync

S3 File Gateway から S3 へのアップロードは非同期で行われるため、少し待ってから S3 バケット側を確認します。
では、S3 バケット側で、対象オブジェクトが存在しないことを確認します。

$ aws s3 ls s3://<DATA_BUCKET_NAME>/access-denied-test

検証時では、何も出力されませんでした。
access-denied-test はバケットポリシーで s3:PutObject を拒否しているため、S3 バケットにはアップロードされない想定です。
一方で、NFS マウント先ではファイルを確認できます。

$ ls -l /storage/access-denied-test

sh-5.2$ aws s3 ls s3://storage-gateway-data-bucket-test-v1/access-denied-test
sh-5.2$ ls -l /storage/access-denied-test
-rw-r--r--. 1 ssm-user ssm-user 19 May 31 07:25 /storage/access-denied-test

NFS マウント先にはファイルが存在していますが、S3 バケット側には対象オブジェクトが存在しません。
これで、S3 File Gateway のローカルキャッシュにはファイルが存在しているものの、S3 へのアップロードには失敗している状態を作成できました。

確認してみた

ここからは、前のセクションで作成したアップロード失敗状態のファイルが、キャッシュレポートにどのように出力されるかを確認します。

キャッシュレポート出力用 IAM ロールを準備する

キャッシュレポートを作成するには、レポート出力先の S3 バケットへ書き込むための IAM ロールが必要です。
この IAM ロールは、Storage Gateway がキャッシュレポート CSV をレポート出力用 S3 バケットへ保存するために利用します。S3 File Gateway のファイル共有がデータ保存用 S3 バケットへアクセスする IAM ロールとは用途が異なります。
キャッシュレポートを保存する S3 バケットに対して、指定する IAM ロールに以下の権限が必要です。

• s3:PutObject
• s3:AbortMultipartUpload

また、storagegateway.amazonaws.com が sts:AssumeRole できる信頼ポリシーも必要です。
信頼ポリシー例は以下です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowStorageGatewayAssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": "storagegateway.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowStorageGatewayWriteCacheReport",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::<REPORT_BUCKET_NAME>/*"
    }
  ]
}

<REPORT_BUCKET_NAME> は、キャッシュレポート出力用 S3 バケット名に置き換えてください。
今回は、データ保存用 S3 バケットとは別に、キャッシュレポート出力用 S3 バケットを指定しています。

キャッシュレポートを作成する

Storage Gateway コンソールから、対象のファイル共有を選択します。
対象のファイル共有を開いたら、[アクション] から [キャッシュレポートの作成] を選択します。

※ アップロードに失敗したファイルが検出された場合、上部に通知されるようです

今回の検証では、ファイル共有を S3 VPC エンドポイント経由で構成していないため、[VPC エンドポイントを使用して S3 に接続しますか?] では [バケットに直接接続] を選択しました。
この項目では、ゲートウェイがレポート出力先の S3 バケットへ接続する方法を指定します。選択肢の違いは以下です。

通常運用でファイル共有が VPC エンドポイントを使用して S3 に接続している場合は、キャッシュレポート作成時も同じ VPC エンドポイントの利用を検討します。

キャッシュレポートを作成すると、対象ファイル共有の [キャッシュレポート] タブから進行状況を確認できます。
ステータスが COMPLETED (完了しました) になるまで待ちます。

出力された CSV を確認する

キャッシュレポートが完了すると、指定した S3 バケットに CSV ファイルが出力されます。

出力された CSV ファイルを確認します。

CSV から、今回作成した access-denied-test がキャッシュレポートに出力されていることを確認できました。
今回の出力結果では、主に以下の項目を確認しました。

UploadError に S3AccessDenied が出力されており、バケットポリシーで s3:PutObject を拒否したことにより、S3 へのアップロードに失敗していることを確認できました。
また、FilePath に /access-denied-test が出力されているため、NFS マウント先で作成したファイルを特定できます。
これにより、CloudWatch メトリクスだけでは分かりづらい「どのファイルが、どのような理由でアップロードに失敗しているのか」を確認できました。

補足

キャッシュレポートを設定すると、以下のような出力もあるようです。

まとめ

S3 File Gateway のキャッシュレポート機能を使い、アップロードに失敗しているファイルと失敗理由を CSV で確認できました。今回は、バケットポリシーで意図的に S3AccessDenied を発生させ、キャッシュレポートに UploadError として出力されることを確認しました。
CloudWatch メトリクスでアップロード失敗を検知し、キャッシュレポートで対象ファイルを特定するという使い方が有効そうですね。本ブログが皆様の参考となれば幸いです。

参考資料

• Amazon S3 ファイルゲートウェイユーザーガイドのドキュメント履歴 - AWS Storage Gateway
• S3 ファイルゲートウェイのキャッシュレポートを作成する - AWS Storage Gateway
• S3 ファイルゲートウェイのキャッシュレポートの表示と管理 - AWS Storage Gateway
• S3 ファイルゲートウェイキャッシュレポートで提供される情報について - AWS Storage Gateway
• [Storage Gateway] EC2からS3バケットをNFSマウントしてみた～2021年冬～ | DevelopersIO

クラスメソッドオペレーションズ株式会社について

クラスメソッドグループのオペレーション企業です。
運用・保守開発・サポート・情シス・バックオフィスの専門チームが、IT・AIをフル活用した「しくみ」を通じて、お客様の業務代行から課題解決や高付加価値サービスまでを提供するエキスパート集団です。
当社は様々な職種でメンバーを募集しています。
「オペレーション・エクセレンス」と「らしく働く、らしく生きる」を共に実現するカルチャー・しくみ・働き方にご興味がある方は、クラスメソッドオペレーションズ株式会社 コーポレートサイト をぜひご覧ください。※2026年1月 アノテーション㈱から社名変更しました