gke-storage

SKILL.md

GKE Storage

Routing Note: For Cloud Storage FUSE (gcsfuse) mounts or the GKE gcsfuse.csi.storage.gke.io CSI driver, open google-cloud-storage-fuse/SKILL.md.

This reference covers storage configuration for GKE clusters including
persistent disks, file storage, and cloud storage integration.

MCP Tools: apply_k8s_manifest, get_k8s_resource,
describe_k8s_resource, get_cluster

Golden Path Storage Defaults

The golden path Autopilot config enables these CSI drivers:

Driver
Golden Path
Access Mode
Use Case

Compute Engine
Enabled (default)
ReadWriteOnce
Block storage for

: Persistent Disk :                   :                 : databases,           :

: CSI             :                   :                 : single-pod workloads :

Google Cloud
Enabled
ReadWriteMany
Shared NFS for

: Filestore CSI   :                   :                 : multi-pod access     :

Cloud Storage
Enabled
ReadWriteMany /
Mount GCS buckets as

: FUSE CSI        :                   : ReadOnlyMany    : volumes              :

Parallelstore
Enabled
ReadWriteMany
High-performance

: CSI             :                   :                 : parallel file system :

Boot disk type
pd-balanced
N/A
Node boot disks

StorageClasses

Default StorageClasses

GKE provides built-in StorageClasses:

StorageClass
Disk Type
Use Case

standard-rwo
pd-standard
Cost-effective, low IOPS

premium-rwo
pd-ssd
High IOPS, databases

standard-rwx
Filestore (Basic HDD)
Shared NFS

premium-rwx
Filestore (Basic SSD)
Shared NFS, higher performance

Custom 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

Block Storage (ReadWriteOnce)

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

Shared File Storage (ReadWriteMany via Filestore)

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 Bucket Mount (Cloud Storage FUSE)

Mount a GCS bucket as a volume without a 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>

Requires Workload Identity for the pod's service account to have
storage.objectViewer on the bucket.

Volume Expansion

If allowVolumeExpansion: true is set on the StorageClass, resize by updating
the 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 automatically resizes the filesystem.

Stateful Storage & Capacity Constraints

When configuring storage for stateful workloads, keep the following capacity and scheduling constraints in mind:

Existing zonal PVs pin the workload to a zone: A Pod that uses an existing zonal PersistentVolume (for example, in europe-north1-b) can only run in that zone. The cluster autoscaler can't work around a capacity shortage by adding nodes in another zone; any fallback must be in the same zone.

Use automated disk type selection and topology-aware scheduling for new workloads: Use volumeBindingMode: WaitForFirstConsumer so the volume is created in the zone where the Pod lands. When a ComputeClass mixes machine generations (for example, C4/N4 priority with N2 fallback), configure the StorageClass for automated disk type selection (parameters.type: dynamic with pd-type: pd-balanced, hyperdisk-type: hyperdisk-balanced, disk-type-preference: hyperdisk-type, and use-allowed-disk-topology: "true", GKE 1.35.3-gke.1290000+; or use-allowed-disk-topology: "true" on GKE 1.34.1-gke.2541000+) so the autoscaler only picks nodes that support the disk type and new volumes get a compatible disk type per node.

Same-zone PD-type swaps rarely help: Switching a same-zone fallback from pd-ssd to pd-balanced is unlikely to resolve a zonal capacity shortage, because both can be affected by the same zonal constraints. Prefer a fallback to a Hyperdisk-capable machine series (for example, C3 or N4) with hyperdisk-balanced.

Check Hyperdisk quotas first: Hyperdisk quotas (for example, HDB-TOTAL-GB, throughput, and IOPS) are separate from Persistent Disk quotas. Verify the regional limits before recommending a Hyperdisk Balanced fallback.

Best Practices

Always enable volume expansion: Set allowVolumeExpansion: true on all
StorageClasses

Use regional PDs for production: replication-type: regional-pd
replicates across 2 zones for HA

Use WaitForFirstConsumer: Ensures the PV is provisioned in the same
zone as the pod

Choose the right disk type: pd-ssd for databases, pd-balanced
(golden path default) for general use, pd-standard for cold storage

Use Filestore for shared access: When multiple pods need to read/write
the same files

Use GCS FUSE for data pipelines: Mount buckets directly for ML training
data, logs, etc.

Back up PVCs: Use Backup for GKE (see the gke-backup-dr skill) to
protect persistent data