A Container Storage Interface (CSI) driver that provides persistent storage for Kubernetes workloads using XenServer/XCP-ng infrastructure through Xen Orchestra.

This repository hosts the CSI driver and all of its build and dependent configuration files to deploy the driver.

The Xen Orchestra CCM is required when using the default --node-metadata-source=kubernetes mode. Without it, spec.providerID is not set on Node objects, NodeGetInfo fails, and the node-driver-registrar enters CrashLoopBackOff — the CSI node plugin never registers with kubelet and no volume operations are possible on that node. Use --node-metadata-source=xo-api if you cannot run the CCM (see Topology and Placement).

• csi plugin name: csi.xenorchestra.vates.tech
• supported accessModes: ReadWriteOnce

⚠️ WARNING
This driver is currently under development. It contains unimplemented methods, shortcuts, and non-standard practices. DO NOT use in production environments.

• Static volume provisioning (use an existing VDI by UUID).
• Dynamic volume provisioning (automatically create a VDI from a StorageClass).

• XenOrchestra version 6.4+
• XCP-ng version 8.3+
• Network connectivity between Kubernetes nodes and XO API

• Documentation index – entry point to guides, migrations, and references.
• Installation guide – requirements, credentials, StorageClass, static and dynamic provisioning.
• Topology and Placement – pool boundary, live migration behaviour, CCM dependency.
• Developer guide – build, kxo helper, DevSpace, MicroK8s registry, remote debugging.
• Migration v0.2.0 to v0.3.0 – backfill other-config:kubernetes_volume_id on legacy VDIs.
• Reference: Volume Handle and Volume ID in v0.3.0 – details about stable CSI identity semantics.

An example of an install with kubectl can be found in the './deploy' folder. You may need to adjust this file to fit your actual installation; see below for more information.

• The driver depends on the CCM credentials config secret (See here).

# Create a registry credential secret for ghcr.io
kubectl -n kube-system create secret docker-registry regcred --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-pword> --docker-email=<your-email>

# Install the driver
./deploy/install-driver.sh

# Alternative: Install the driver from local repo
./deploy/install-driver.sh local

# Create a StorageClass
kubectl apply -f examples/csi-storageclass.yaml

# Install the driver
./deploy/uninstall-driver.sh

Use /var/snap/microk8s/common/var/lib/kubelet/

Use /var/lib/kubelet/

Manually attach a disk to the node VM.

Get an example

1. Create a VDI using the Xen Orchestra GUI, or any other tools such as CLI, API or Terraform.
2. Create a persistent volume (PV) and enter the UUID of the VDI created in Step 1 into the 'volumeHandle' property.
3. Use the PV with a PVC and then mount the volume inside your pod.

The driver creates a new VDI in a pool's default SR each time a PVC is bound. Two modes are supported:

Get an example

Set poolId in StorageClass.parameters. The driver always provisions into that pool. The poolId is validated against the pod's topology requirements at provision time — an error is returned if they are incompatible.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: csi-xenorchestra-sc-dynamic
provisioner: csi.xenorchestra.vates.tech
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: false
parameters:
  poolId: "<xo-pool-uuid>"

Omit poolId entirely. The driver selects the pool automatically from the accessibility_requirements passed by the Kubernetes scheduler, following the CSI spec ordering: preferred topologies first, then requisite topologies as fallback. The first pool whose default SR is accessible is used.

This mode requires volumeBindingMode: WaitForFirstConsumer and nodes labelled with topology.k8s.xenorchestra/pool_id (set by the CCM or the CSI node plugin).

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: csi-xenorchestra-sc-topology
provisioner: csi.xenorchestra.vates.tech
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: false
# no parameters block required

• Dynamic Volume Provisioning (Create VDIs from a StorageClass)
• Delete VDIs when a PV is released (reclaimPolicy: Delete)
• Read only full-support
• Volume Expansion
• Volume Snapshots

• Volume Listing
• Storage Capacity
• Volume Validation, Information, Modification
• Access modes - Add ReadWriteMany and ReadOnlyMany support

• Use with Xen Orchestra Cloud Controller Manager
• Alternative for credential management (environment variables supported)
• Check RBAC policies

• Metrics endpoint
• Switch completely to the Xen Orchestra REST API

• Complete the documentation (installation, configuration, examples...)
• Provide improved deployment methods (using kubectl, Helm or other)
• Test with other Kubernetes clusters (Talos, Rancher, etc.)

• Proper CI pipelines
• Unit test and integration tests

• Pool selection via StorageClass.parameters.poolId
• Topology-aware pool selection from accessibility_requirements (no poolId required)
• poolId validation against accessibility_requirements requisite topologies
• VOLUME_ACCESSIBILITY_CONSTRAINTS controller capability — AccessibleTopology returned in CreateVolumeResponse, topology requirements honoured in CreateVolumeRequest
• Cluster tag filtering (--cluster-tag; VDIs tagged at creation)
• Cluster Topology support
• Multi-SR support (migration...)
• Multi-pool support
• XO CCM

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.