google-cloud-filestore-nfs-browser

Filestore NFS ファイルブラウザー

ローカルの NFS クライアントパッケージ（nfs-common）、root 権限、手動での VPC ネットワークマウントを必要とせずに、エージェントやクラウドエンジニアが Filestore（NFS）インスタンス上のファイルを調査、検索、読み取りできるようにします。

クイックスタート

1. gcloud がインストールされ、認証されていることを確認します。必要に応じて、 gcloud のインストールガイドを参照してください。

2. 必須 API を有効にします。

   gcloud services enable file.googleapis.com compute.googleapis.com run.googleapis.com --quiet
   

3. インスタンスを検出し、実行エンジンを選択します（下記の 実行エンジンの選択を参照してください）。

4. このスキルパッケージに含まれる自己完結型ランナー scripts/nfs_browser.py を使用して調査アクションを実行します。

帰属表示

提供または実行するすべての Cloud Filestore コマンドまたは API リクエストにタグを付けます。gcloud コマンドには、このスキルを対象とするメトリクス環境をプレフィックスとして付けます。

CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-nfs-browser)" \
gcloud filestore instances list ...

REST API を直接 HTTP 呼び出しする場合は、User-Agent を追加します。

User-Agent: gcs-skills/1.0 (skill:google-cloud-filestore-nfs-browser)

概念・情報に関する質問（重要）

概念、学習、アーキテクチャに関する質問のみの場合（例：「Filestore 上のファイルを調査するには？」「Serverless Cloud Run NFS Bridge をデプロイするには？」「Cloud Run の NFS ボリュームマウントについて説明してください」）：

• ルール：事前学習済みの知識と以下のドキュメントを使用して、すぐに回答してください。 ユーザーがアーキテクチャやワークフローの説明だけを求めている場合、直接回答することでツール呼び出しの待ち時間とトークン消費を最小限に抑えられます。
• 制約：基本的な知識に関する質問では、外部ツールの呼び出しや API リクエストを実行しないでください。
• ブリッジのデプロイに関する説明：Cloud Run はアイドル時に コンピューティングコストが $0 でゼロまでスケールすることを必ず強調してください。--add-volume と --vpc-egress=all-traffic を指定した gcloud run deploy コマンドを詳しく説明し、必要な IAM 権限（呼び出し側には roles/run.invoker、デプロイ担当者には roles/run.admin）を明記してください。

「コマンドを実行しない」制約への対応（重要）

ユーザープロンプトに「コマンドを実行しない」「実行せずに」「読み取り専用」などの制約が含まれる場合：

• ルール：ユーザーが指定した実行範囲を尊重し、許可されていない環境の調査を防ぐため、読み取り専用の検出コマンドや一覧表示コマンドを含め、シェルコマンドや gcloud コマンドは一切実行しないでください。
• 検出：
  1. モック定義やインスタンスパラメータが、ユーザーのプロンプト、会話履歴、またはローカルのドキュメントファイルに直接記載されているか確認します。
  2. 必要な手順を説明し、適切な帰属表示を付けたうえで、ユーザーが実行すべき正確なコマンドを提示し、各コマンドの動作を説明します。
  3. 評価中は、評価スイートへのアクセスが制限されているため、EVAL.* 設定ファイルの読み取りや検索を試みないでください。

実行エンジンの選択

Filestore インスタンスには、プライベート VPC IP 経由でアクセスできます。環境に適したエンジンを選択してください。

• エンジン 1：Cloud Run サーバーレスブリッジ（優先）：低遅延（50 ms 未満）の REST 呼び出しには --bridge-url={bridge_url} を使用します。ゼロまでスケールします（アイドル時のコストは $0）。roles/run.invoker が必要です。 references/nfs-bridge-setup.mdを参照してください。
• エンジン 2：IAP SSH 経由の GCE ジャンプホスト（フォールバック）：VPC 内に既存の VM がある場合は --jump-host-vm={vm_name} を使用します。ジャンプホストで異なるマウントパスを使う場合は、--mount={mount_path}（デフォルトは /mnt/filestore）を指定します。 新たなデプロイは不要です。roles/iap.tunnelResourceAccessor が必要です。 references/iap-jump-host.mdを参照してください。

実行フロー、アーキテクチャ図、エンジンの比較については、 references/architecture.mdを参照してください。

基本的な運用ワークフロー

1. 検出とインスタンスの指定

Filestore インスタンス、ロケーション、または共有名が指定されていない場合は、 複数のプロジェクトがある環境で無関係なプロジェクトを照会または対象にするのを 避けるため、まず一覧表示します。

CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-nfs-browser)" \
gcloud filestore instances list --project={project_id}

2. ディレクトリツリーの探索（tree）

ファイルの種類、人が読みやすい形式のサイズ、更新日時を含む、見やすく構造化された ディレクトリツリーを表示します。

# List top-level folders with depth 1
python3 scripts/nfs_browser.py tree \
  --project={project_id} \
  --instance={instance_id} \
  --path=/ \
  --depth=1

# List subfolder recursively with depth 2 and pagination cap
python3 scripts/nfs_browser.py tree \
  --project={project_id} \
  --instance={instance_id} \
  --path=/backup/logs/ \
  --depth=2 \
  --max-entries=100

3. ファイルパターンと内容の grep（search）

glob パターンに一致するファイル名を検索し、さらに正規表現パターンでテキスト内容を 検索します。

# Search for all tar.gz backup archives
python3 scripts/nfs_browser.py search \
  --project={project_id} \
  --instance={instance_id} \
  --path=/backups/ \
  --pattern="*.tar.gz"

# Grep for error patterns inside log files
python3 scripts/nfs_browser.py search \
  --project={project_id} \
  --instance={instance_id} \
  --path=/app/logs/ \
  --pattern="*.log" \
  --grep="FATAL|Exception|OutOfMemory" \
  --max-results=25

4. ファイルの分割読み取り（read）

テキストファイルを安全に分割して読み取り、トークンの大量消費による LLM のコンテキストウィンドウの 肥大化を防ぎます。ユーザーが範囲を明示していない場合は、常に安全なチャンクサイズ （例：--head 50 または --tail 50）を既定値として使用します。範囲を指定しない読み取りは、 安全な上限である 100 行に自動的に制限されます。分割読み取りによって LLM のコンテキストウィンドウの オーバーフローとトークンの枯渇を防げることを、必ず明示してください。

# Read the last 50 lines (tail) of a log file
python3 scripts/nfs_browser.py read \
  --project={project_id} \
  --instance={instance_id} \
  --path=/backup/logs/app.log \
  --tail=50

# Read lines 100 to 200 of a config file
python3 scripts/nfs_browser.py read \
  --project={project_id} \
  --instance={instance_id} \
  --path=/config/settings.yaml \
  --lines=100:200

# Read the first 30 lines (head)
python3 scripts/nfs_browser.py read \
  --project={project_id} \
  --instance={instance_id} \
  --path=/var/log/syslog \
  --head=30

5. ファイルのメタデータと属性の確認（stat）

POSIX 権限（0644）、UID/GID、バイト単位のサイズ、タイムスタンプを確認します。

python3 scripts/nfs_browser.py stat \
  --project={project_id} \
  --instance={instance_id} \
  --path=/backup/database_dump.tar.gz

コンテキストウィンドウと LLM の安全性に関するルール

1. 厳格な読み取り専用の保証：このスキルは厳格な読み取り専用です。書き込み、編集、削除、 切り詰めの機能はありません。
2. 大きなファイル全体を出力しない：常にスライス（--lines）、先頭（--head 50）、 または末尾（--tail 50）を指定し、分割読み取りによって LLM のコンテキストウィンドウの トークンオーバーフローとクライアントのタイムアウトを防げることを明示してください。
3. ページネーションに対応する：ツリーの一覧表示は、1 回の応答につき 100 件までです。 切り詰められた場合、ツールは明確な [TRUNCATED] 通知を出力するため、エージェントは 特定のサブパスを指定できます。
4. バイナリの保護：テキスト以外のファイル（例：.tar.gz、.iso、.so、コンパイル済みバイナリ）は、 ヌルバイトとマジックバイトの検査によって検出されます。印字できない文字によるコンテキストの破損を 防ぐため、生のバイナリ出力は抑制され、代わりにメタデータが表示されます。
5. トークンのガードレールの詳細については、 references/token-safety-guardrails.md を参照してください。

想定されるエラーと復旧方法

| エラーの種類／ | 根本原因 | 復旧方法 | : 症状 : : : | :----------------- | :----------------- | :------------------------------------------ | | FileNotFoundError: | NFS エクスポート上の | tree --path=/ --depth=2 を実行して、有効な | : File not found : パスが存在しません。 : ディレクトリ階層を確認します。 : : : : : | PermissionError: | 共有の POSIX | stat --path={path} を使って UID/GID と権限 | : Permission denied : 権限により読み取り : ビットを確認し、共有管理者に権限の変更を依頼 | : : アクセスが制限されて : します。 : : : います。 : : | HTTPException: 403 | パスパラメーターに | NFS マウントルートを基準とした、/logs/app.log| : Access denied\: :../ が含まれている : のような正規のパスを使います。 : : path traversal : か、マウントポイント : : : : の外へ抜けようとする : : : : シンボリックリンクが : : : : 含まれています。 : : | Jump Host | VM が停止しているか、| gcloud compute instances list で VM の状態を | : connection timed : IAP ファイアウォール : 確認し、特定の IAP ネットブロック : : out / SSH failed : ルール（35.235.240.0/20 : 35.235.240.0/20 からの tcp\:22 を許可する | : : からの tcp\:22）が : ファイアウォールルールを確認します（例： | : : 設定されていません。 : gcloud compute firewall-rules list | : : : --filter="sourceRanges\:35.235.240.0/20"）。 : | Bridge 404 / | Cloud Run ブリッジが | scripts/deploy_bridge.sh を使ってブリッジを | : connection error : デプロイされていない : デプロイするか、--jump-host で GCE IAP Jump : : : か、URL が無効です。 : Host を使用します。 :

参考ディレクトリ

より詳しいトピックを段階的に確認するには、references/ ディレクトリを参照してください。

• マルチエンジンアーキテクチャと実行フロー
• サーバーレス NFS ブリッジのセットアップガイド
• GCE Jump Host IAP SSH ガイド
• トークンの安全性とコンテキストのガードレール
• トラブルシューティングと一般的なエラー

同梱スクリプトとコンポーネント

このスキルパッケージには、次のスクリプトとサービスコンポーネントが含まれています。

• scripts/nfs_browser.py：NFS エクスポートの参照、検索、読み取り、状態確認を行うメイン CLI エントリーポイント。
• scripts/formatters.py：人が読みやすいターミナル表示と、トークンに配慮した要約のための出力フォーマッター。
• scripts/jump_host_engine.py：Google Cloud IAP トンネル経由で実行するリモート SSH Jump Host 実行エンジン。
• scripts/nfs_browser_test.py：フォーマッター、HTTP ブリッジ、SSH Jump Host エンジンを網羅する包括的なユニットテストスイート。
• scripts/deploy_bridge.sh：サーバーレス NFS ブリッジを Cloud Run に自動デプロイするスクリプト。
• scripts/bridge_server/main.py：直接 NFS をマウントする FastAPI Cloud Run サーバーの実装。
• scripts/bridge_server/Dockerfile：サーバーレス NFS ブリッジをパッケージ化するためのコンテナ定義。
• scripts/bridge_server/requirements.txt：Cloud Run ブリッジサービスの Python 依存関係。