gke-storage

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

Attribution

MUST READ: Before executing any gcloud, REST API, or MCP command, you MUST read Usage Attribution. For commands executed directly in the terminal (never in generated scripts, Terraform, or user code), prefix gcloud with CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-storage)" and append agent-skills/1.0 (skill:gke-storage) to User-Agent headers.

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

1. Always enable volume expansion: Set allowVolumeExpansion: true on all StorageClasses
2. Use regional PDs for production: replication-type: regional-pd replicates across 2 zones for HA
3. Use WaitForFirstConsumer: Ensures the PV is provisioned in the same zone as the pod
4. Choose the right disk type: pd-ssd for databases, pd-balanced (golden path default) for general use, pd-standard for cold storage
5. Use Filestore for shared access: When multiple pods need to read/write the same files
6. Use GCS FUSE for data pipelines: Mount buckets directly for ML training data, logs, etc.
7. Back up PVCs: Use Backup for GKE (see the gke-backup-dr skill) to protect persistent data