将 Cloud Storage 存储桶装载为永久性卷

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

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

在阅读本页面之前，请确保您熟悉 Kubernetes 永久性卷、Kubernetes Pod 和 Cloud Storage 存储桶。

如果您想要使用简化的基于 Pod 的界面，该界面不需要您之前使用过 Kubernetes 永久性卷，请参阅将 Cloud Storage 存储桶装载为 CSI 临时卷。

准备工作

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

Cloud Storage 存储桶的永久性卷的工作原理

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

使用由 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 就可以在其本地文件系统中以目录的形式访问存储桶的内容。如需微调在文件系统中装载存储桶的方式，您可以使用装载选项。您还可以使用卷属性来配置 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" 是必需的。如需了解可选注解，请参阅配置边车容器。

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

    • 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 项目文档中的问题排查指南。

后续步骤