使用 Compute Engine 永久性磁盘 CSI 驱动程序

Autopilot Standard

Google Kubernetes Engine (GKE) 为您在集群中自动部署和管理 Compute Engine 永久性磁盘容器存储接口 (CSI) 驱动程序提供了一种简单的方法。Compute Engine 永久性磁盘 CSI 驱动程序在 Autopilot 集群中始终处于启用状态，无法停用或修改。在 Standard 集群中，您必须启用 Compute Engine 永久性磁盘 CSI 驱动程序。

Compute Engine 永久性磁盘 CSI 驱动程序版本与 GKE 版本号相关联。Compute Engine 永久性磁盘 CSI 驱动程序版本通常是发布 GKE 版本时可用的最新驱动程序。当集群升级到最新的 GKE 补丁程序时，驱动程序会自动更新。

优势

使用 Compute Engine 永久性磁盘 CSI 驱动程序具有以下优势：

它可以自动部署和管理永久性磁盘驱动程序，而不必手动进行设置。
您可以使用客户管理的加密密钥 (CMEK)。这些密钥用于对加密您的数据的数据加密密钥进行加密。如需详细了解 GKE 上的 CMEK，请参阅使用 CMEK。
您可以将卷快照与 Compute Engine 永久性磁盘 CSI 驱动程序结合使用。通过卷快照，您可以在特定时间点创建卷的副本。您可以使用此副本将卷恢复到之前的状态或预配新卷。
您可以将卷克隆与运行 GKE 1.22 及更高版本的集群中的 Compute Engine 永久性磁盘 CSI 驱动程序结合使用。通过卷克隆，您可以在特定时间点创建卷的副本，并预配来源卷的所有数据。
Bug 修复和功能更新独立于次要的 Kubernetes 版本而发布。此发布时间表通常会加快发布节奏。

须知事项

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

启用 Google Kubernetes Engine API。

启用 Google Kubernetes Engine API

如果您要使用 Google Cloud CLI 执行此任务，请安装并初始化 gcloud CLI。如果您之前安装了 gcloud CLI，请运行 gcloud components update 以获取最新版本。
注意：对于现有 gcloud CLI 安装，请务必设置 compute/region 和 compute/zone 属性。通过设置默认位置，您可以避免 gcloud CLI 中出现以下错误：One of [--zone, --region] must be supplied: Please specify location。

要求

如需使用 Compute Engine 永久性磁盘 CSI 驱动程序，您的集群必须使用以下版本：

Linux 集群：GKE 1.14 或更高版本。
Windows 集群：GKE 1.18 或更高版本。

在 1.22 及更高版本中，已启用 CSI 迁移。使用 gce-pd 提供商的现有卷将进行迁移，以改为通过 CSI 驱动程序进行通信。无需对任何 StorageClass 进行更改。gce-pd 提供商依然不支持 CMEK 或卷快照等功能。必须使用 StorageClass 中的 pd.csi.storage.gke.io 提供商来启用这些功能。

如需将 Compute Engine 永久性磁盘 CSI 驱动程序与适用于 GKE 的工作负载身份联合搭配使用，您的 Standard 集群必须使用以下版本：

Linux 集群：GKE 1.16 或更高版本。
Windows 集群：GKE 1.20.8-gke.900 或更高版本。

在新集群上启用 Compute Engine 永久性磁盘 CSI 驱动程序

如需使用未自动启用 Compute Engine 永久性磁盘 CSI 驱动程序的版本创建集群，您可以使用 Google Cloud CLI 或 Google Cloud 控制台。

如需在创建集群时启用该驱动程序，请完成以下步骤：

gcloud

gcloud container clusters create CLUSTER-NAME \
    --addons=GcePersistentDiskCsiDriver \
    --cluster-version=VERSION

替换以下内容：

CLUSTER-NAME：您的集群的名称。
VERSION：GKE 版本号。您必须选择 1.14 或更高版本才能使用此功能。

如需查看完整的标志列表，请参阅 gcloud container clusters create 文档。

控制台

转到 Google Cloud 控制台中的 Google Kubernetes Engine 页面。

转到 Google Kubernetes Engine
点击创建。
在标准部分中，点击配置。
根据需要配置集群。
在导航窗格的集群下，点击功能。
选中启用 Compute Engine 永久性磁盘 CSI 驱动程序复选框。
点击创建。

启用 Compute Engine 永久性磁盘 CSI 驱动程序后，您可以使用驱动程序和预配工具名称 pd.csi.storage.gke.io 在 Kubernetes 卷中使用该驱动程序。

在现有集群上启用 Compute Engine 永久性磁盘 CSI 驱动程序

如需在现有标准集群中启用 Compute Engine 永久性磁盘 CSI 驱动程序，请使用 Google Cloud CLI 或 Google Cloud 控制台。

如需在现有集群上启用该驱动程序，请完成以下步骤：

gcloud

gcloud container clusters update CLUSTER-NAME \
   --update-addons=GcePersistentDiskCsiDriver=ENABLED

将 CLUSTER-NAME 替换为现有集群的名称。

控制台

转到 Google Cloud 控制台中的 Google Kubernetes Engine 页面。

前往 Google Kubernetes Engine
在集群列表中，点击您要修改的集群的名称。
在功能下，点击 Compute Engine 永久性磁盘 CSI 驱动程序字段旁边的 修改 Compute Engine CSI 驱动程序。
选中启用 Compute Engine 永久性磁盘 CSI 驱动程序复选框。
点击保存更改。

停用 Compute Engine 永久性磁盘 CSI 驱动程序

您可以使用 Google Cloud CLI 或 Google Cloud 控制台停用适用于标准集群的 Compute Engine 永久性磁盘 CSI 驱动程序。

如果您停用该驱动程序，则当前使用该驱动程序所拥有的 PersistentVolume 的任何 Pod 都将无法终止。尝试使用这些 PersistentVolume 的所有新 Pod 也将无法启动。

如需在现有标准集群上停用该驱动程序，请完成以下步骤：

gcloud

gcloud container clusters update CLUSTER-NAME \
    --update-addons=GcePersistentDiskCsiDriver=DISABLED

将 CLUSTER-NAME 替换为现有集群的名称。

控制台

转到 Google Cloud 控制台中的 Google Kubernetes Engine 页面。

前往 Google Kubernetes Engine
在集群列表中，点击您要修改的集群的名称。
在功能下，点击 Compute Engine 永久性磁盘 CSI 驱动程序字段旁边的 修改 Compute Engine CSI 驱动程序。
取消选中启用 Compute Engine Persistent Disk CSI 驱动程序复选框。
点击保存更改。

使用适用于 Linux 集群的 Compute Engine 永久性磁盘 CSI 驱动程序

以下几个部分介绍了在 GKE 中使用 CSI 驱动程序支持的 Kubernetes 卷的典型过程。这些部分针对使用 Linux 的集群。

创建一个 StorageClass

启用 Compute Engine 永久性磁盘 CSI 驱动程序后，GKE 会自动安装以下 StorageClasses：

standard-rwo（使用平衡永久性磁盘）
premium-rwo（使用 SSD 永久性磁盘）

对于 Autopilot 集群，默认 StorageClass 是 standard-rwo，它使用 Compute Engine 永久性磁盘 CSI 驱动程序。对于标准集群，默认 StorageClass 使用 Kubernetes 树内 gcePersistentDisk 卷插件。

您可以通过运行以下命令找到已安装的 StorageClass 的名称：

kubectl get sc

您还可以通过在预配工具字段中添加 pd.csi.storage.gke.io 来安装其他使用 Compute Engine 永久性磁盘 CSI 驱动程序的 StorageClass。

例如，您可以使用以下名为 pd-example-class.yaml 的文件创建一个 StorageClass：

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: pd-example
provisioner: pd.csi.storage.gke.io
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
parameters:
  type: pd-balanced

您可以在 type 参数中指定以下永久性磁盘类型：

pd-balanced
pd-ssd
pd-standard
pd-extreme（在 GKE 1.26 版及更高版本中受支持）

如果使用 pd-standard 或 pd-extreme，请参阅不支持的机器类型，了解其他使用限制。

使用 pd-extreme 选项时，您还必须将 provisioned-iops-on-create 字段添加到清单中。此字段必须设置为您在创建永久性磁盘时指定的预配 IOPS 值。

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: pd-extreme-example
provisioner: pd.csi.storage.gke.io
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
parameters:
  type: pd-extreme
  provisioned-iops-on-create: '10000'

创建 pd-example-class.yaml 文件后，请运行以下命令：

kubectl create -f pd-example-class.yaml

创建一个 PersistentVolumeClaim

您可以创建一个引用 Compute Engine 永久性磁盘 CSI 驱动程序的 StorageClass 的 PersistentVolumeClaim。

以下名为 pvc-example.yaml 的文件使用预安装的存储类别 standard-rwo：

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: podpvc
spec:
  accessModes:
  - ReadWriteOnce
  storageClassName: standard-rwo
  resources:
    requests:
      storage: 6Gi

创建 PersistentVolumeClaim 清单后，请运行以下命令：

kubectl create -f pvc-example.yaml

在预安装的 StorageClass (standard-rwo) 中，将 volumeBindingMode 设置为 WaitForFirstConsumer。如果将 volumeBindingMode 设置为 WaitForFirstConsumer，则在调度引用 PersistentVolumeClaim 的 Pod 之前，系统不会预配 PersistentVolume。如果将 StorageClass 中的 volumeBindingMode 设置为 Immediate（或者将其省略），则在创建 PersistentVolumeClaim 后，系统会预配基于永久性磁盘的 PersistentVolume。

创建使用该卷的 Pod

将 Pod 与 PersistentVolume 搭配使用时，我们建议您使用工作负载控制器（例如 Deployment 或 StatefulSet）。虽然您通常不会使用一个独立的 Pod，但以下示例为简单起见使用了一个 Pod。

以下示例将使用您在上一部分中创建的卷：

apiVersion: v1
kind: Pod
metadata:
  name: web-server
spec:
  containers:
   - name: web-server
     image: nginx
     volumeMounts:
       - mountPath: /var/lib/www/html
         name: mypvc
  volumes:
   - name: mypvc
     persistentVolumeClaim:
       claimName: podpvc
       readOnly: false

使用适用于 Windows 集群的 Compute Engine 永久性磁盘 CSI 驱动程序

以下几个部分介绍了在 GKE 中使用 CSI 驱动程序支持的 Kubernetes 卷的典型过程。这些部分针对使用 Windows 的集群。

确保：

集群版本为 1.19.7-gke.2000、1.20.2-gke.2000 或更高版本。
节点版本为 1.18.12-gke.1203、1.19.6-gke.800 或更高版本。

创建一个 StorageClass

创建适用于 Windows 的 StorageClass 的过程与 Linux 非常相似。请注意，默认安装的 StorageClass 并不适用于 Windows，因为文件系统类型不同。适用于 Windows 的 Compute Engine 永久性磁盘 CSI 驱动程序需要以 NTFS 作为文件系统类型。

例如，您可以使用以下名为 pd- windows-class.yaml 的文件创建一个 StorageClass。请务必将 csi.storage.k8s.io/fstype: NTFS 添加到参数列表中：

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: pd-sc-windows
provisioner: pd.csi.storage.gke.io
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
parameters:
  type: pd-balanced
  csi.storage.k8s.io/fstype: NTFS

创建一个 PersistentVolumeClaim

创建适用于 Windows 的 StorageClass 后，您便可以创建引用该 StorageClass 的 PersistentVolumeClaim：

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: podpvc-windows
spec:
  accessModes:
  - ReadWriteOnce
  storageClassName: pd-sc-windows
  resources:
    requests:
      storage: 6Gi

创建使用该卷的 Pod

以下示例将使用您在上一任务中创建的卷：

apiVersion: v1
kind: Pod
metadata:
  name: web-server
spec:
  nodeSelector:
    kubernetes.io/os: windows
  containers:
    - name: iis-server
      image: mcr.microsoft.com/windows/servercore/iis
      ports:
      - containerPort: 80
      volumeMounts:
      - mountPath: /var/lib/www/html
        name: mypvc
  volumes:
    - name: mypvc
      persistentVolumeClaim:
        claimName: podpvc-windows
        readOnly: false

使用具有非默认文件系统类型的 Compute Engine 永久性磁盘 CSI 驱动程序

GKE 中 Compute Engine 永久性磁盘的默认文件系统类型为 ext4。只要节点映像支持该类型，您也可以使用 xfs 存储类型。如需查看节点映像支持的驱动程序列表，请参阅存储驱动程序支持。

以下示例展示了如何将 xfs（而非 ext4）用作 Compute Engine 永久性磁盘 CSI 驱动程序的默认文件系统类型。

创建一个 StorageClass

将以下清单保存为名为 pd-xfs-class.yaml 的 YAML 文件：

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: xfs-class
provisioner: pd.csi.storage.gke.io
parameters:
  type: pd-balanced
  csi.storage.k8s.io/fstype: xfs
volumeBindingMode: WaitForFirstConsumer

应用清单：
```
kubectl apply -f pd-xfs-class.yaml
```

创建一个 PersistentVolumeClaim

将以下清单保存为 pd-xfs-pvc.yaml：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: xfs-pvc
spec:
  storageClassName: xfs-class
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

应用清单：
```
kubectl apply -f pd-xfs-pvc.yaml
```

创建使用该卷的 Pod

将以下清单保存为 pd-xfs-pod.yaml：

apiVersion: v1
kind: Pod
metadata:
  name: pd-xfs-pod
spec:
  containers:
  - name: cloud-sdk
    image: google/cloud-sdk:slim
    args: ["sleep","3600"]
    volumeMounts:
    - mountPath: /xfs
      name: xfs-volume
  volumes:
  - name: xfs-volume
    persistentVolumeClaim:
      claimName: xfs-pvc

应用清单：
```
kubectl apply -f pd-xfs-pod.yaml
```

验证卷是否已正确装载

在 Pod 中打开 shell 会话：

kubectl exec -it pd-xfs-pod -- /bin/bash

查找 xfs 分区：

df -aTh --type=xfs

输出应类似如下所示：

Filesystem     Type  Size  Used Avail Use% Mounted on
/dev/sdb       xfs    30G   63M   30G   1% /xfs

查看 Compute Engine 永久性磁盘 CSI 驱动程序的日志

您可以使用 Cloud Logging 查看与 Compute Engine 永久性磁盘 CSI 驱动程序相关的事件。日志可帮助您排查问题。

如需详细了解 Cloud Logging，请参阅查看 GKE 日志。

如需查看 Compute Engine 永久性磁盘 CSI 驱动程序的日志，请完成以下步骤：

转到 Google Cloud 控制台中的 Cloud Logging 页面。

转到 Cloud Logging

请运行以下查询：

 resource.type="k8s_container"
 resource.labels.project_id="PROJECT_ID"
 resource.labels.location="LOCATION"
 resource.labels.cluster_name="CLUSTER_NAME"
 resource.labels.namespace_name="kube-system"
 resource.labels.container_name="gce-pd-driver"

替换以下内容：

PROJECT_ID：您的项目的名称。
LOCATION：集群的 Compute Engine 区域或可用区。
CLUSTER_NAME：您的集群的名称。

已知问题

不支持的机器类型

如果您使用的是 C3 系列机器家族，则不支持 pd-standard 永久性磁盘类型。

如果您尝试在机器上运行 Pod，并且该 Pod 使用不受支持的永久性磁盘类型，您将看到 Pod 上发出的如下警告消息：

AttachVolume.Attach failed for volume "pvc-d7397693-5097-4a70-9df0-b10204611053" : rpc error: code = Internal desc = unknown Attach error: failed when waiting for zonal op: operation operation-1681408439910-5f93b68c8803d-6606e4ed-b96be2e7 failed (UNSUPPORTED_OPERATION): [pd-standard] features are not compatible for creating instance.

如果您的集群包含多个具有不同机器系列的节点池，则您可以使用节点污点和节点亲和性来限制可以调度工作负载的位置。例如，您可以使用此方法来限制使用 pd-standard 的工作负载在不受支持的机器家族上运行。

如果您使用的是 pd-extreme 永久性磁盘类型，则需要确保将磁盘挂接到具有适当机器配置的虚拟机实例。如需了解详情，请参阅机器配置支持。

使用 Compute Engine 永久性磁盘 CSI 驱动程序

优势

须知事项

要求

在新集群上启用 Compute Engine 永久性磁盘 CSI 驱动程序

gcloud

控制台

在现有集群上启用 Compute Engine 永久性磁盘 CSI 驱动程序

gcloud

控制台

停用 Compute Engine 永久性磁盘 CSI 驱动程序

gcloud

控制台

使用适用于 Linux 集群的 Compute Engine 永久性磁盘 CSI 驱动程序

创建一个 StorageClass

创建一个 PersistentVolumeClaim

创建使用该卷的 Pod

使用适用于 Windows 集群的 Compute Engine 永久性磁盘 CSI 驱动程序

创建一个 StorageClass

创建一个 PersistentVolumeClaim

创建使用该卷的 Pod

使用具有非默认文件系统类型的 Compute Engine 永久性磁盘 CSI 驱动程序

创建一个 StorageClass

创建一个 PersistentVolumeClaim

创建使用该卷的 Pod

验证卷是否已正确装载

查看 Compute Engine 永久性磁盘 CSI 驱动程序的日志

已知问题

不支持的机器类型

后续步骤