Parameters & Binding

StorageClass parameters allow you to customize how storage is provisioned, while binding modes control when volume provisioning and binding occur. Understanding these concepts helps you optimize storage provisioning for your specific needs and improve pod scheduling.

StorageClass Parameters

Parameters are key-value pairs that are passed to the provisioner (CSI driver) when creating a volume. Each provisioner supports different parameters, allowing you to customize storage characteristics like disk type, zone, encryption, and performance settings.

graph TB A[StorageClass] --> B[Parameters] B --> C[Provisioner Receives Parameters] C --> D[Volume Created with Settings] B --> E[disk type] B --> F[zone] B --> G[encryption] B --> H[IOPS] B --> I[replication] style A fill:#e1f5ff style B fill:#fff4e1 style C fill:#e8f5e9 style D fill:#f3e5f5

Common Parameters by Provider

Google Cloud Platform (GCE)

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gce-fast
provisioner: pd.csi.storage.gke.io
parameters:
  type: pd-ssd              # Disk type: pd-standard, pd-ssd, pd-balanced
  replication-type: regional-pd  # Regional persistent disk (replicated)
  zones: us-central1-a,us-central1-b  # Specific zones
volumeBindingMode: WaitForFirstConsumer

Common GCE parameters:

type: pd-standard, pd-ssd, pd-balanced
replication-type: none (zonal) or regional-pd (regional)
zones: Comma-separated list of zones
disk-encryption-kms-key: KMS key for encryption

Amazon Web Services (EBS)

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: aws-fast
provisioner: ebs.csi.aws.com
parameters:
  type: gp3                   # Volume type: gp2, gp3, io1, io2, st1, sc1
  iops: "3000"                # IOPS (for gp3, io1, io2)
  throughput: "125"           # Throughput in MB/s (for gp3)
  encrypted: "true"           # Enable encryption
  kmsKeyId: "arn:aws:kms:..." # KMS key for encryption
volumeBindingMode: WaitForFirstConsumer

Common AWS EBS parameters:

type: gp2, gp3, io1, io2, st1, sc1
iops: IOPS for gp3, io1, io2
throughput: Throughput in MB/s for gp3
encrypted: true or false
kmsKeyId: KMS key ARN for encryption
fsType: Filesystem type (ext4, xfs, ntfs)

Azure Disk

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: azure-fast
provisioner: disk.csi.azure.com
parameters:
  skuName: Premium_LRS      # Premium_LRS, StandardSSD_LRS, Standard_LRS, UltraSSD_LRS
  location: eastus           # Azure region
  storageAccount: mystorageaccount  # Storage account (for Standard_LRS)
  fsType: ext4               # Filesystem type
volumeBindingMode: WaitForFirstConsumer

Common Azure parameters:

skuName: Premium_LRS, StandardSSD_LRS, Standard_LRS, UltraSSD_LRS
location: Azure region
storageAccount: Storage account name (for Standard_LRS)
fsType: Filesystem type (ext4, xfs)

NFS (Generic)

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: nfs-storage
provisioner: nfs.csi.k8s.io
parameters:
  server: nfs.example.com    # NFS server address
  share: /exports            # NFS share path
volumeBindingMode: Immediate

Volume Binding Modes

Volume binding mode determines when the volume binding and dynamic provisioning occurs in relation to when a pod using the PVC is scheduled.

Immediate Binding

With volumeBindingMode: Immediate, the volume is provisioned and bound as soon as the PVC is created, before any pod is scheduled.

Characteristics:

Volume provisioned immediately when PVC is created
Binding happens before pod scheduling
Volume may be created in a different zone than the pod
Faster pod startup (volume already exists)
Less flexible for multi-zone clusters

sequenceDiagram participant User participant K8s as Kubernetes participant Prov as Provisioner participant Pod User->>K8s: Create PVC K8s->>Prov: Provision volume (any zone) Prov->>K8s: PV created K8s->>User: PVC bound User->>K8s: Create Pod K8s->>Pod: Schedule pod (may be different zone)

Example:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: immediate-storage
provisioner: pd.csi.storage.gke.io
parameters:
  type: pd-standard
volumeBindingMode: Immediate  # Bind immediately

Use cases:

Single-zone clusters
When zone doesn’t matter
Faster pod startup is more important than zone optimization

WaitForFirstConsumer Binding

With volumeBindingMode: WaitForFirstConsumer, the volume provisioning and binding is delayed until a pod using the PVC is scheduled. This allows the volume to be created in the same zone as the pod.

Characteristics:

Volume provisioned only when pod is scheduled
Binding happens after pod scheduling
Volume created in the same zone as the pod
Better for multi-zone clusters
Slightly slower pod startup (volume created on demand)

sequenceDiagram participant User participant K8s as Kubernetes participant Sched as Scheduler participant Prov as Provisioner participant Pod User->>K8s: Create PVC K8s->>User: PVC created (unbound) User->>K8s: Create Pod with PVC K8s->>Sched: Schedule pod (select zone) Sched->>Prov: Provision volume (pod's zone) Prov->>K8s: PV created in pod's zone K8s->>Pod: Bind and start pod

Example:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: wait-storage
provisioner: pd.csi.storage.gke.io
parameters:
  type: pd-ssd
volumeBindingMode: WaitForFirstConsumer  # Wait for pod

Use cases:

Multi-zone clusters
Zone-optimized storage (reduced latency)
Regional persistent disks
When pod zone placement matters

Binding Mode Comparison

graph TB subgraph immediate[Immediate Binding] A[PVC Created] --> B[Volume Provisioned] B --> C[PV Bound] C --> D[Pod Scheduled] D --> E[Volume May Be in Different Zone] end subgraph wait[WaitForFirstConsumer] F[PVC Created] --> G[Pod Scheduled] G --> H[Volume Provisioned in Pod's Zone] H --> I[PV Bound] I --> J[Pod Starts] end style E fill:#ffe1e1 style J fill:#e8f5e9

Complete Example

Here’s a complete example showing parameters and binding modes:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: production-ssd
provisioner: pd.csi.storage.gke.io
parameters:
  type: pd-ssd                    # SSD disk type
  replication-type: regional-pd   # Regional replication
volumeBindingMode: WaitForFirstConsumer  # Wait for pod scheduling
reclaimPolicy: Retain             # Retain on PVC deletion
allowVolumeExpansion: true        # Allow volume expansion
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: production-ssd
  resources:
    requests:
      storage: 100Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: app
        image: nginx
        volumeMounts:
        - name: data
          mountPath: /data
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: app-data

Parameter Validation

Parameters are passed directly to the provisioner without validation by Kubernetes. If invalid parameters are provided:

Volume provisioning may fail
Errors appear in provisioner logs
PVC remains in Pending state
Events show provisioning errors

Check provisioning errors:

# Check PVC events
kubectl describe pvc <pvc-name>

# Check provisioner logs
kubectl logs -n kube-system <provisioner-pod>

Best Practices

Use WaitForFirstConsumer for multi-zone - Better zone optimization
Use Immediate for single-zone - Simpler and faster
Document parameters - Document what each parameter does
Test parameter combinations - Verify parameters work together
Use appropriate disk types - Match storage class to workload needs
Enable encryption - Use encryption parameters for sensitive data
Set IOPS/throughput appropriately - Match performance parameters to workload
Review provisioner documentation - Each provisioner has different parameters

Troubleshooting

PVC Stuck in Pending (Invalid Parameters)

If a PVC is stuck due to invalid parameters:

Check PVC events: kubectl describe pvc <name>
Review provisioner logs for parameter errors
Verify parameters match provisioner documentation
Test with minimal parameters first

Volume in Wrong Zone

If volumes are created in the wrong zone:

Use WaitForFirstConsumer binding mode
Verify zones are configured correctly
Check pod scheduling constraints
Review StorageClass zone parameters

Provisioning Failures

If volume provisioning fails:

Check provisioner pod status: kubectl get pods -n kube-system | grep provisioner
Review provisioner logs
Verify storage quota/limits
Check network connectivity to storage system
Verify provisioner has necessary permissions