将 Cloud Storage 存储分区作为永久卷装载

本指南介绍了如何使用由 Cloud Storage 存储分区支持的 Kubernetes 永久性卷在 Google Kubernetes Engine (GKE) 上管理 Kubernetes Pod 的存储资源。如果您已经熟悉 PersistentVolume，并且希望与依赖于此资源类型的现有部署保持一致，请考虑使用此存储选项。

本指南适用于希望简化 GKE 应用存储空间管理的平台管理员和操作员用户。

在阅读本页内容之前，请确保您熟悉 Kubernetes 持久卷、Kubernetes Pod 和 Cloud Storage 存储分区。

如果您希望使用无需任何 Kubernetes 永久性卷使用经验的简化型基于 Pod 的界面，请参阅将 Cloud Storage 存储分区作为 CSI 临时卷进行挂载。

准备工作

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

Cloud Storage 存储分区的持久卷的工作原理

通过静态预配，您可以创建一个或多个包含底层存储系统细节的 PersistentVolume 对象。然后，集群中的 Pod 即可通过 PersistentVolumeClaims 使用存储空间。

使用由 Cloud Storage 存储桶支持的持久性卷涉及以下操作：

  1. 存储定义：您在 GKE 集群中定义 PersistentVolume，包括要使用的 CSI 驱动程序和所有必需的参数。对于 Cloud Storage FUSE CSI 驱动程序，您需要指定存储桶名称和其他相关详细信息。

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

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

  2. 驱动程序调用：当 PersistentVolumeClaim 请求与 PersistentVolume 规范匹配的存储空间时，GKE 会调用 Cloud Storage FUSE CSI 驱动程序。

  3. 存储桶挂载：CSI 驱动程序会将存储桶挂载到调度请求 pod 的节点。这样一来，Pod 就可以通过 Pod 本地文件系统中的目录访问存储桶中的内容。如需微调存储分区在文件系统中的装载方式，您可以使用装载选项。您还可以使用卷属性配置 Cloud Storage FUSE CSI 驱动程序的特定行为。

  4. 重新附加：如果 Pod 重启或被重新调度到其他节点，CSI 驱动程序会将同一存储桶重新挂载到新节点，从而确保数据可访问。

创建一个 PersistentVolume

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

    Pod

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: gcs-fuse-csi-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  storageClassName: example-storage-class  
  mountOptions:
    - implicit-dirs
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
  claimRef:
    name: gcs-fuse-csi-static-pvc
    namespace: NAMESPACE

    替换以下值：

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

    示例清单显示了以下必需设置：

    • spec.csi.driver：使用 gcsfuse.csi.storage.gke.io 作为 CSI 驱动程序名称。

    （可选）您可以调整以下变量：

    • spec.mountOptions：将挂载选项传递给 Cloud Storage FUSE。在一个字符串中指定标志，以英文逗号分隔，不带空格。
    • spec.csi.volumeAttributes：将其他卷属性传递给 Cloud Storage FUSE。

    Pod（文件缓存）

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: gcs-fuse-csi-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  storageClassName: example-storage-class 
  mountOptions:
    - implicit-dirs
    - file-cache:max-size-mb:-1
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
  claimRef:
    name: gcs-fuse-csi-static-pvc
    namespace: NAMESPACE

    替换以下值：

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

    Pod（并行下载）

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: gcs-fuse-csi-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  storageClassName: example-storage-class 
  mountOptions:
    - implicit-dirs
    - file-cache:enable-parallel-downloads:true
    - file-cache:max-size-mb:-1
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
  claimRef:
    name: gcs-fuse-csi-static-pvc
    namespace: NAMESPACE

    替换以下值：

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

  2. 将清单应用于集群：

    kubectl apply -f PV_FILE_PATH

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

创建一个 PersistentVolumeClaim

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

    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: gcs-fuse-csi-static-pvc
  namespace: NAMESPACE
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  storageClassName: example-storage-class

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

    如需将 PersistentVolume 绑定到 PersistentVolumeClaim，请检查以下配置设置：

    • PersistentVolume 和 PersistentVolumeClaim 清单中的 spec.storageClassName 字段应匹配。storageClassName 不需要引用现有 StorageClass 对象。如需将声明绑定到卷，您可以使用任意名称，但名称不能为空。
    • PersistentVolume 和 PersistentVolumeClaim 清单中的 spec.accessModes 字段应匹配。
    • PersistentVolume 清单中的 spec.capacity.storage 字段应与 PersistentVolumeClaim 清单中的 spec.resources.requests.storage 相匹配。由于 Cloud Storage 存储分区没有大小限制，因此您可以放置任意数量的容量，但不能为空。

  2. 将清单应用于集群：

    kubectl apply -f PVC_FILE_PATH

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

在 Pod 中使用卷

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

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-static-pvc  
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi" 
spec:
  containers:
  - image: busybox
    name: busybox
    command: ["sleep"]
    args: ["infinity"]  
    volumeMounts:
    - name: gcs-fuse-csi-static
      mountPath: /data
      readOnly: true
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-static
    persistentVolumeClaim:
      claimName: gcs-fuse-csi-static-pvc
      readOnly: true

    替换以下值：

    示例清单显示了以下必需设置：

    • metadata.annotations：注解 gke-gcsfuse/volumes: "true" 是必需的。如需了解可选注解，请参阅配置 Sidecar 容器。

    （可选）您可以调整以下变量：

    • spec.containers[n].volumeMonts[n].readOnly：如果仅有特定的卷装载是只读的，请指定 true。
    • spec.volumes[n].persistentVolumeClaim.readOnly：如果所有卷装载都是只读的，请指定 true。

  2. 将清单应用于集群：

    kubectl apply -f POD_FILE_PATH

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

问题排查

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

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

后续步骤