Profiles Recommender 用户指南受众: 集群用户、ML 工程师、数据科学家前提: 已部署 GCS FUSE CSI Driver 并启用 Profiles 特性1. 功能简介Profiles Recommender 是一个自动缓存调优系统。当你通过 CSI Driver 挂载 GCS Bucket 时它会根据你的 Bucket 大小对象数量和数据总量所在节点的硬件类型GPU / TPU / 通用节点可用内存和临时存储容量自动计算最优的stat cache和file cache配置无需你手动计算和设置。一句话总结: 把性能调参的认知负担从你转移到系统。2. 启用 Checklist在推荐器生效前你需要确保以下条件全部满足CSI Driver 已启用GCSFuseProfilesFeature Flag使用静态 PV非临时卷ephemeralPV 上有 Bucket Scanner 写入的注解自动完成StorageClass 上有标签gke-gcsfuse/profile: true缺少任一条件推荐器不会激活你的挂载选项保持不变。3. 快速开始3.1 创建启用 Profiles 的 StorageClassapiVersion:storage.k8s.io/v1kind:StorageClassmetadata:name:gcsfuse-profileslabels:gke-gcsfuse/profile:true# 必须启用推荐器provisioner:gcsfuse.csi.storage.gke.ioparameters:# 可选调整推荐行为fuseMemoryAllocatableFactor:0.7fuseEphemeralStorageAllocatableFactor:0.85fuseFileCacheMediumPriority:gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd3.2 创建 PVBucket Scanner 会自动填充注解apiVersion:v1kind:PersistentVolumemetadata:name:my-training-data# 以下注解由 Bucket Scanner Controller 自动写入# annotations:# gke-gcsfuse/bucket-scan-status: ready# gke-gcsfuse/bucket-scan-num-objects: 50000# gke-gcsfuse/bucket-scan-total-size-bytes: 107374182400# gke-gcsfuse/bucket-scan-location-type: multi-region# gke-gcsfuse/bucket-scan-hns-enabled: falsespec:storageClassName:gcsfuse-profilescsi:driver:gcsfuse.csi.storage.gke.iovolumeHandle:my-bucket-name3.3 正常使用 PVC 和 PodapiVersion:v1kind:PersistentVolumeClaimmetadata:name:my-training-data-pvcspec:storageClassName:gcsfuse-profilesvolumeName:my-training-dataaccessModes:[ReadWriteMany]resources:requests:storage:5Gi---apiVersion:v1kind:Podmetadata:name:training-jobspec:containers:-name:trainerimage:my-training-imagevolumeMounts:-name:datamountPath:/datavolumes:-name:datapersistentVolumeClaim:claimName:my-training-data-pvc挂载时推荐器会自动计算最优缓存参数并注入到 gcsfuse 启动选项中。4. 配置参考4.1 StorageClass 参数参数默认值类型说明fuseFileCacheMediumPrioritygpu:ram|lssd,tpu:ram,general_purpose:ram|lssdstring按节点类型配置存储介质优先级fuseMemoryAllocatableFactor0.7float64gcsfuse 可使用的节点内存比例fuseEphemeralStorageAllocatableFactor0.85float64gcsfuse 可使用的临时存储比例4.2 StorageClass 标签必须labels:gke-gcsfuse/profile:true4.3 PV 注解Bucket Scanner 自动写入注解类型说明gke-gcsfuse/bucket-scan-statusstringready或overridegke-gcsfuse/bucket-scan-num-objectsint64 stringBucket 对象总数gke-gcsfuse/bucket-scan-total-size-bytesint64 stringBucket 数据总大小字节gke-gcsfuse/bucket-scan-location-typestring如multi-region,region,zonalgke-gcsfuse/bucket-scan-hns-enabledtrue/false是否为 HNS (Hierarchical Namespace) Bucket5. 覆盖推荐值推荐器遵循用户覆盖始终获胜原则。有两种方式手动控制缓存配置5.1 通过 Mount Options 覆盖在 PV 或 Pod 的mountOptions中直接指定缓存大小spec:csi:volumeAttributes:mountOptions:stat-cache-max-size-mb:128,file-cache:max-size-mb:1024指定了某缓存类型的值后推荐器对该类型的智能推荐将完全跳过。支持的覆盖 keyKey效果stat-cache-max-size-mb或metadata-cache:stat-cache-max-size-mb固定 stat cache 大小file-cache-max-size-mb或file-cache:max-size-mb固定 file cache 大小5.2 通过手动 PV 注解覆盖 Bucket 信号当 Bucket Scanner 尚未就绪或你想自行指定 Bucket 数据量时metadata:annotations:gke-gcsfuse/bucket-scan-status:overridegke-gcsfuse/bucket-scan-num-objects:100000gke-gcsfuse/bucket-scan-total-size-bytes:536870912000gke-gcsfuse/bucket-scan-location-type:multi-regiongke-gcsfuse/bucket-scan-hns-enabled:false5.3 优先级层次用户 mountOptions (CLI 格式) 推荐器输出 (config-file 格式) SC mountOptions6. 典型场景示例6.1 GPU 训练节点 —— 100GB Bucket256GB 节点内存输入信号:numObjects 50,000 → stat cache 需要 ~81 MiBtotalSizeBytes 100 GiB → 文件缓存需要 100 GiB节点类型: GPU, 256 GiB 可分配内存Sidecar limit: 6 GiB memory推荐结果:stat cache: 81 MiB (RAM) ✅ — 完全满足file cache: 无法满足100 GiB 6GiB × 0.7 4.2 GiB尝试 LSSD → 若节点有 Local SSD 且空间足够 → 使用 LSSD否则文件缓存禁用6.2 TPU 推理节点 —— 小 Bucket (1000 对象, 500MB)输入信号:numObjects 1,000 → stat cache ~1.6 MiBtotalSizeBytes 500 MiB → 文件缓存 500 MiB节点类型: TPU仅支持 RAMSidecar limit: 2 GiB memory推荐结果:stat cache: 1.6 MiB (RAM) ✅剩余 memory budget: 2GiB × 0.7 - 1.6MiB ≈ 1.4 GiBfile cache: 500 MiB (RAM) ✅ — 完全放入 RAM6.3 通用节点 —— Zonal Bucket输入信号:locationType “zonal”推荐结果:stat cache: 正常推荐file cache:0zonal bucket 延迟已经很低缓存收益不大7. 自定义文件缓存卷如果你已自行挂载了高性能缓存卷如 RAM disk 或 NVMe可以在 Pod 上添加标签告知推荐器metadata:labels:gke-gcsfuse/cache-created-by-user:true此时推荐器将设置 file cache -1 (unlimited) 并跳过介质选择让 gcsfuse 使用你提供的缓存卷。8. FAQQ: 推荐器会覆盖我手动设置的 mountOptions 吗不会。用户显式设置的值始终获胜。推荐器只填充你未设置的缓存参数。Q: 我使用 Ephemeral Volume 能用 Profiles 吗不能。Ephemeral Volume 没有 PV 对象因此无法携带 Bucket Scanner 注解。推荐器需要这些数据来做出推荐。Q: 如果 Bucket Scanner 还没扫描完挂载会失败吗会。如果 PV 上缺少必需的bucket-scan-*注解NodePublishVolume会返回 Internal 错误。确保 Scanner 在挂载前完成或使用override模式手动设置。Q: 多个 Pod 挂载同一 Bucket 会冲突吗每个 Pod 独立推荐互不感知。同节点多 Pod 情况下通过设置 sidecar container 的resources.limits来限制每个 Pod 的资源消耗。Q: 推荐器怎么决定用 RAM 还是 Local SSD按 StorageClass 中配置的fuseFileCacheMediumPriority优先级列表依次尝试。GPU 节点默认先试 RAM、不够再试 LSSDTPU 节点只试 RAM。Q: 我的 Bucket 有 10TB 数据文件缓存会是 10TB 吗不会。推荐器会用节点/sidecar 的资源预算截断。如果没有任何存储介质能容纳所需缓存文件缓存会被禁用设为 0。不做部分缓存。Q: 怎么确认推荐器实际使用了什么参数查看 CSI Node 插件日志搜索GCSFuseCSIRecommendation。每次挂载都会输出一条 JSON 日志包含所有输入信号和最终决策。