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 节点 IP 而不是 Pod IP？”、“Filestore 需要哪些端口？”、“解释 root squash”）：

• 规则：立即使用预训练知识和以下工作流规则作答。 用户仅寻求架构指导时，直接回答可以减少工具延迟和令牌用量。
• 限制：对于基础知识问题，不要执行外部工具调用或 API 请求。

处理“禁止执行命令”限制（重要）

如果用户提示中包含“不要执行命令”“不执行命令”或“只读”等限制：

• 规则：严格禁止调用 run_command 来执行任何 shell、Python 或 gcloud 命令。
• 发现信息：
  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 / 终端 Agent）

# 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 由 GKE 工作节点上的 Linux 内核挂载，而非挂载在 Pod 网络命名空间内。即使 Pod IP（10.4.0.0/14）已列入允许列表，NFS 服务器看到的流量也源自 GKE 节点内部 IP。务必在 nfsExportOptions 和 VPC 防火墙规则中评估并允许 GKE 节点子网 CIDR。

步骤 2：实例元数据与共享 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}，则将 {host_project} 解析为用于防火墙查询的共享 VPC 宿主项目。

步骤 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 网络中的入站防火墙规则（如果使用共享 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 范围：在 logName 中始终包含 cloudaudit.googleapis.com%2Factivity，以免将只读的 GetInstance / ListInstances 调用（data_access）误判为管理配置漂移。
• 漂移仅供参考：近期的 UpdateInstance 事件可说明配置在何时以及由谁（principalEmail、timestamp）更改，但只有导出 ACL 或防火墙检查失败才构成挂载阻碍。
• 单次批量查询规则：扫描多个实例（--all）时，应执行一次项目范围的审计日志查询，而非在循环中逐个查询实例。
• 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：零依赖命令行运行器和纯 Python 评估引擎。