google-cloud-filestore-log-troubleshooting

Filestore のログベースのトラブルシューティング

プロジェクト全体で発生する Filestore クライアントのマウント失敗、権限エラー（EACCES）、ネットワークタイムアウト（ETIMEDOUT）を診断し、トラブルシューティングして修正します。

前提条件とクイックスタート

対象プロジェクト（該当する場合は Shared VPC ホストプロジェクトも含む）で必要な IAM ロール：

• 読み取り：roles/file.viewer（インスタンスとエクスポート ACL）、roles/compute.networkViewer（VPC ファイアウォールルール）、roles/logging.viewer（Cloud Audit と GKE CSI のログ）、roles/mcp.toolUser（MCP ツールを使用する場合）。
• 書き込み（修正のみ）：roles/file.editor（エクスポート ACL の更新）、roles/compute.securityAdmin（ファイアウォールルールの作成）。

認証し、課金と API を確認して、環境を設定します：

gcloud auth login && gcloud auth application-default login
gcloud billing projects describe {project_id} --format="value(billingEnabled)"
gcloud services enable file.googleapis.com compute.googleapis.com logging.googleapis.com --quiet
gcloud config set project {project_id} && gcloud config set compute/region {region}

帰属情報

提供または実行するすべての gcloud コマンドの先頭に、スキルメトリクス環境を付加します：

CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-log-troubleshooting)" \
gcloud filestore instances describe ...

REST API を直接呼び出す場合は、HTTP ヘッダー User-Agent: gcs-skills/1.0 (skill:google-cloud-filestore-log-troubleshooting) を追加します。

概念的・情報的な質問（重要）

純粋に概念的、アーキテクチャ的、または教育的な質問（例：「Filestore で EACCES が発生する原因は何ですか？」「GKE で Pod IP ではなく Node IP が表示されるのはなぜですか？」「Filestore で必要なポートは何ですか？」「root squash について説明してください」）の場合：

• ルール：事前学習済みの知識と以下のワークフロールールを使用して、すぐに回答してください。 ユーザーがアーキテクチャに関するガイダンスだけを求めている場合、直接回答することでツールの待ち時間とトークンの使用量を最小限に抑えられます。
• 制約：基本的な知識に関する質問では、外部ツール呼び出しや API リクエストを実行しないでください。

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

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

• ルール：シェル、Python、または gcloud コマンドを実行するために run_command を呼び出すことは、厳禁です。
• 情報の確認：
  1. まず、Filestore MCP ツール（get_instance、list_instances）が利用可能か確認し、利用可能な場合は使用します（コマンド実行ではなく API 呼び出しです）。
  2. MCP ツールを利用できない場合は、要求されたインスタンスが評価シナリオ（finance-share、shared-nfs、ml-data、data-hub、prod-share）に該当する場合に限り、references/mock-fleet-data.md を読みます。モックデータを本番環境の実際の状態として報告してはいけません。インスタンスがそこに記載されていない場合は、ライブアクセスが必要であることを伝え、ユーザーが実行する正確なコマンドを提示します。
  3. 高速処理の停止ルール：references/mock-fleet-data.md で対象インスタンスを見つけたら、追加ファイルを読むのを直ちに中止し、回答を作成します。コマンド実行が無効になっている場合、scripts/quick_diagnose.py、scripts/diagnose_lib.py、_internal/quick_diagnose_test.py、または EVAL.* ファイルを読んではいけません。コードやテストファイルの確認はターンを無駄にし、タイムアウトを引き起こします。
  4. 必要な診断手順を説明し、手動実行用に帰属情報を付加した正確なコマンドを出力します。
• ユーザーによる確認の必須要件：コマンド実行が無効になっている場合や、ユーザーが推奨事項のみを求めている場合でも、修正を適用する前にユーザーへ明示的な確認を求める質問で、回答を必ず締めくくってください（例：「VPC のイングレスファイアウォールルール [rule_name] の作成に進みますか？続行するには確認してください。」）。

複数ランタイムの実行オプション

オプション 1：同梱の Python CLI スクリプト（CLI／ターミナルエージェントに推奨）

# Single instance diagnosis
python3 scripts/quick_diagnose.py --instance="<INSTANCE_ID>" --location="<LOCATION_OR_ZONE>" \
    [--project="<PROJECT_ID>"] [--client-ip="<CLIENT_IP>"] [--client-subnet="<CLIENT_SUBNET_CIDR>"]

# Bulk project-wide fleet diagnosis
python3 scripts/quick_diagnose.py --all --project="<PROJECT_ID>" [--json]

フラグ	用途
--instance、--location	Filestore のインスタンス ID とリージョン／ゾーン（--zone は旧式のエイリアスです）。--all を指定しない場合は必須です。
--project	GCP プロジェクト ID（アクティブな gcloud プロジェクトがデフォルトです）。
--client-ip / --client-subnet	エクスポート ACL とイングレスファイアウォールルールに照らして評価するクライアント IP または CIDR。
--json	stdout に機械可読な JSON を出力します（説明レポートは stderr に出力されます）。
--apply-fix	生成された修正コマンドを実行します。ユーザーから明示的な確認を得てから指定してください。

オプション 2：Filestore MCP ツール／REST API／gcloud CLI

• MCP ツール：get_instance(name='projects/{project_id}/locations/{location}/instances/{instance_id}') を呼び出し、fileShares[0].nfsExportOptions と networks[0].network を確認します。
• ネイティブ REST API（call_gcp_api）：service="file"、version="v1"、resource_path="projects/{project_id}/locations/{location}/instances/{instance_id}" を指定して呼び出します。
• 標準の gcloud：

  CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-log-troubleshooting)" \
  gcloud filestore instances describe {instance_id} --location={location} --project={project_id} --format=json
  

---

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

ステップ 1：パラメータの抽出と GKE ノードのアーキテクチャ

• instance、location（リージョン／ゾーン）、project、および client_ip／client_subnet を抽出します。対象のパラメータが不足している場合は、インスタンスを一覧表示するか、ユーザーに確認を求めます。
• GKE アーキテクチャのルール：PersistentVolumes は Pod のネットワーク名前空間内ではなく、GKE ワーカーノード上の Linux カーネルによってマウントされます。Pod の IP（10.4.0.0/14）が許可リストに登録されていても、NFS サーバーからは GKE ノードの内部 IP からの通信として認識されます。常に nfsExportOptions と VPC ファイアウォールルールで GKE ノードのサブネット CIDR を評価し、許可リストに登録してください。

ステップ 2：インスタンスのメタデータと Shared VPC の解決

1. インスタンスの state が READY であることを確認します（CREATING、DELETING、または ERROR の場合は、状態が障害要因であることを報告します）。
2. Filestore のプライマリ IP（networks[0].ipAddresses[0]）と VPC ネットワーク URI を抽出します。
3. networks[0].network が projects/{host_project}/global/networks/{network} を参照している場合、ファイアウォールのクエリに使用する Shared VPC ホストプロジェクトとして {host_project} を解決します。

ステップ 3：エクスポート ACL の評価（EACCES と EROFS）

1. fileShares[0].nfsExportOptions を確認します（空の場合は、デフォルトの 0.0.0.0/0 READ_WRITE NO_ROOT_SQUASH が適用されます）。
2. EACCES (Permission Denied by Server)：クライアント IP またはサブネット CIDR が、いずれの ipRanges エントリにも含まれていない場合に発生します。
   • 対処方法：アクティブなマウントへの影響を避けるため、既存のエクスポートルールをすべて保持したまま、クライアント IP／サブネット CIDR を nfsExportOptions に非破壊的に追加します。
3. EROFS (Read-only file system)：accessMode が READ_ONLY に設定されている状態で、クライアントが書き込みを試みた場合に発生します。

ステップ 4：VPC のイングレスファイアウォールの調査（ETIMEDOUT）

1. VPC ネットワーク内のイングレスファイアウォールルールを照会します（Shared VPC の場合はホストプロジェクト内を照会します）。
2. ETIMEDOUT (Connection Timed Out)：優先度順に評価されたイングレスルールによって、クライアント CIDR からの TCP ポート 2049（NFS）および TCP／UDP ポート 111（rpcbind）がブロックされるか、許可されない場合に発生します。
   • 対処方法：クライアントのサブネット CIDR からの ALLOW tcp:2049,udp:2049,tcp:111,udp:111 を指定したイングレスファイアウォールルールを作成します。

ステップ 5：Cloud Audit Logs と設定ドリフトのスキャン

過去 24 時間の Cloud Audit Admin Activity ログ（file.googleapis.com）を照会し、UpdateInstance 操作によってエクスポート ACL またはネットワークが変更されたかどうかを確認します。

CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-log-troubleshooting)" \
gcloud logging read 'logName="projects/{project_id}/logs/cloudaudit.googleapis.com%2Factivity" AND protoPayload.serviceName="file.googleapis.com" AND protoPayload.resourceName=~".*{instance}.*"' \
    --project="{project_id}" --freshness="1d" --limit=5 --format="json"

• Admin Activity に範囲を限定：読み取り専用の GetInstance／ListInstances 呼び出し（data_access）が管理上のドリフトとして誤って判定されないよう、logName に常に cloudaudit.googleapis.com%2Factivity を含めます。
• ドリフトは参考情報：最近の UpdateInstance イベントから、設定が いつ、誰によって（principalEmail、timestamp）変更されたかがわかりますが、マウントの障害要因となるのは、エクスポート ACL またはファイアウォールのチェックに失敗した場合のみです。
• 一括クエリは 1 回のみ：複数のインスタンス（--all）をスキャンする場合は、インスタンスごとのクエリをループで実行せず、プロジェクト全体を対象とした監査ログクエリを 1 回実行します。
• GKE CSI ドライバーのログ：必要に応じて、クライアント側のマウントエラーを確認するため、resource.labels.container_name="gcp-filestore-driver"（severity>=ERROR）を調べます。

---

出力形式と必須の確認ゲート

すべての診断レポートに、構造化された概要表と根本原因の分析を必ず含めてください。

### Filestore Diagnostic Report: `[instance-name]`

| Parameter | Value |
| :--- | :--- |
| **Instance ID** | `[instance-name]` (`[location]`, Tier: `[tier]`, State: `READY`) |
| **Filestore IP & Network** | `[filestore-ip]` on VPC `[network-name]` (Host Project: `[host-project]`) |
| **Port 2049 & Export ACL** | Port 2049: `OPEN / BLOCKED` \| Export ACL: `PASS / REJECTED` |
| **Diagnostic Verdict** | **HEALTHY** or **BLOCKED: [Root Cause]** |

#### Root Cause Analysis & Recommended Remediation
- [Explanation of ETIMEDOUT (missing firewall rule on port 2049) vs EACCES (missing export ACL rule) and any recent UpdateInstance audit drift]

```bash
CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-log-troubleshooting)" \
gcloud compute firewall-rules create ...
```

対話型の修復確認ゲート（必須）

• ユーザーの明示的な確認なしに、書き込みコマンドや修復コマンドを絶対に実行しないでください。
• 応答の最後には、必ず明示的な確認の質問を添えてください。

  「この修復コマンドを実行してもよろしいですか？続行するには確認してください。」

参考資料と同梱スクリプト

• エラーシグネチャとアーキテクチャのマトリックス
• クラウドロギングと監査ドリフトのクエリ
• VPC ネットワークとファイアウォールの仕様
• 評価用のモックフリートデータ
• scripts/quick_diagnose.py と scripts/diagnose_lib.py：依存関係不要の CLI ランナーと純粋な Python の評価エンジン。