将 Cloud Storage 存储桶装载为 CSI 临时卷

本指南介绍了如何使用由 Cloud Storage 存储桶提供支持的 CSI 临时卷，来自动管理 Google Kubernetes Engine (GKE) 上 Kubernetes Pod 或作业的存储资源。CSI 临时卷与 Pod 或作业生命周期相关联，您无需手动处理 PersistentVolume 和 PersistentVolumeClaim 对象。

本指南适用于希望简化 GKE 应用存储管理的平台管理员和运维人员。

在阅读本页面之前，请确保您熟悉 CSI 临时卷、Kubernetes Pod 和作业，以及 Cloud Storage 存储桶。

如果您已经熟悉 PersistentVolume，并且希望与依赖此资源类型的现有部署保持一致，请参阅将 Cloud Storage 存储桶装载为永久性卷。

准备工作

请确保您已满足以下前提条件：

Cloud Storage 存储桶的 CSI 临时存储的工作原理

CSI 临时卷简化了 GKE 上的应用的存储管理。您可以直接在 Pod 或作业规范中定义 CSI 临时卷。使用 CSI 临时卷无需单独的 PersistentVolume 和 PersistentVolumeClaim 对象。

使用 CSI 临时卷涉及以下操作：

  1. 存储空间定义：在 Pod 或作业的 YAML 文件中指定存储空间，包括要使用的 CSI 驱动程序和任何必需的参数。对于 Cloud Storage FUSE CSI 驱动程序，您需要指定存储桶名称和其他相关详细信息。

    （可选）您可以使用文件缓存功能来微调 CSI 驱动程序的性能。文件缓存可通过在速度更快的磁盘上缓存频繁访问的 Cloud Storage 文件来提高 GKE 应用性能。

    此外，您可以使用并行下载功能加快从 Cloud Storage 读取大型文件的速度，以实现多线程下载。您可以使用此功能来缩短模型加载时间，尤其是对于大小超过 1 GB 的读取操作。

  2. 驱动程序调用：当您创建 Pod 或作业时，GKE 会检测到临时卷请求并调用 Cloud Storage FUSE CSI 驱动程序。

  3. 卷装载和挂接：CSI 驱动程序会装载 CSI 临时卷（指向底层 Cloud Storage 存储桶），并使其可供 Pod 或作业使用，以供您的应用访问。如需微调在文件系统中装载存储桶的方式，您可以使用装载选项。您还可以使用卷属性来配置 Cloud Storage FUSE CSI 驱动程序的特定行为。

  4. 生命周期管理：临时卷在 Pod 或作业的整个生命周期内都存在。当 Pod 删除或作业完成时，CSI 驱动程序会自动处理清理工作并卸载卷。

挂接 CSI 临时卷

按照以下说明操作，具体取决于您要将 CSI 临时卷挂接到 Pod 还是作业，

Pod

如需在 Pod 中挂接 CSI 临时卷，请按照以下步骤操作：

  1. 使用以下规范创建 Pod YAML 清单：

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral 
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true" 
spec:
  terminationGracePeriodSeconds: 60
  containers:
  - image: busybox
    name: busybox
    command: ["sleep"]
    args: ["infinity"] 
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
      readOnly: true
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      readOnly: true
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"

    替换以下值：

    • NAMESPACE：您要在其中部署 Pod 的 Kubernetes 命名空间。
    • KSA_NAME：您在配置对 Cloud Storage 存储桶的访问权限时指定的 Kubernetes ServiceAccount 的名称。
    • BUCKET_NAME：您在配置对 Cloud Storage 存储桶的访问权限时指定的 Cloud Storage 存储桶名称。您可以指定下划线 (_) 以装载 Kubernetes ServiceAccount 可以访问的所有存储桶。如需了解详情，请参阅 Cloud Storage FUSE 文档中的动态装载。

    示例清单显示了这些必需设置：

    • metadata.annotations：注解 gke-gcsfuse/volumes: "true" 是必需的。如需了解可选注解，请参阅配置边车容器。
    • spec.volumes[n].csi.driver：使用 gcsfuse.csi.storage.gke.io 作为 CSI 驱动程序名称。

    您可以选择性地调整以下变量：

    • spec.terminationGracePeriodSeconds：默认情况下，该值设置为 30。如果您需要将大型文件写入 Cloud Storage 存储桶，请提高此值，以确保 Cloud Storage FUSE 有足够的时间在应用退出后清空数据。如需了解详情，请参阅 Kubernetes 最佳实践：安全终止。
    • spec.volumes[n].csi.volumeAttributes.mountOptions：将装载选项传递给 Cloud Storage FUSE。在一个字符串中指定标志，以英文逗号分隔，不带空格。
    • spec.volumes[n].csi.volumeAttributes：将其他卷属性传递给 Cloud Storage FUSE。
    • spec.volumes[n].csi.readOnly：如果所有卷装载都是只读的，请指定 true。
    • spec.containers[n].volumeMounts[m].readOnly：如果仅有特定的卷装载是只读的，请指定 true。

  2. 运行以下命令以将该清单应用于集群：

    kubectl apply -f FILE_PATH

    将 FILE_PATH 替换为 YAML 文件的路径。

Pod（文件缓存）

如需在 Pod 中挂接具有文件缓存功能的 CSI 临时卷，请按照以下步骤操作：

  1. 按照创建具有本地 SSD 支持的临时存储空间的集群或节点池中的步骤，创建具有本地 SSD 支持的临时存储空间的集群或节点池。

  2. 使用以下规范创建 Pod YAML 清单：

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-file-cache-example 
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi" 
spec:
  nodeSelector:
    cloud.google.com/gke-ephemeral-storage-local-ssd: "true"
  restartPolicy: Never
  initContainers:
  - name: data-loader
    image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
    resources:
      limits:
        cpu: 500m
        memory: 1Gi
      requests:
        cpu: 500m
        memory: 1Gi
    command:
      - "/bin/sh"
      - "-c"
      - |
        mkdir -p /test_files
        for i in $(seq 1 1000); do dd if=/dev/zero of=/test_files/file_$i.txt bs=1024 count=64; done
        gcloud storage cp /test_files gs://BUCKET_NAME --recursive
  containers:
  - name: data-validator
    image: busybox
    resources:
      limits:
        cpu: 500m
        memory: 512Mi
      requests:
        cpu: 500m
        memory: 512Mi
    command:
      - "/bin/sh"
      - "-c"
      - |
        echo "first read with cache miss"
        time cat /data/test_files/file_* > /dev/null

        echo "second read from local cache"
        time cat /data/test_files/file_* > /dev/null 
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs,file-cache:max-size-mb:-1"

    替换以下值：

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

    • BUCKET_NAME：您在配置对 Cloud Storage 存储桶的访问权限时指定的 Cloud Storage 存储桶名称。您可以指定下划线 (_) 以装载 Kubernetes ServiceAccount 可以访问的所有存储桶。如需了解详情，请参阅 Cloud Storage FUSE 文档中的动态装载。

      在示例清单中，init 容器数据加载器会生成 1,000 个大小为 64 KiB 的文件，并将这些文件上传到 Cloud Storage 存储桶。主容器 data-validator 会从存储桶读取所有文件两次，并记录时长。

  3. 运行以下命令以将该清单应用于集群：

    kubectl apply -f FILE_PATH

    将 FILE_PATH 替换为 YAML 文件的路径。

  4. 如需查看日志输出，请运行以下命令：

    kubectl logs -n NAMESPACE gcs-fuse-csi-file-cache-example -c data-validator

    将 NAMESPACE 替换为工作负载的命名空间。

    输出应类似如下所示：

    first read with cache miss
real    0m 54.68s
...
second read from local cache
real    0m 0.38s
...

    输出结果显示，使用本地缓存的第二次读取比缓存未命中的第一次读取快得多。

Pod（并行下载）

如需在 Pod 中挂接具有并行下载功能的 CSI 临时卷，请按照以下步骤操作：

  1. 使用以下规范创建 Pod YAML 清单：

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral 
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi" 
spec:
  containers:
  ...
  volumes:
  - name: gcs-fuse-csi-ephemeral 
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs,file-cache:enable-parallel-downloads:true,file-cache:max-size-mb:-1"
        fileCacheCapacity: "-1"

    替换以下值：

    • NAMESPACE：您要在其中部署 Pod 的 Kubernetes 命名空间。
    • BUCKET_NAME：您在配置对 Cloud Storage 存储桶的访问权限时指定的 Cloud Storage 存储桶名称。您可以指定下划线 (_) 以装载 Kubernetes ServiceAccount 可以访问的所有存储桶。如需了解详情，请参阅 Cloud Storage FUSE 文档中的动态装载。

  2. 运行以下命令以将该清单应用于集群：

    kubectl apply -f FILE_PATH

    将 FILE_PATH 替换为 YAML 文件的路径。

作业

如需在作业中挂接 CSI 临时卷，请按照以下步骤操作：

  1. 使用以下规范创建作业 YAML 清单：

    apiVersion: batch/v1
kind: Job
metadata:
  name: gcs-fuse-csi-job-example 
  namespace: NAMESPACE 
spec:
  template:
    metadata: 
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME 
      containers:
      - name: writer
        image: busybox
        command:
          - "/bin/sh"
          - "-c"
          - touch /data/test && echo $(date) >> /data/test && sleep 10
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
      - name: reader
        image: busybox
        command:
          - "/bin/sh"
          - "-c"
          - sleep 10 && cat /data/test 
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
          readOnly: true
      volumes:
      - name: gcs-fuse-csi-ephemeral
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: BUCKET_NAME
      restartPolicy: Never 
  backoffLimit: 1

    替换以下值：

    • NAMESPACE：您要在其中部署 Pod 的 Kubernetes 命名空间。
    • KSA_NAME：您在配置对 Cloud Storage 存储桶的访问权限时指定的 Kubernetes ServiceAccount 的名称。
    • BUCKET_NAME：您在配置对 Cloud Storage 存储桶的访问权限时指定的 Cloud Storage 存储桶名称。您可以指定下划线 (_) 以装载 Kubernetes ServiceAccount 可以访问的所有存储桶。如需了解详情，请参阅 Cloud Storage FUSE 文档中的动态装载。

    示例清单显示了这些必需设置：

    • metadata.annotations：注解 gke-gcsfuse/volumes: "true" 是必需的。如需了解可选注解，请参阅配置边车容器。
    • spec.volumes[n].csi.drive：使用 gcsfuse.csi.storage.gke.io 作为 CSI 驱动程序名称。

    您可以选择性地调整以下变量：

    • spec.volumes[n].csi.volumeAttributes.mountOptions：将装载选项传递给 Cloud Storage FUSE。在一个字符串中指定标志，以英文逗号分隔，不带空格。
    • spec.volumes[n].csi.volumeAttributes：将其他卷属性传递给 Cloud Storage FUSE。
    • spec.volumes[n].csi.readOnly：如果所有卷装载都是只读的，请指定 true。
    • spec.containers[n].volumeMounts[m].readOnly：如果仅有特定的卷装载是只读的，请指定 true。

  2. 运行以下命令以将该清单应用于集群：

    kubectl apply -f FILE_PATH

    将 FILE_PATH 替换为 YAML 文件的路径。

问题排查

如果您需要排查 Cloud Storage FUSE 问题，可以将 log-severity 标志设置为 TRACE。您可以在部署 YAML 内的驱动程序容器规范的 args 部分中设置该标志。这会使 gcsfuseLoggingSeverity 卷属性自动设置为 trace。

如需查看更多问题排查提示，请参阅 GitHub 项目文档中的问题排查指南。

后续步骤