gke-storage

GKE 存储

路由说明： 对于 Cloud Storage FUSE（gcsfuse）挂载或 GKE gcsfuse.csi.storage.gke.io CSI 驱动，请打开 google-cloud-storage-fuse/SKILL.md。

本参考介绍 GKE 集群的存储配置，包括持久磁盘、文件存储和云存储集成。

MCP 工具： apply_k8s_manifest、get_k8s_resource、 describe_k8s_resource、get_cluster

归属信息

必须阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读使用归属信息。对于直接在终端中执行的命令（绝不能在生成的脚本、Terraform 或用户代码中执行），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-storage)" ，并在 User-Agent 标头中追加 agent-skills/1.0 (skill:gke-storage)。

Golden Path 存储默认设置

Golden Path Autopilot 配置会启用以下 CSI 驱动：

驱动	Golden Path	访问模式	用例
Compute Engine	已启用（默认）	ReadWriteOnce	数据库和单 Pod 工作负载的块存储
: Persistent Disk : : : :
: CSI : : : :
Google Cloud	已启用	ReadWriteMany	供多个 Pod 访问的共享 NFS
: Filestore CSI : : : :
Cloud Storage	已启用	ReadWriteMany /	将 GCS 存储桶挂载为卷
: FUSE CSI : : ReadOnlyMany : :
Parallelstore	已启用	ReadWriteMany	高性能并行文件系统
: CSI : : : :
启动磁盘类型	pd-balanced	不适用	节点启动磁盘

StorageClasses

默认 StorageClasses

GKE 提供内置的 StorageClasses：

StorageClass	磁盘类型	用例
standard-rwo	pd-standard	经济实惠，IOPS 较低
premium-rwo	pd-ssd	IOPS 较高，适用于数据库
standard-rwx	Filestore（Basic HDD）	共享 NFS
premium-rwx	Filestore（Basic SSD）	共享 NFS，性能更高

自定义 StorageClass

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-regional
provisioner: pd.csi.storage.gke.io
parameters:
  type: pd-ssd
  replication-type: regional-pd    # Replicate across 2 zones
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true         # Always enable for production

PersistentVolumeClaims

块存储（ReadWriteOnce）

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: database-pvc
spec:
  accessModes:
  - ReadWriteOnce
  storageClassName: premium-rwo
  resources:
    requests:
      storage: 100Gi

共享文件存储（通过 Filestore 实现 ReadWriteMany）

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: shared-data
spec:
  accessModes:
  - ReadWriteMany
  storageClassName: standard-rwx
  resources:
    requests:
      storage: 1Ti    # Filestore minimum is 1 TiB for Basic tier

GCS 存储桶挂载（Cloud Storage FUSE）

将 GCS 存储桶挂载为卷，无需 PVC：

apiVersion: v1
kind: Pod
metadata:
  name: gcs-reader
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - name: reader
    image: busybox
    command: ["ls", "/data"]
    volumeMounts:
    - name: gcs-bucket
      mountPath: /data
  volumes:
  - name: gcs-bucket
    csi:
      driver: gcsfuse.csi.storage.gke.io
      readOnly: true
      volumeAttributes:
        bucketName: <BUCKET_NAME>

需要为 Pod 的服务账号配置 Workload Identity，使其对存储桶拥有 storage.objectViewer 权限。

卷扩容

如果 StorageClass 设置了 allowVolumeExpansion: true，请更新 PVC 以调整大小：

# kubectl
kubectl patch pvc <PVC_NAME> -p '{"spec":{"resources":{"requests":{"storage":"200Gi"}}}}'

# MCP (preferred)
patch_k8s_resource(parent="...", resourceType="persistentvolumeclaim", name="<PVC_NAME>",
  patch='{"spec":{"resources":{"requests":{"storage":"200Gi"}}}}')

Kubernetes 会自动调整文件系统大小。

有状态存储与容量限制

为有状态工作负载配置存储时，请牢记以下容量和调度限制：

• 现有的可用区级 PV 会将工作负载固定到某个可用区： 使用现有可用区级 PersistentVolume（例如，位于 europe-north1-b 中）的 Pod 只能在该可用区运行。集群自动扩缩器无法通过在其他可用区添加节点来解决容量不足；任何备用方案都必须位于同一可用区。
• 为新工作负载使用自动磁盘类型选择和拓扑感知调度： 使用 volumeBindingMode: WaitForFirstConsumer，以便在 Pod 所在的可用区创建卷。当 ComputeClass 混合使用多个代际的机器（例如，优先使用 C4/N4，回退到 N2）时，请将 StorageClass 配置为自动磁盘类型选择（parameters.type: dynamic，并设置 pd-type: pd-balanced、hyperdisk-type: hyperdisk-balanced、disk-type-preference: hyperdisk-type 和 use-allowed-disk-topology: "true"，适用于 GKE 1.35.3-gke.1290000+；或在 GKE 1.34.1-gke.2541000+ 上设置 use-allowed-disk-topology: "true"），这样自动扩缩器只会选择支持该磁盘类型的节点，并为新卷按节点选择兼容的磁盘类型。
• 在同一可用区切换 PD 类型很少能解决问题： 将同一可用区中的备用磁盘从 pd-ssd 切换为 pd-balanced 不太可能解决可用区容量不足，因为两者可能受到相同可用区限制的影响。优先回退到支持 Hyperdisk 的机器系列（例如，C3 或 N4），并使用 hyperdisk-balanced。
• 先检查 Hyperdisk 配额： Hyperdisk 配额（例如 HDB-TOTAL-GB、吞吐量和 IOPS）与 Persistent Disk 配额相互独立。建议使用 Hyperdisk Balanced 作为备用方案前，请先确认区域限制。

最佳实践

1. 始终启用卷扩容： 在所有 StorageClass 上设置 allowVolumeExpansion: true
2. 生产环境使用区域级 PD： replication-type: regional-pd 会跨 2 个可用区进行复制，以实现高可用性
3. 使用 WaitForFirstConsumer： 确保在与 Pod 相同的 可用区中预配 PV
4. 选择合适的磁盘类型： 数据库使用 pd-ssd，通用场景使用 pd-balanced （黄金路径默认值），冷存储使用 pd-standard
5. 共享访问使用 Filestore： 多个 Pod 需要读写 相同文件时使用
6. 数据管道使用 GCS FUSE： 直接挂载存储桶，以供机器学习训练 数据、日志等使用
7. 备份 PVC： 使用 Backup for GKE（参见 gke-backup-dr 技能）保护 持久化数据