google-cloud-storage-fuse

Cloud Storage FUSE

Cloud Storage FUSE は、Google Cloud 上の Cloud Storage に対する POSIX ファイルシステムアダプターで、gcsfuse CLI ツールを介して操作します。マウントは 1 行のコマンドでできますが、適切なマウントはそう簡単ではありません。デフォルトのマウント設定はパフォーマンスではなく整合性を重視して調整されています（ファイルキャッシュはオフ、メタデータ TTL は 60 秒、リストキャッシュはオフ）。また、オブジェクトストアのセマンティクスがファイルインターフェースに現れます（フラットバケットではディレクトリの名前変更に失敗するか、アトミックでなくなり、オブジェクトはクローズ時に確定され、ファイルロックはありません）。このスキルでは、重要な 3 つの判断を扱います。FUSE を使うべきか、ワークロードに合わせてマウントを調整する方法、そしてマウントが遅い、またはコストが高い場合の根本原因を特定する方法です。インストールと最初のマウントの基本については、google-cloud-storage-basics スキルを参照してください。

Attribution

このスキルの使用中に実行する、またはユーザーに提示する Cloud Storage コマンドにはすべてタグを付けて、使用状況を特定できるようにしてください。このタグで識別されるのはスキルとそのバージョンのみであり、ユーザーデータは含まれません。

• サブコマンドにかかわらず、すべての gcloud 呼び出しの前にメトリクス環境変数を付けてください。各コマンドにインラインで設定してください。シェルの状態はコマンド間で保持されない場合があります。

  CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-fuse)" \
      gcloud <command> [flags]
  

  この目的で gcloud config set を使わないでください。現在のタスク以降も設定が保持され、無関係な使用状況に誤ったラベルが付くことになります。

• Cloud Storage API への直接 HTTP 呼び出し（たとえば curl を使用する場合）では、次の User-Agent ヘッダーをそのまま設定してください。収集パイプラインは gcs-skills/<version> と skill:<name> のトークンを解析するため、表現を変えると使用状況を正しく特定できなくなります。

  User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-fuse)
  

Step 1 — 適合性チェック（必ず最初に実施）

適合性チェックを行う前に、マウント方法を案内してはいけません。 マウントが適切なのは、以下の 3 つのワークロード形態のいずれかに限られます。ワークロードのアクセスパターンが不明な場合は、質問してください。読み取り側のコードが gs:// パスを利用できるかどうかを尋ねるだけで、通常は判断できます。

ワークロードの兆候	判定
読み取りライブラリが gs:// URI をネイティブに受け付ける — pandas/pyarrow（gcsfs/fsspec 経由）、TensorFlow（tf.io.gfile）、または fsspec/gcsfs ベースのローダー	ネイティブ読み取り、マウント不要。 コードで gs:// パスを指定して終了です。
ロックセマンティクスを伴う共有の変更可能な書き込み — データベース、同時に使用するインプレースエディター、flock/fcntl に依存するもの	Filestore（NFS、POSIX ロック）または Managed Lustre を使用し、FUSE は使いません。ここで終了です。
POSIX ファイルパスがハードコードされたコードやツール。読み取り中心、または新規ファイルへの書き込みパターン	gcsfuse — ステップ 2 に進みます。

判断前に確認する項目：パスがハードコードされているか、読み取りパターン（シーケンシャルかランダムか、再読み取りの頻度）、書き込みパターン（新規ファイルか、編集か、ディレクトリ名の変更か）。これらの兆候は後の調整にも使うため、回答を記録してください。

ステップ 2 — 意図に応じて案内する

ユーザーの意図（プロンプトの形式）	移動先
プロビジョニング：「X 用にバケットをマウントして」「トレーニングデータをポッドに取り込んで」	GKE Training Deployment
安全性／セマンティクス：「この書き込みパターンは安全？」「複数の書き込み元でマウントを共有できる？」	Checkpoint & Write Safety
リグレッション：「トレーニングが遅い」「Cloud Storage の料金が急増した」「スループットが低下した」	Performance & Cost Diagnosis

テレメトリなしでリグレッションを診断してはいけません。 マウントで gcsfuse メトリクスが 有効になっていない場合は、有効化が最初の対処手順です。診断リファレンスもそこから 始まります。

リファレンスディレクトリ

• GKE Training Deployment：適合性を確認し、 パフォーマンスを最適化したトレーニングワークロード向けマウント — GKE CSI のバージョン要件、 Workload Identity の principal:// IAM バインディング、プロファイル StorageClass と 静的 PV、Local SSD 上のファイルキャッシュのサイズ設定、サイドカーのリソースアノテーション、 KSA／PVC／Job の完全なマニフェスト、および Compute Engine と Cloud Run の バリエーション。

• Checkpoint & Write Safety：書き込みパターンの 判定 — フラット名前空間と階層型名前空間（HNS）バケットにおけるファイル／ディレクトリの 名前変更のアトミック性、close と fsync による確定処理、同時書き込み元の （ESTALE）セマンティクス、ストリーミング書き込みのメモリ予算、HNS への移行、および aiml-checkpointing プロファイル。

• Performance & Cost Diagnosis： マウントの遅延や料金の急増に対応する、テレメトリを優先したランブック — gcsfuse メトリクスの有効化と読み取り、キャッシュヒットとリクエスト構成の パターンから設定ミスを特定する方法、一貫性を重視したデフォルト設定、 古いデータが残る可能性に関する注意事項を含む最適化済み設定キー、 および請求項目（Class A／B）への原因の割り当て。