使用 Filestore CSI 驱动程序访问 Filestore 实例

Autopilot Standard

Filestore CSI 驱动程序是将 Filestore 实例与 Google Kubernetes Engine (GKE) 搭配使用的主要方式。Filestore CSI 驱动程序提供全代管式体验，由开源 Google Cloud Filestore CSI 驱动程序提供支持。

Filestore CSI 驱动程序版本与 Kubernetes 次要版本号相关联。Filestore CSI 驱动程序版本通常是发布 Kubernetes 次要版本时可用的最新驱动程序。当集群升级到最新的 GKE 补丁程序时，驱动程序会自动更新。

优势

Filestore CSI 驱动程序具有以下优势：

您可以通过 Kubernetes API (kubectl) 访问全代管式 NFS 存储。
您可以使用 GKE Filestore CSI 驱动程序来动态预配 PersistentVolume。
您可以将卷快照与 GKE Filestore CSI 驱动程序结合使用。CSI 卷快照可用于创建 Filestore 备份。

Filestore 备份会创建文件共享的差分副本（包括所有文件数据和元数据），并将其与实例分开存储。您只能将此副本恢复到新的 Filestore 实例。不支持恢复到现有的 Filestore 实例。您可以使用 CSI 卷快照 API 来触发 Filestore 备份，只需在卷快照类中添加 type:backup 字段即可。
您可以将卷扩展与 GKE Filestore CSI 驱动程序结合使用。通过卷扩展，您可以调整卷的容量。
您可以在 Kubernetes 工作负载中使用预先预配的 Filestore 实例来访问现有的 Filestore 实例。您还可以动态创建或删除 Filestore 实例，并在具有 StorageClass 或 Deployment 的 Kubernetes 工作负载中使用这些实例。
支持 Filestore Multishares for GKE。此功能让您可以创建 Filestore 实例并在任何数量的 GKE 集群中同时为该实例分配多个较小的以 NFS 形式装载的 PersistentVolume。

要求

如需使用 Filestore CSI 驱动程序，您的集群必须使用适用于您的服务层级的适当 GKE 版本号。仅支持以下服务层级：
- 具有 GKE 1.21 版或更高版本的基本 HDD 层级
- 具有 GKE 1.21 版或更高版本的基本 SSD 层级
- 具有 GKE 1.27 版或更高版本的可用区层级（10 TiB 到 100 TiB）
- 具有 GKE 1.25 版或更高版本的 Enterprise 层级
- 如需使用 Filestore Multishares 功能，您的集群必须使用 GKE 1.25 版或更高版本。
只有使用 Linux 的集群支持 Filestore CSI 驱动程序；Windows Server 节点不支持。
Filestore 的最小实例大小至少为 1 TiB。最小实例大小取决于您选择的 Filestore 服务层级。如需了解详情，请参阅服务层级。
Filestore 在 Filestore 实例上使用 NFSv3 文件系统协议，并支持任何与 NFSv3 兼容的客户端。

须知事项

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

启用 Cloud Filestore API 和 Google Kubernetes Engine API。

启用 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。

如果要在共享 VPC 网络中使用 Filestore，请参阅将 Filestore 与共享 VPC 搭配使用中的其他设置说明。

在新集群上启用 Filestore CSI 驱动程序

如需在创建新的 Standard 集群时启用 Filestore CSI 驱动程序，请使用 Google Cloud CLI 或 Google Cloud 控制台执行以下步骤。

gcloud

gcloud container clusters create CLUSTER_NAME \
    --addons=GcpFilestoreCsiDriver \
    --cluster-version=VERSION

替换以下内容：

CLUSTER_NAME：您的集群的名称。
VERSION：GKE 版本号。 您必须选择支持的版本号才能使用此功能。如需了解详情，请参阅 [#requirements]。 或者，您可以使用 --release-channel 标志并指定发布渠道。

控制台

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

转到 Google Kubernetes Engine
点击创建。
选择标准集群模式，然后点击配置。
根据您的需求配置集群。
在导航窗格的集群下，点击功能。
选中启用 Filestore CSI 驱动程序复选框。
点击创建。

如果要在共享 VPC 网络中使用 Filestore，请参阅在具有共享 VPC 的新集群上启用 Filestore CSI 驱动程序。

启用 Filestore CSI 驱动程序后，您可以通过驱动程序和预配工具名称 filestore.csi.storage.gke.io 在 Kubernetes 卷中使用该驱动程序。

在现有集群上启用 Filestore CSI 驱动程序

如需在现有集群中启用 Filestore CSI 驱动程序，请使用 Google Cloud CLI 或 Google Cloud 控制台。

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

gcloud

gcloud container clusters update CLUSTER_NAME \
   --update-addons=GcpFilestoreCsiDriver=ENABLED

将 CLUSTER_NAME 替换为现有集群的名称。

控制台

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

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

停用 Filestore CSI 驱动程序

您可以使用 Google Cloud CLI 或 Google Cloud 控制台在现有 Autopilot 或 Standard 集群上停用 Filestore CSI 驱动程序。

gcloud

gcloud container clusters update CLUSTER_NAME \
    --update-addons=GcpFilestoreCsiDriver=DISABLED \
    --region REGION

替换以下值：

CLUSTER_NAME：现有集群的名称。
REGION：集群的区域，例如 us-central1。

控制台

在 Google Cloud 控制台中，转到 Google Kubernetes Engine 菜单。

转到 Google Kubernetes Engine
在集群列表中，点击您要修改的集群的名称。
在功能下，点击 Filestore CSI 驱动程序字段旁边的 修改 Filestore CSI 驱动程序。
清除启用 Filestore CSI 驱动程序复选框。
点击保存更改。

使用 Filestore CSI 驱动程序访问已有的 Filestore 实例

本部分介绍在 GKE 中使用 Kubernetes 卷和 Filestore CSI 驱动程序访问已有的 Filestore 实例的典型过程：

创建 PersistentVolume 和 PersistentVolumeClaim 以访问实例

创建一个如以下示例所示的清单文件，并将其命名为 preprov-filestore.yaml：

apiVersion: v1
kind: PersistentVolume
metadata:
  name: PV_NAME
spec:
  storageClassName: ""
  capacity:
    storage: 1Ti
  accessModes:
    - ReadWriteMany
  persistentVolumeReclaimPolicy: Retain
  volumeMode: Filesystem
  csi:
    driver: filestore.csi.storage.gke.io
    volumeHandle: "modeInstance/FILESTORE_INSTANCE_LOCATION/FILESTORE_INSTANCE_NAME/FILESTORE_SHARE_NAME"
    volumeAttributes:
      ip: FILESTORE_INSTANCE_IP
      volume: FILESTORE_SHARE_NAME
---
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: podpvc
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: ""
  volumeName: PV_NAME
  resources:
    requests:
      storage: 1Ti

如需根据 preprov-filestore.yaml 清单文件创建 PersistentVolumeClaim 和 PersistentVolume 资源，请运行以下命令：
```
kubectl apply -f preprov-filestore.yaml
```

然后，继续创建使用该卷的 Deployment。

使用 Filestore CSI 驱动程序创建卷

以下几个部分介绍了在 GKE 中使用 Filestore CSI 驱动程序支持的 Kubernetes 卷的典型过程：

创建一个 StorageClass
使用 PersistentVolumeClaim 访问卷
创建使用该卷的 Deployment

创建一个 StorageClass

启用 Filestore CSI 驱动程序后，GKE 会自动安装以下 StorageClasses 以预配 Filestore 实例：

zonal-rwx，使用 Filestore 可用区层级。仅适用于更高容量范围（10 TiB 到 100 TiB）。
enterprise-rwx，使用 Filestore 企业层级，其中每个 Kubernetes PersistentVolume 都映射到一个 Filestore 实例。
enterprise-multishare-rwx，使用 Filestore 企业层级，其中每个 Kubernetes PersistentVolume 都映射到给定 Filestore 实例的共享。如需了解详情，请参阅 Filestore Multishares for Google Kubernetes Engine。
standard-rwx，使用 Filestore 基本 HDD 服务层级。
premium-rwx，使用 Filestore 基本 SSD 服务层级。

每个 StorageClass 仅适用于运行其各自受支持 GKE 版本号的 GKE 集群。如需查看每个服务层级所需的受支持版本的列表，请参阅要求。

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

kubectl get sc

您还可以通过在 provisioner 字段中添加 filestore.csi.storage.gke.io 来安装其他使用 Filestore CSI 驱动程序的 StorageClass。

Filestore 有必要知道应在哪个网络上创建新实例。自动安装的 StorageClass 使用为 GKE 集群创建的默认网络。如果您删除了此网络或者希望使用其他网络，则必须按照以下步骤创建新的 StorageClass。否则，自动安装的 StorageClass 将不起作用。

将以下清单保存为 filestore-example-class.yaml：
```
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: filestore-example
provisioner: filestore.csi.storage.gke.io
volumeBindingMode: Immediate
allowVolumeExpansion: true
parameters:
  tier: standard
  network: default
```
从清单中，请考虑以下参数配置：
- 将 volumeBindingMode 设置为 Immediate 允许立即开始预配卷。之所以有这种可能性，是因为 Filestore 实例可以从任何可用区进行访问。因此，与 Compute Engine 永久性磁盘相比，GKE 不需要知道 Pod 被安排在哪个可用区。如果设置为 WaitForFirstConsumer，则只有在安排 Pod 后才能开始 GKE 预配。如需了解详情，请参阅 VolumeBindingMode。
- 您可以在 tier 参数中指定任何受支持的 Filestore 层级（例如 BASIC_HDD、BASIC_SSD、ZONAL 或 ENTERPRISE）。
- 在非默认 VPC 上预配 Filestore 实例时，可以使用 network 参数。非默认 VPC 需要设置特殊的防火墙规则。
如需根据 filestore-example-class.yaml 清单文件创建 StorageClass 资源，请运行以下命令：
```
kubectl create -f filestore-example-class.yaml
```

如果要在共享 VPC 网络中使用 Filestore，请参阅将 Filestore CSI 驱动程序与共享 VPC 一起使用时创建 StorageClass。

使用 PersistentVolumeClaim 访问卷

您可以创建一个引用 Filestore CSI 驱动程序的 StorageClass 的 PersistentVolumeClaim 资源。

您可以使用预安装或自定义的 StorageClass。

以下示例清单文件创建了一个引用 StorageClass（名为 filestore-example）的 PersistentVolumeClaim。

将以下清单文件保存为 pvc-example.yaml：

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: podpvc
spec:
  accessModes:
  - ReadWriteMany
  storageClassName: filestore-example
  resources:
    requests:
      storage: 1Ti

如需根据 pvc-example.yaml 清单文件创建 PersistentVolume 资源，请运行以下命令：
```
kubectl create -f pvc-example.yaml
```

创建使用该卷的 Deployment

以下示例 Deployment 清单使用名为 pvc-example.yaml 的 PersistentVolume 资源。

多个 Pod 可以共享同一 PersistentVolumeClaim 资源。

将以下清单保存为 filestore-example-deployment.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-server-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
        volumeMounts:
        - mountPath: /usr/share/nginx/html
          name: mypvc
      volumes:
      - name: mypvc
        persistentVolumeClaim:
          claimName: podpvc
---
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: podpvc
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: filestore-example
  resources:
    requests:
      storage: 1Ti

如需根据 filestore-example-deployment.yaml 清单文件创建 Deployment，请运行以下命令：
```
kubectl apply -f filestore-example-deployment.yaml
```
确认已成功创建 Deployment：
```
kubectl get deployment
```
Filestore 实例可能需要一段时间才能完成预配。在此之前，Deployment 不会报告 READY 状态。您可以运行以下命令来监控 PVC 状态，以查看进度：
```
kubectl get pvc
```
卷预配完成后，您应该会看到 PVC 变为 BOUND 状态。

为 Filestore 实例添加标签

您可以使用标签对相关实例进行分组，并存储有关实例的元数据。标签是一种键值对，可帮助您组织 Filestore 实例。您可以将标签附加到各项资源，然后根据其标签对资源进行过滤。

您可以使用 StorageClass.parameters 中的 labels 键提供标签。Filestore 实例可以使用有关创建实例的 PersistentVolumeClaim/PersistentVolume 的信息进行标记。自定义标签键和值必须遵循标签的命名惯例。请参阅 Kubernetes 存储类别示例，将自定义标签应用于 Filestore 实例。

将 fsgroup 与 Filestore 卷搭配使用

Kubernetes 使用 fsGroup 更改卷的权限和所有权，以匹配 Pod 的 SecurityContext 中用户请求的 fsGroup。fsGroup 是适用于 Pod 中的所有容器的补充组。您可以将 fsgroup 应用于由 Filestore CSI 驱动程序预配的卷。

使用 Filestore 卷配置 IP 访问规则

Filestore 支持适用于卷的基于 IP 的访问权限控制规则。此功能适用于运行 1.29.5 或更高版本的 GKE 集群。

此功能允许管理员指定允许哪些 IP 地址范围访问通过 GKE 动态预配的 Filestore 实例。这样可以通过将访问权限限制为仅限已获授权的客户端来提高安全性，尤其是在 GKE 集群的 IP 范围过宽且可能会将 Filestore 实例暴露给未获授权的用户或应用的情况下。

您可以直接通过 Filestore API 配置这些规则，也可以在创建卷时通过 Filestore CSI 驱动程序配置这些规则。您可以使用 nfs-export-options-on-create 参数在 StorageClass 中以 JSON 格式提供所选配置。

以下示例清单展示了如何指定配置：

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: filestore-example
provisioner: filestore.csi.storage.gke.io
volumeBindingMode: Immediate
allowVolumeExpansion: true
parameters:
  tier: "enterprise"
  nfs-export-options-on-create: '[
    {
      "accessMode": "READ_WRITE",
      "ipRanges": [
        "10.0.0.0/24"
      ],
      "squashMode": "ROOT_SQUASH",
      "anonUid": "1003",
      "anonGid": "1003"
    },
    {
      "accessMode": "READ_WRITE",
      "ipRanges": [
        "10.0.0.0/28"
      ],
      "squashMode": "NO_ROOT_SQUASH"
    }
  ]'

安全选项

Filestore IP 访问规则简化了为 GKE 工作负载配置共享文件存储权限的流程。但是，要了解它如何管理文件所有权和访问权限，需要掌握一些关键概念：

NFS 和用户映射 NFS（网络文件系统）是 Filestore 使用的协议。其工作原理是，将客户端系统（GKE pod）上的用户映射到 Filestore 服务器上的用户。如果服务器上的某个文件归用户 ID 1003 所有，而客户端通过用户 ID 1003 进行连接，那么就可以访问该文件。
根用户废除和 anonUid：
- 根用户废除 ROOT_SQUASH 是一项安全功能，可防止客户端使用完整的 root 权限访问 Filestore 实例。启用根用户废除功能后，客户端系统上的根用户会映射到 anonUid 设置指定的非特权用户。
- 无根用户废除 (NO_ROOT_SQUASH) 允许客户端使用完整的 root 权限访问 Filestore 实例，这对于初始设置很方便，但对于常规操作来说不太安全。
初始设置和权限：默认情况下，新 Filestore 实例完全由根用户拥有。如果您没有先为其他用户设置权限，就启用根用户废除功能，则您会失去访问权限。因此，您至少需要一条具有 NO_ROOT_SQUASH 的 NFS 导出规则，才能初始配置其他用户和群组的访问权限。

建议

初始设置：始终从至少一条 NFS 导出规则开始，该规则指定具有 READ_WRITE 权限的管理员范围并允许 NO_ROOT_SQUASH 访问权限。您可以使用此访问权限根据需要创建目录、设置权限和分配所有权。
安全性：启用根用户废除功能 (ROOT_SQUASH) 以增强安全性。请注意，创建卷后，您只能通过 Filestore API 修改访问规则。
共享访问权限：在 Pod 安全上下文中使用 fsGroup 来管理共享卷的组所有权。请确保您的设置不会与 ROOT_SQUASH 模式重叠。否则，系统会返回 Access denied 错误消息。

将 Filestore 与共享 VPC 搭配使用

本部分介绍如何在服务项目的共享 VPC 网络中使用 Filestore 实例。

设置具有共享 VPC 的集群

如需设置具有共享 VPC 网络的集群，请按以下步骤操作：

在具有共享 VPC 的新集群上启用 Filestore CSI 驱动程序

如需在具有共享 VPC 的新集群上启用 Filestore CSI 驱动程序，请按以下步骤操作：

验证可用子网和次要范围。创建集群时，您必须指定要用于集群 Pod 和 Service 的子网和次要 IP 地址范围。

gcloud container subnets list-usable \
   --project=SERVICE_PROJECT_ID \
   --network-project=HOST_PROJECT_ID

输出类似于以下内容：

PROJECT                   REGION       NETWORK     SUBNET  RANGE
HOST_PROJECT_ID  us-central1  shared-net  tier-1  10.0.4.0/22
┌──────────────────────┬───────────────┬─────────────────────────────┐
│ SECONDARY_RANGE_NAME │ IP_CIDR_RANGE │            STATUS           │
├──────────────────────┼───────────────┼─────────────────────────────┤
│ tier-1-pods          │ 10.4.0.0/14   │ usable for pods or services │
│ tier-1-services      │ 10.0.32.0/20  │ usable for pods or services │
└──────────────────────┴───────────────┴─────────────────────────────┘

创建 GKE 集群。以下示例展示了如何使用 gcloud CLI 创建配置为使用共享 VPC 的 Autopilot 或 Standard 集群。以下示例使用创建网络和两个子网中的网络、子网和范围名称。

Autopilot

gcloud container clusters create-auto tier-1-cluster \
   --project=SERVICE_PROJECT_ID \
   --region=COMPUTE_REGION \
   --network=projects/HOST_PROJECT_ID/global/networks/NETWORK_NAME \
   --subnetwork=projects/HOST_PROJECT_ID/regions/COMPUTE_REGION/subnetworks/SUBNET_NAME \
   --cluster-secondary-range-name=tier-1-pods \
   --services-secondary-range-name=tier-1-services

标准

gcloud container clusters create tier-1-cluster \
   --project=SERVICE_PROJECT_ID \
   --zone=COMPUTE_REGION \
   --enable-ip-alias \
   --network=projects/HOST_PROJECT_ID/global/networks/NETWORK_NAME \
   --subnetwork=projects/HOST_PROJECT_ID/regions/COMPUTE_REGION/subnetworks/SUBNET_NAME \
   --cluster-secondary-range-name=tier-1-pods \
   --services-secondary-range-name=tier-1-services \
   --addons=GcpFilestoreCsiDriver

创建防火墙规则以允许在集群中的节点、Pod 和 Service 之间进行通信。以下示例展示了如何创建名为 my-shared-net-rule-2 的防火墙规则。
```
gcloud compute firewall-rules create my-shared-net-rule-2 \
   --project HOST_PROJECT_ID \
   --network=NETWORK_NAME \
   --allow=tcp,udp \
   --direction=INGRESS \
   --source-ranges=10.0.4.0/22,10.4.0.0/14,10.0.32.0/20
```
在此示例中，来源范围 IP 值来自您验证了可用子网和次要范围的之前步骤。

在将 Filestore CSI 驱动程序与共享 VPC 搭配使用时创建 StorageClass

以下示例展示了如何在将 Filestore CSI 驱动程序与共享 VPC 搭配使用时创建 StorageClass：

cat <<EOF | kubectl apply -f -

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: filestore-sharedvpc-example
provisioner: filestore.csi.storage.gke.io
parameters:
  network: "projects/HOST_PROJECT_ID/global/networks/SHARED_VPC_NAME"
  connect-mode: PRIVATE_SERVICE_ACCESS
  reserved-ip-range: RESERVED_IP_RANGE_NAME
allowVolumeExpansion: true

EOF

请替换以下内容：

HOST_PROJECT_ID：共享 VPC 网络的宿主项目的 ID 或名称。
SHARED_VPC_NAME：您之前创建的共享 VPC 网络的名称。
RESERVED_IP_RANGE_NAME：要在其中预配 Filestore 实例的特定预留 IP 地址范围的名称。此字段是可选字段。如果指定了预留的 IP 地址范围，则该范围必须是已命名的地址范围，而非直接 CIDR 值。

如果要在运行 1.23 或更高版本的 Filestore Multishares on GKE 集群上预配由 Filestore 多共享提供支持的卷，请参阅使用 Filestore multishares for GKE 优化存储空间。

重新连接 Filestore 单个共享卷

如果您将 Filestore 与基本 HDD、基本 SSD 或企业（单共享）层级搭配使用，则可以按照以下说明将现有 Filestore 实例重新连接到 GKE 工作负载。

按照获取特定实例的相关信息中的说明，查找预配的 Filestore 实例的详细信息。
重新部署您的 PersistentVolume 规范。在 volumeAttributes 字段中，修改以下字段，使其使用与第 1 步中的 Filestore 实例相同的值：
- ip：将此值修改为预配的 Filestore 实例 IP 地址。
- volume：将此值修改为预配的 Filestore 实例的共享名称。
重新部署您的 PersistentVolumeClaim 规范。在 volumeName 中，请确保引用与第 2 步中相同的 PersistentVolume 名称。
运行 kubectl get pvc 以检查 PersistentVolumeClaim 和 PersistentVolume 的绑定状态。
重新部署 Pod 规范，并确保您的 Pod 能够再次访问 Filestore 共享。

使用 Filestore CSI 驱动程序访问 Filestore 实例

优势

要求

须知事项

在新集群上启用 Filestore CSI 驱动程序

gcloud

控制台

在现有集群上启用 Filestore CSI 驱动程序

gcloud

控制台

停用 Filestore CSI 驱动程序

gcloud

控制台

使用 Filestore CSI 驱动程序访问已有的 Filestore 实例

创建 PersistentVolume 和 PersistentVolumeClaim 以访问实例

使用 Filestore CSI 驱动程序创建卷

创建一个 StorageClass

使用 PersistentVolumeClaim 访问卷

创建使用该卷的 Deployment

为 Filestore 实例添加标签

将 fsgroup 与 Filestore 卷搭配使用

使用 Filestore 卷配置 IP 访问规则

安全选项

建议

将 Filestore 与共享 VPC 搭配使用

设置具有共享 VPC 的集群

在具有共享 VPC 的新集群上启用 Filestore CSI 驱动程序

Autopilot

标准

在将 Filestore CSI 驱动程序与共享 VPC 搭配使用时创建 StorageClass

重新连接 Filestore 单个共享卷

后续步骤