Skip to main content

OpenStack Cinder CSI

Purpose: For platform engineers, shows how to configure OpenStack Cinder CSI for volume provisioning and availability zones.

What OpenStack Cinder CSI Does​

The OpenStack Cinder CSI driver provisions Kubernetes persistent volumes backed by OpenStack Cinder block storage. It creates, attaches, detaches, and deletes Cinder volumes in response to PersistentVolumeClaim lifecycle events. This driver is deployed on OpenStack provider clusters as the primary storage backend.

How It's Deployed​

The Cinder CSI driver is deployed via FluxCD from openCenter-gitops-base:

openCenter-gitops-base/applications/base/services/openstack-csi/
├── namespace.yaml
├── source.yaml
├── helmrelease.yaml
└── helm-values/
    └── hardened-values.yaml

Customer overlay:

applications/overlays/<cluster>/services/openstack-csi/
├── kustomization.yaml
└── override-values.yaml

The driver requires OpenStack credentials to interact with the Cinder API.

Key Configuration​

OpenStack Credentials​

The driver authenticates to the OpenStack Cinder API using application credentials stored in a Kubernetes Secret. The secret is created by openCenter-cli and encrypted with SOPS:

# The cloud.conf is stored in a SOPS-encrypted secret
# applications/overlays/<cluster>/services/openstack-csi/override-values.yaml
clusterID: <cluster-name>
secret:
  enabled: true
  hostMount: true
  create: true
  filename: cloud.conf
  name: <cluster-name>-cloud-config
  data:
    cloud.conf: |
      [Global]
      auth-url=<openstack-auth-url>
      application-credential-id=<credential-id>
      application-credential-secret=<credential-secret>
      region=<region>
      [BlockStorage]
      bs-version=v3

StorageClass Configuration​

openCenter creates StorageClasses that map to Cinder volume types. The standard configuration includes both Delete and Retain reclaim policies:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ha-performance-delete
provisioner: cinder.csi.openstack.org
volumeBindingMode: Immediate
reclaimPolicy: Delete
allowVolumeExpansion: true
parameters:
  type: HA-Performance
---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ha-performance-retain
provisioner: cinder.csi.openstack.org
volumeBindingMode: Immediate
reclaimPolicy: Retain
allowVolumeExpansion: true
parameters:
  type: HA-Performance

The type parameter must match a Cinder volume type available in your OpenStack environment. Check available types with openstack volume type list.

Availability Zones​

For multi-AZ OpenStack deployments, configure topology-aware provisioning:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: cinder-az-aware
provisioner: cinder.csi.openstack.org
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
parameters:
  type: HA-Performance

WaitForFirstConsumer delays volume creation until a pod is scheduled, ensuring the Cinder volume is created in the same availability zone as the node.

Verification​

# Check CSI driver pods
kubectl get pods -n cinder-csi

# Verify StorageClasses
kubectl get storageclass | grep cinder

# Test volume provisioning
kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-cinder-pvc
spec:
  accessModes: [ReadWriteOnce]
  storageClassName: ha-performance-delete
  resources:
    requests:
      storage: 1Gi
EOF

# Check PVC is bound
kubectl get pvc test-cinder-pvc

# Verify the Cinder volume was created
# (requires OpenStack CLI access)
openstack volume list | grep pvc-

# Clean up
kubectl delete pvc test-cinder-pvc

Troubleshooting​

PVC stuck in Pending: Check CSI controller logs for Cinder API errors:

kubectl logs -n cinder-csi -l app=openstack-cinder-csi -c cinder-csi-plugin

Common causes: invalid credentials, Cinder API unreachable, volume type not found, quota exceeded.

Volume attach failures: Verify the node VM has available disk attachment slots. OpenStack limits the number of volumes per instance (typically 26).

Common Customizations​

  • Multiple volume types: Create StorageClasses for each Cinder volume type (SSD, HDD, HA-Performance).
  • Volume expansion: Enabled by default. Edit PVC spec.resources.requests.storage to expand.
  • Snapshot support: Requires external-snapshotter controller. Create VolumeSnapshotClass with driver: cinder.csi.openstack.org.
  • Default StorageClass: Annotate one class with storageclass.kubernetes.io/is-default-class: "true".