gcs-fuse-csi-driver Profiles Recommender sre ops guide

Profiles Recommender SRE 运维指南

受众: SRE、平台运维工程师
场景: 日志分析、故障排查、容量规划、告警配置

1. 运维概览

Profiles Recommender 运行在 CSI Node 插件（DaemonSet）内部，在每次NodePublishVolume（Pod 挂载 GCS Bucket）时执行。它不是独立进程，无需单独部署或维护。

关键特性:

• 无状态：每次调用独立计算，无持久化数据
• 失败安全：推荐失败时 fallback 到用户原始挂载选项
• 可观测：每次推荐输出结构化 JSON 日志

2. 日志格式与查询

2.1 日志结构

每次 Profiles Recommender 执行时输出一条 JSON 格式日志到 stdout（绕过 klog 格式化）：

{"severity":"INFO","message":"GCSFuseCSIRecommendation: ... FileCache: 512MiB (ram) | MetadataStatCache: 64MiB | Expand for full details","target":{"pvName":"pvc-abc123","nodeName":"gke-pool-1-xyz","podName":"default/my-training-pod"},"inputSignals":{"bucketTotalObjects":10000,"bucketTotalDataSizeBytes":536870912000,"bucketLocationType":"multi-region","bucketHNSEnabled":false,"requiredFileCacheBytes":536870912000,"requiredMetadataStatCacheBytes":17000000,"nodeType":"gpu","nodeAllocatableMemoryBytes":274877906944,"nodeAllocatableEphemeralStorageBytes":402653184000,"nodeHasEphemeralStorageLSSD":true,"sidecarLimitMemoryBytes":6442450944,"sidecarLimitEphemeralStorageBytes":0,"fuseBudgetMemoryBytes":4509715660,"fuseBudgetEphemeralStorageBytes":342254906400},"decision":{"metadataStatCacheBytes":17000000,"fileCacheBytes":342254906400,"fileCacheMedium":"lssd"}}

2.2 关键字段说明

2.3 日志查询示例

# 查找所有文件缓存被禁用的挂载kubectl logs-lapp=gcsfuse-csi-node --all-containers|\grep"GCSFuseCSIRecommendation"|\jq'select(.decision.fileCacheBytes == 0)'# 查找 stat cache 被截断的情况kubectl logs-lapp=gcsfuse-csi-node --all-containers|\grep"GCSFuseCSIRecommendation"|\jq'select(.inputSignals.requiredMetadataStatCacheBytes > .decision.metadataStatCacheBytes)'# 按节点汇总推荐情况kubectl logs-lapp=gcsfuse-csi-node --all-containers|\grep"GCSFuseCSIRecommendation"|\jq-r'.target.nodeName'|sort|uniq-c|sort-rn

3. 排障决策树

4. 常见故障及处理

4.1 挂载失败：PV 注解缺失

现象:NodePublishVolume返回Internal错误
日志关键词:missing required annotation

处理步骤:

1. 检查 PV 注解：

   kubectl getpv<pv-name>-ojsonpath='{.metadata.annotations}'|jq.

2. 确认 Bucket Scanner Controller 正常运行：

   kubectl get pods-nkube-system-lapp=bucket-scanner

3. 临时解决：手动添加 override 注解：

   kubectl annotatepv<pv-name>\gke-gcsfuse/bucket-scan-status=override\gke-gcsfuse/bucket-scan-num-objects=<估算值>\gke-gcsfuse/bucket-scan-total-size-bytes=<估算值>\gke-gcsfuse/bucket-scan-location-type=multi-region\gke-gcsfuse/bucket-scan-hns-enabled=false

4.2 文件缓存始终被禁用

现象:decision.fileCacheBytes == 0

排查方向:

4.3 Stat Cache 被截断导致性能下降

现象: 大量stat操作延迟高

诊断:

# 对比 required vs actualjq'select(.inputSignals.requiredMetadataStatCacheBytes > .decision.metadataStatCacheBytes) | {pod: .target.podName, required: .inputSignals.requiredMetadataStatCacheBytes, actual: .decision.metadataStatCacheBytes}'

解决: 增加 sidecar container 的 memory limit，或降低fuseMemoryAllocatableFactor（注意：降低 factor 意味着给文件缓存更少空间）。

4.4 LSSD 检测失败

现象: 节点有 Local SSD 但nodeHasEphemeralStorageLSSD == false

诊断:

kubectl getnode<node-name>-ojsonpath='{.metadata.annotations.node\.gke\.io/last-applied-node-labels}'

检查输出中是否包含cloud.google.com/gke-ephemeral-storage-local-ssd=true。若 GKE 版本更新了标注方式，此检测可能失效。

5. 容量规划

5.1 资源预算公式

effectiveLimit = min(nodeAllocatable, sidecarLimit) budget = effectiveLimit × allocatableFactor

• 内存预算默认: 70% × min(节点可分配内存, sidecar memory limit)
• 临时存储预算默认: 85% × min(节点可分配临时存储, sidecar ephemeral-storage limit)

5.2 节点规划建议

5.3 多 Pod 同节点注意事项

每个 Pod 独立计算预算，不感知其他 Pod。若 10 个 Pod 落在同一节点：

• 有 sidecarLimit: 每 Pod 限于其 limit × factor，安全
• 无 sidecarLimit: 每 Pod 各自认为可用节点 70% 内存，叠加可能 OOM

建议: 始终为 gcsfuse sidecar 设置resources.limits。

6. 告警建议

告警查询示例 (Cloud Logging)

resource.type="k8s_container" resource.labels.container_name="gcs-fuse-csi-driver" jsonPayload.message=~"GCSFuseCSIRecommendation" jsonPayload.decision.fileCacheBytes=0 jsonPayload.inputSignals.bucketLocationType!="zonal"

7. 监控指标

当前推荐器不直接暴露 Prometheus 指标，但可从结构化日志导出：

8. Runbook

RB-1: 批量 Pod 挂载失败（Scanner 故障）

紧急恢复: 对所有受影响 PV 添加 override 注解，恢复挂载。

RB-2: 节点内存压力（多 Pod 缓存争抢）

1. 识别受影响节点：

   kubectltopnodes|sort-k4-rn|head

2. 查看该节点上的推荐日志：

   kubectl logs-nkube-system<csi-node-pod>|grep"GCSFuseCSIRecommendation"|\jq'select(.target.nodeName == "<问题节点>") | {pod: .target.podName, memBudget: .inputSignals.fuseBudgetMemoryBytes, statCache: .decision.metadataStatCacheBytes, fileCache: .decision.fileCacheBytes}'

3. 临时缓解：
   • 降低fuseMemoryAllocatableFactor到 0.5
   • 或为 sidecar 添加/减少 memory limit
4. 长期方案：
   • 分散 Pod 到更多节点
   • 使用 Pod Anti-Affinity 避免过度集中

RB-3: 切换节点池后缓存策略异常

当节点从 LSSD 节点池迁移到非 LSSD 节点池时，推荐器可能从 LSSD 降级到 RAM 或直接禁用文件缓存。

1. 确认新节点的 LSSD 注解状态
2. 如需强制使用 RAM 缓存，用户可手动设置file-cache:max-size-mb
3. 或在 StorageClass 中调整fuseFileCacheMediumPriority移除 lssd 选项

9. 已知运维影响