Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用 Cloud Storage FUSE 分析结果自动进行性能调优

Autopilot Standard

本文档介绍了如何在 Google Kubernetes Engine (GKE) 上使用 Cloud Storage FUSE 配置文件自动调整 Cloud Storage FUSE CSI 驱动程序的性能，并加速 AI/机器学习工作负载的数据访问。

Cloud Storage FUSE 配置文件可自动执行关键的性能调优流程。您可以应用预定义的配置文件来为您配置 CSI 驱动程序，而无需手动调整设置。对于 AI/机器学习应用，使用这些配置文件可以缩短训练和推理时间，并减少运营开销。

本文档适用于希望在没有深厚的存储调优专业知识的情况下提高应用性能的应用开发者和机器学习 (ML) 工程师。如需详细了解常见角色，请参阅常见的 GKE 用户角色和任务。

在阅读本文档之前，请确保您熟悉 Cloud Storage、Kubernetes 和 Cloud Storage FUSE CSI 驱动程序的基础知识。另请查看使用 Cloud Storage FUSE CSI 驱动程序的要求。

使用 Cloud Storage FUSE 配置文件的优势

为了自动调整 AI/ML 工作负载的性能，Cloud Storage FUSE 配置文件会使用预定义的 Cloud Storage FUSE 配置并应用其他特定于 GKE 的设置。这些设置基于 Cloud Storage FUSE 性能调优最佳实践。使用预定义配置文件具有以下优势：

简化了性能调优：使用预定义的 Cloud Storage FUSE 配置文件，为常见的 AI/机器学习工作负载（例如训练、部署和检查点设置）应用经过优化的配置。
动态的资源感知优化：使用 Cloud Storage FUSE 配置文件可让 CSI 驱动程序根据存储桶或子目录的特征（例如大小、对象数量和位置类型）、边车限制以及节点的可用资源自动调整缓存大小并选择最佳缓存介质（例如 RAM 或本地 SSD）。
提升读取性能：使用 gcsfusecsi-serving 配置文件时，GKE 会自动启用 Rapid Cache，以提升服务工作负载的读取性能。
性能调优数据洞见：您可以通过结构化日志详细了解环境中的输入信号以及驱动程序应用的最终配置，从而深入了解自动调优决策。如需了解详情，请参阅查看建议数据分析

随着 Cloud Storage FUSE 最佳实践的不断发展，这些配置文件会通过新的 GKE 版本进行更新。

限制

您无法将 Cloud Storage FUSE 配置文件与 Cloud Storage FUSE CSI 临时卷搭配使用。
这些配置文件不支持动态装载，在动态装载中，您会指定下划线 (_) 以装载 Kubernetes ServiceAccount 可以访问的所有存储分区。
不支持使用自定义私有边车映像替换边车映像。如需了解详情，请参阅为边车容器配置私有映像。

要求

您的 GKE 集群必须运行 1.35.1-gke.1616000 版或更高版本。
您的集群必须已启用 Cloud Storage FUSE CSI 驱动程序。如果您要创建新集群，或在现有集群上启用该驱动程序，请参阅文档中的以下步骤，为 GKE 设置 Cloud Storage FUSE CSI 驱动程序：

费用

除了与 Cloud Storage FUSE CSI 驱动程序相关的标准 GKE 和 Cloud Storage 费用之外，使用 Cloud Storage FUSE 配置文件还会产生以下费用。

存储分区扫描费用

Cloud Storage FUSE 分析文件会对您的存储桶或子目录执行后台扫描。默认情况下，此扫描每 7 天进行一次。扫描存储分区会产生列出对象的 Cloud Storage A 类操作费用。

Rapid Cache 费用

gcsfusecsi-serving 配置文件会自动启用快速缓存，该功能会按照 Cloud Storage 快速缓存价格计费。为避免在不再需要缓存实例时产生相关费用，请参阅费用控制。

准备工作

在开始之前，请确保您已执行以下任务：

启用 Cloud Storage API 和 Google Kubernetes Engine API。

启用 API

如果您要使用 Google Cloud CLI 执行此任务，请安装并初始化 gcloud CLI。如果您之前安装了 gcloud CLI，请通过运行 gcloud components update 命令来获取最新版本。较早版本的 gcloud CLI 可能不支持运行本文档中的命令。
注意：对于现有 gcloud CLI 安装，请务必设置 compute/region 属性。如果您主要使用可用区级集群，请改为设置 compute/zone。通过设置默认位置，您可以避免 gcloud CLI 中出现如下错误：One of [--zone, --region] must be supplied: Please specify location。如果集群的位置与您设置的默认位置不同，您可能需要在某些命令中指定位置。

选择适合您需求的 Google Cloud 区域。虽然我们建议您在同一区域中创建 GKE 集群和 Cloud Storage 存储桶，以优化性能和费用，但如果您使用 gcsfusecsi-serving 配置文件或计划启用快速缓存，则必须这样做。
确保您已有一个 Cloud Storage 存储桶，其中包含 AI/ML 工作负载所需的数据集、模型或检查点。如果您需要创建存储桶，请参阅创建存储桶。

选择性能配置

选择最适合您工作负载的配置文件。每个配置文件都对应于集群上预安装的 StorageClass。如需详细了解 Cloud Storage FUSE 配置文件的定义，请参阅相应的 StorageClass 配置参考。

个人资料	StorageClass 名称	优化目标	主要特性
培训	`gcsfusecsi-training`	高吞吐量读取	在大型数据集上训练期间，优化 GPU 和 TPU 的数据延迟。
检查点	`gcsfusecsi-checkpointing`	高吞吐量写入	最大限度地缩短保存大型检查点所需的时间，从而减少训练停顿。
服务	`gcsfusecsi-serving`	数据访问和缓存	默认启用 Rapid Cache 以加快读取操作。

您可以通过运行以下命令来验证集群中安装的 StorageClass：

kubectl get sc -l gke-gcsfuse/profile=true

配置 IAM 权限

授予 GKE 服务代理分析 Cloud Storage 存储桶和管理快速缓存的权限。

运行本部分中的命令时，请替换以下占位符：

GCS_PROJECT：包含 Cloud Storage 存储桶的项目 ID。
PROJECT_NUMBER：GKE 集群项目的项目编号。
BUCKET_NAME：Cloud Storage 存储桶的名称。

选择以下与您的个人资料和使用需求相符的选项。

方案 A：自定义角色（推荐）

对于 Serving 配置文件或使用 Rapid Cache 的情况，此选项是必需的。如果您使用投放配置文件，或者计划为其他配置文件手动启用快速缓存，则必须授予管理该缓存的权限。

创建自定义 IAM 角色，以允许扫描对象和创建快速缓存：

gcloud iam roles create gke.gcsfuse.profileUser \
  --project=GCS_PROJECT \
  --title="GKE GCSFuse Profile User" \
  --description="Allows scanning Cloud Storage buckets for objects, retrieving bucket metadata, and creating caches." \
  --permissions="storage.objects.list,storage.buckets.get,storage.anywhereCaches.create,storage.anywhereCaches.get,storage.anywhereCaches.list,storage.anywhereCaches.update"

将自定义角色绑定到特定存储桶的 GKE 服务代理：

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
  --project=GCS_PROJECT \
  --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot." \
  --role="projects/GCS_PROJECT/roles/gke.gcsfuse.profileUser"

选项 B：训练和检查点配置文件的标准角色

如果您仅使用训练或检查点配置，并且不打算使用快速缓存，请运行以下命令：

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --project=GCS_PROJECT \
    --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot." \
    --role="roles/storage.legacyBucketReader"

部署具有 Cloud Storage FUSE 配置的工作负载

请按照以下步骤部署具有 Cloud Storage FUSE 配置的工作负载。

创建一个引用某个 Cloud Storage FUSE 配置文件 StorageClass 的 PersistentVolume (PV) 清单：
```
apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  mountOptions:
    - only-dir=BUCKET_DIR_PATH # Optional
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
```
替换以下内容：
- STORAGECLASS_NAME：您要使用的配置文件的 StorageClass 名称。值必须为 gcsfusecsi-training、gcsfusecsi-checkpointing 或 gcsfusecsi-serving。
- BUCKET_DIR_PATH：（可选）Cloud Storage 存储桶中的路径（如果您要装载特定目录）。如果指定，GKE 会扫描此路径以进行优化。如果省略，GKE 会扫描整个存储桶。
- BUCKET_NAME：您在配置对 Cloud Storage 存储桶的访问权限时指定的 Cloud Storage 存储桶名称。

创建一个请求的 StorageClass 与 PV 相同的 PersistentVolumeClaim (PVC)：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
  namespace: NAMESPACE
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  volumeName: my-pv
  storageClassName: STORAGECLASS_NAME

替换以下内容：

NAMESPACE：您要在其中部署 Pod 的命名空间。
STORAGECLASS_NAME：PV 中列出的 StorageClass 名称。

在 Deployment 中使用 PVC：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  namespace: NAMESPACE
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: my-container
        image: busybox
        volumeMounts:
        - name: my-gcs-volume
          mountPath: "/data"
      volumes:
      - name: my-gcs-volume
        persistentVolumeClaim:
          claimName: my-pvc

替换以下内容：

NAMESPACE：您要在其中部署 Pod 的命名空间。
KSA_NAME：您在配置对 Cloud Storage 存储分区的访问权限时创建的 Kubernetes ServiceAccount 名称。

部署后，CSI 驱动程序会根据节点资源（例如 GPU 或 TPU、内存、本地 SSD、存储桶或子目录大小）以及边车资源限制自动计算最佳缓存大小和装载选项。

验证自动化优化

GKE 后台进程会自动分析您的存储桶，并同步快速缓存（如果正在使用）。

检查存储桶扫描和缓存的状态

创建 PV 后，请按照以下步骤检查存储桶扫描和缓存的状态。您无需等待 Pod 部署完成。

检查 PV 状态：
```
kubectl describe pv my-pv
```

在输出中，验证是否显示了 ScanOperationSucceeded 事件。输出类似于以下内容：

Normal  ScanOperationSucceeded  gke-gcsfuse-scanner  Bucket scan completed successfully for bucket "my-bucket", directory "my-dir": "526893" objects, "57690897566" bytes

如果您使用 gcsfusecsi-serving 配置文件，请验证 AnywhereCacheSyncSucceeded 事件是否在缓存层准备就绪后出现。输出类似于以下内容：
```
Normal  AnywhereCacheSyncSucceeded  gke-gcsfuse-scanner  Anywhere Cache sync succeeded for PV "my-pv": us-central1-c:running
```
注意：快速缓存创建过程可能需要几分钟到几小时。在此期间，您的工作负载不会被阻止，并且可以从存储桶中直接读取数据，直到缓存正常运行。如需了解详情，请参阅创建缓存。

验证 PV 注释是否已使用扫描结果进行更新：

gke-gcsfuse/bucket-scan-status: completed
gke-gcsfuse/bucket-scan-num-objects: 526893
gke-gcsfuse/bucket-scan-total-size-bytes: 57690897566
gke-gcsfuse/bucket-scan-location-type: multi-region
gke-gcsfuse/bucket-scan-hns-enabled: true
gke-gcsfuse/bucket-scan-last-updated-time: 2025-12-10T22:48:38Z

检查 Pod 状态

部署 Pod 后，运行以下命令：

kubectl get pods -n NAMESPACE

将 NAMESPACE 替换为您部署 Pod 的命名空间。

您的 Pod 现在应处于 RUNNING 状态，并且已自动应用性能最佳实践。如果您的 Pod 显示 SchedulingGated 状态，则表示 GKE 仍在扫描您的存储桶或子目录。在 CSI 控制器完成扫描并更新 PV 之前，Pod 会一直处于此状态。

如需了解驱动程序在 Pod 启动后记录的特定调优决策，请参阅查看建议数据分析。

如果您遇到任何错误，请参阅问题排查部分。

StorageClass 配置参考文档

本部分提供了预安装的 Cloud Storage FUSE 配置文件的 StorageClass 清单，以及有关配置文件所用装载选项和参数的详细参考信息。借助这些配置，gcsfuse.csi.storage.gke.io 驱动程序可以自动执行性能调优和资源管理，从而优化 AI/机器学习工作负载。

培训

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-training
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-training
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

检查点

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-checkpointing
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-checkpointing
  - read_ahead_kb=1024
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

服务

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-serving
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-serving
  - read_ahead_kb=131072
  - file-cache:max-size-mb:0
  - read:enable-buffered-read:true
  - read:global-max-blocks:80
parameters:
  anywhereCacheZones: "*"
  anywhereCacheAdmissionPolicy: "admit-on-first-miss"
  anywhereCacheTTL: "1h"
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

配置文件针对 gcsfuse.csi.storage.gke.io 驱动程序使用以下装载选项和参数：

mountOptions:
- profile：应用针对 AI/ML 工作负载量身定制的一组预定义的 Cloud Storage FUSE 优化。预安装配置的有效值为 aiml-training、aiml-checkpointing 和 aiml-serving。
- read_ahead_kb：指定预读缓冲区的大小（以千字节 [KB] 为单位）。此选项允许 Cloud Storage FUSE 从 Cloud Storage 中预提取数据，从而可能提高顺序访问模式的读取性能。
- file-cache:max-size-mb：对于 Serving 配置文件，指定文件缓存的最大大小（以兆比字节 [MiB] 为单位）。在服务工作负载中，模型通常只加载到 GPU 或 TPU 内存中一次，因此此参数设置为 0 以停用本地 Cloud Storage FUSE 文件缓存，从而有助于防止冗余磁盘 I/O 并节省本地存储空间。
- read:enable-buffered-read：对于 Serving 配置文件，可让 Cloud Storage FUSE 管理自己的内部缓冲区，这有助于减少应用与内核之间的小型、昂贵的系统调用次数。
- read:global-max-blocks：对于 Serving 配置文件，限制用于缓冲读取的并发内存块的总数。此选项有助于防止 FUSE 进程在处理多个请求时消耗所有可用 RAM。
parameters:
- skipCSIBucketAccessCheck：设置为 "true" 时，使 CSI 驱动程序跳过初始存储桶访问权限检查。此参数有助于减少对 Security Token Service 的调用，从而避免潜在的配额问题。
- gcsfuseMetadataPrefetchOnMount：设置为 "true" 时，指示 CSI 驱动程序在卷装载后立即开始将对象元数据从 Cloud Storage prefetching到本地缓存中。此参数可加快对文件的首次访问速度。
- fuseFileCacheMediumPriority：定义 Cloud Storage FUSE 文件缓存所用存储介质的优先级顺序。它允许为具有 GPU、TPU 或通用节点的节点指定不同的偏好设置。媒体选项包括 ram 和 lssd（本地 SSD，如果可用且已启用）。
- fuseMemoryAllocatableFactor：以字符串格式指定一个分数，用于限制 Cloud Storage FUSE 缓存可消耗的最大内存，该值相对于节点的可分配总内存和边车的内存限制。
- fuseEphemeralStorageAllocatableFactor：限制节点上临时存储空间（例如用于文件缓存的本地 SSD）的 Cloud Storage FUSE 缓存使用量，相对于节点的可分配临时存储空间或为缓存限制的边车临时存储空间。
- bucketScanResyncPeriod：设置重新扫描 PV 以检测对 Cloud Storage 存储桶所做更改的时间间隔。
- bucketScanTimeout：单个存储桶扫描操作允许的最长持续时间。如果扫描时间超过此时间，系统可能会使用部分结果。
- anywhereCacheZones：指定以英文逗号分隔的支持的可用区列表，快速缓存将在这些可用区中创建，例如 "us-central1-a,us-central1-b"。如需使用集群可用的所有可用区，请使用 "*" 作为值。将此值设置为 "none" 或不指定此值会停用快速缓存。
- anywhereCacheTTL：存储在快速缓存中的数据的存留时间 (TTL)，从上次访问时开始计算。如果您更改此值，系统会使用新的 TTL 更新现有的快速缓存实例。
- anywhereCacheAdmissionPolicy：确定在发生读取未命中（即在缓存中找不到请求的数据）后，何时将数据纳入快速缓存。选项包括 "admit-on-first-miss"（在第一次读取未命中时准许数据）或 "admit-on-second-miss"（仅在第二次读取未命中同一对象时准许数据）。如果您更改此值，现有的快速缓存实例会更新为新政策。

可选：微调配置文件

您可以自定义配置文件的特定设置，同时仍能受益于其基本配置。您可以使用以下选项来调整配置，而无需创建新的 StorageClass。

替换装载选项和参数

如需修改特定行为，请在 PV 的 spec.mountOptions 字段中添加装载选项，或在 spec.csi.volumeAttributes 字段中添加 CSI 参数。GKE 会在配置文件的默认设置之上应用您的手动设置。

以下示例展示了如何替换 read_ahead_kb 装载选项并在 Serving 配置文件中停用 gcsfuseMetadataPrefetchOnMount 参数。

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: gcsfusecsi-serving
  mountOptions:
  - read_ahead_kb=2048 # Overrides the profile's default.
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: my-gcs-bucket
    volumeAttributes:
      gcsfuseMetadataPrefetchOnMount: "false" # Overrides the profile's default.

常见用例包括下列各项：

如需为训练配置文件启用快速缓存，请将 anywhereCacheZones 参数直接添加到 PV 规范中。
调整特定的 Cloud Storage FUSE 行为，例如增加 read_ahead_kb 大小，以满足特定工作负载的独特需求。

手动配置缓存大小时，请考虑以下事项：

指定手动缓存大小只会替换相应特定组件的自动动态调整大小功能。在剩余资源预算范围内，所有其他组件将继续尽力进行动态调整大小。
设置 metadata-cache 或 file-cache 选项（例如 metadata-cache:stat-cache-max-size-mb）不会停用其他缓存类型的自动计算功能。
如果您手动指定了 file-cache:max-size-mb，则还必须配置自定义读取缓存卷。这有助于确保为自定义缓存大小明确定义具有足够容量的存储介质。

使用注释绕过存储桶扫描

您可以使用注释提供自己的对象数量和大小指标，从而绕过自动存储桶扫描流程。CSI 驱动程序使用这些值来计算最佳性能配置，而无需扫描存储桶。

以下示例展示了如何将 gke-gcsfuse/bucket-scan-status: "override" 注解添加到 PV，以及如何添加特定的指标注解。

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
  annotations:
    gke-gcsfuse/bucket-scan-status: "override"
    gke-gcsfuse/bucket-scan-num-objects: 19238
    gke-gcsfuse/bucket-scan-total-size-bytes: 94837465
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME

常见用例包括下列各项：

如果您已经知道存储桶的大小和对象数量，尤其是对于数据很少变化的推理工作负载，您可以在启动时跳过扫描时间。
如果 Cloud Storage API 暂时不可用，这些注释可帮助您在修复底层服务期间保持性能。

问题排查

您可以使用以下信息来监控 Cloud Storage FUSE 配置文件的状态，并解决在存储桶扫描和缓存同步期间遇到的常见问题。

配置参数无效 (`InvalidArgument`)

由于清单中提供的一个或多个参数无效，后台优化任务未能启动。

症状

PV 显示 ScanOperationStartError 或 AnywhereCacheSyncError 事件，且消息包含 rpc error: code = InvalidArgument。例如：

Bucket scan timeout configuration error: rpc error: code = InvalidArgument desc = invalid duration format for "INVALID_DURATION".
Anywhere Cache sync failed for PV "PV_NAME": rpc error: code = InvalidArgument desc = failed to get anywhere cache "CACHE_NAME" ... invalid anywhere cache "CACHE_NAME" provided.

原因

PV 的 spec.csi.volumeAttributes 字段中的一个或多个参数格式不正确，或者包含系统无法解析的值。

解决方法

更正 PV 清单中的无效参数值，然后重新部署 PV。确保所有时长值（例如 bucketScanTimeout）都使用正确的格式（例如 2m 或 10m），并且所有特定于配置文件的设置都与有效的支持值相匹配。

扫描 Cloud Storage 存储桶时权限遭拒

GKE 无法访问指定的 Cloud Storage 存储桶来执行所需的性能分析。

症状

PV 显示 ScanOperationStartError 事件，其中包含一条 Error 403: Forbidden 消息，表明调用者没有 storage.buckets.get 访问权限。

原因

GKE 服务代理缺少所需的 IAM 权限，或者存储桶名称不正确。

解决方法

验证 PV 的 volumeHandle 字段中的存储桶名称是否正确，以及该存储桶是否存在。
确保已向特定存储桶的 service-PROJECT_NUMBER@container-engine-robot. 身份授予 GKE 服务代理权限。如需了解详情，请参阅配置 IAM 权限。

Rapid Cache 位置不匹配

无法创建 Rapid Cache 缓存，因为所请求的可用区与存储桶的位置不兼容。

症状

PV 显示 AnywhereCacheSyncWarning 事件，并包含以下消息：Invalid zone. Rapid Cache isn't available in the requested zone.

原因

Rapid Cache 缓存必须在存储桶所在区域位置内的可用区中创建。如果您的 GKE 集群和 Cloud Storage 存储桶位于不同区域，通常会发生此错误。

解决方法

将 Cloud Storage 存储桶迁移到与 GKE 集群位置匹配的区域，然后重新部署 PV。

存储分区扫描超时

Cloud Storage 存储桶的分析时间超过了配置的超时时间，导致优化结果不完整。

症状

PV 显示 ScanOperationTimedOut 事件。PV 附带了对象数量和总大小的部分结果。

原因

相应存储桶包含的对象数量异常多（通常为数百万），无法在默认的两分钟超时时间内完全列出。

解决方法

在 PV 的 spec.csi.volumeAttributes 部分中，为 bucketScanTimeout 字段设置一个较大的值，例如 10m。
如果存储桶大小是静态的，请手动提供对象数量和大小，以绕过扫描。

受内存预算限制的元数据缓存

驱动程序将元数据缓存大小限制在节点可用资源范围内，这可能会降低性能。

症状

日志包含一条消息，指出所需的元数据统计信息缓存大小已限制为可用的 Cloud Storage FUSE 内存预算。

原因

存储桶中对象的元数据缓存超过了分配给 Cloud Storage FUSE 边车的内存或节点的可用内存。

解决方法

使用 only-dir 装载选项将卷范围限定为包含较少对象的较小子目录。
增加 Cloud Storage FUSE Sidecar 容器的内存上限。
- 如果边车限制已足够，请使用具有更多可分配内存的节点类型。

由于资源限制，文件缓存已停用

GKE 停用了本地文件缓存，因为它找不到具有足够空间的合适存储介质。

症状

日志显示警告：No suitable file cache medium found or requirement exceeded limits for all options。

原因

计算出的文件缓存大小超出了可用节点 RAM 和可用本地 SSD 存储空间。

解决方法

使用 only-dir 装载选项将卷范围限定为包含较少对象的较小子目录。
增加 Cloud Storage FUSE 边车的资源限制。
使用具有更多内存的节点类型，或在节点池中启用本地 SSD。

使用 PersistentVolume 事件监控状态

GKE 会将关键配置事件和错误记录到 PV。如需检查这些事件，请运行以下命令：

kubectl describe pv PV_NAME

成功扫描存储桶后，您会看到 ScanOperationSucceeded 事件。如果您使用 gcsfusecsi-serving 配置文件，则在缓存层正常运行后，您会看到 AnywhereCacheSyncSucceeded 事件。

使用 CSI 驱动程序日志监控状态

Cloud Storage FUSE CSI 驱动程序会记录详细的配置决策和性能洞见。如需在 Cloud Logging 中查看这些日志，请使用以下查询：

resource.type="k8s_container"
resource.labels.pod_name=~"gcsfusecsi-node-.*"

查看建议分析洞见

如需了解自动调优逻辑的具体输入信号和做出的决策，请在 CSI 驱动程序日志中搜索 GCSFuseCSIRecommendation 字符串。生成的 JSON 载荷会提供详细的指标，包括以下内容：

inputSignals：存储桶对象数量、数据总大小和可用节点资源（RAM 和临时存储空间）。
decision：最终计算出的缓存大小和所选的存储介质（ram 或 lssd）。

{
  "insertId": "INSERT_ID",
  "jsonPayload": {
    "decision": {
      "fileCacheBytes": 300000000,
      "fileCacheMedium": "lssd",
      "metadataStatCacheBytes": 4500,
    },
    "target": {
      "nodeName": "NODE_NAME",
      "pvName": "PV_NAME",
      "podName": "POD_NAME"
    },
    "message": "GCSFuseCSIRecommendation: Recommended cache configs for PV PV_NAME and Pod POD_NAME: FileCache: 287MiB (lssd) | MetadataStatCache: 1MiB | Expand for full details",
    "inputSignals": {
      "requiredFileCacheBytes": 300000000,
      "fuseBudgetMemoryBytes": 187904819,
      "sidecarLimitMemoryBytes": 268435456,
      "nodeType": "gpu",
      "bucketTotalObjects": 3,
      "nodeAllocatableMemoryBytes": 191291998208,
      "bucketTotalDataSizeBytes": 300000000,
      "bucketLocationType": "multi-region",
      "bucketHNSEnabled": true,
      "sidecarLimitEphemeralStorageBytes": 0,
      "requiredMetadataStatCacheBytes": 4500,
      "nodeAllocatableEphemeralStorageBytes": 1317908854882,
      "nodeHasEphemeralStorageLSSD": true,
      "fuseBudgetEphemeralStorageBytes": 1120222526649
    }
  },
  ...
}

清理

为避免因本指南中创建的资源导致您的 Google Cloud 账号产生费用，请执行以下步骤：

删除 Deployment：
```
kubectl delete deployment my-deployment -n NAMESPACE
```
将 NAMESPACE 替换为您在其中创建了 Deployment 的 Kubernetes 命名空间。
删除 PersistentVolumeClaim：
```
kubectl delete pvc my-pvc -n NAMESPACE
```
将 NAMESPACE 替换为您创建 PVC 的 Kubernetes 命名空间。
删除 PersistentVolume：
```
kubectl delete pv my-pv
```
如果您使用了 gcsfusecsi-serving 配置文件或手动启用了快速缓存，请按照停用缓存中的说明操作，以免产生缓存实例费用。

后续步骤

详细了解 Cloud Storage FUSE CSI 驱动程序。
了解如何手动优化 Cloud Storage FUSE CSI 驱动程序的性能。

使用 Cloud Storage FUSE 分析结果自动进行性能调优 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

使用 Cloud Storage FUSE 配置文件的优势

限制

要求

费用

存储分区扫描费用

Rapid Cache 费用

准备工作

选择性能配置

配置 IAM 权限

方案 A：自定义角色（推荐）

选项 B：训练和检查点配置文件的标准角色

部署具有 Cloud Storage FUSE 配置的工作负载

验证自动化优化

检查存储桶扫描和缓存的状态

检查 Pod 状态

StorageClass 配置参考文档

培训

检查点

服务

可选：微调配置文件

替换装载选项和参数

使用注释绕过存储桶扫描

问题排查

配置参数无效 (InvalidArgument)

扫描 Cloud Storage 存储桶时权限遭拒

Rapid Cache 位置不匹配

存储分区扫描超时

受内存预算限制的元数据缓存

由于资源限制，文件缓存已停用

使用 PersistentVolume 事件监控状态

使用 CSI 驱动程序日志监控状态

查看建议分析洞见

清理

后续步骤

使用 Cloud Storage FUSE 分析结果自动进行性能调优

配置参数无效 (`InvalidArgument`)