Skip to content

README.md

Latest commit

 

History

History
248 lines (187 loc) · 10.3 KB

README.md

File metadata and controls

248 lines (187 loc) · 10.3 KB
Raw

XenOrchestra CSI Driver for Kubernetes

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. 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 (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.

Features

  • Static volume provisioning (use an existing VDI by UUID).
  • Dynamic volume provisioning (automatically create a VDI from a StorageClass).
  • Local storage support: pin VDIs to a host-local SR with automatic migration on reschedule.
  • Volume migration via VolumeAttributesClass: create a VDI directly in a specific Storage Repository (SR), or migrate it after creation within the same pool.

Prerequisite

  • XenOrchestra version 6.4+
  • XCP-ng version 8.3+
  • Network connectivity between the CSI controller pod and the XO API

Documentation

Version migrations

When upgrading between versions, some releases require or recommend metadata changes to existing VDIs. Each guide is self-contained and includes rollback instructions.

  • v0.2.0 to v0.3.0 – required — backfill other-config:kubernetes_volume_id on legacy VDIs.
  • v0.3.0 to v0.4.0 – required — migrate VDI metadata from other_config to tags (mandatory for existing v0.3.0 dynamic volumes).

Limitations

Do not rename CSI-managed VDIs in Xen Orchestra

The driver uses the VDI name_label as a fallback lookup when the k8s:volumeId:<volumeId> tag is missing (e.g. after tag erasure). The name_label is set at creation time to <prefix><volumeId>-<volumeName>.

Renaming a VDI in Xen Orchestra breaks this fallback. If the tag has also been erased, the driver will no longer be able to locate the VDI and volume operations (DeleteVolume, ControllerUnpublishVolume) will fail and the VDI will be considered deleted.

CSI-managed VDIs are identifiable by:

  • the k8s:volumeId:<volumeId> tag,
  • the csi- prefix in their name_label (or the prefix set with the flag --vdi-name-prefix),
  • the name_description field set to VDI managed by the Kubernetes CSI; pv-name=<pv-name>.

See VDI Lookup and Identification for full details and manual recovery steps.

Install driver on a Kubernetes cluster

Install the driver with Helm, reusing the Xen Orchestra CCM credentials Secret:

helm upgrade --install xenorchestra-csi-driver \
  --namespace kube-system \
  --set existingConfigSecret=xenorchestra-cloud-controller-manager \
  oci://ghcr.io/vatesfr/charts/xenorchestra-csi-driver

See the installation guide for requirements, credentials, MicroK8s configuration, StorageClasses, component toggles, installation tests, and uninstallation.

Driver parameters

Static provisioning

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.
Name Meaning Example Required Default
volumeHandle Disk identifier, it must be the VDI UUID b05f63f2-692a-4833-9453-980a73f9f27f Yes N/A
driver Driver to use for the PV it must be csi.xenorchestra.vates.tech Yes N/A

Dynamic provisioning

The driver creates a new VDI each time a PVC is bound. Three selection modes are supported, in order of precedence: VAC SR > explicit poolId > topology-aware.

Get an example

VAC SR selection (highest precedence, Kubernetes ≥ 1.31)

Set storageRepositoryId in a VolumeAttributesClass. The driver creates the VDI directly in the specified SR. The SR is validated: it must exist, and belong to the pool selected by poolId or topology. If storageType is set in the StorageClass, the SR's shared/local type must match.

When using VAC SR selection, the storageType: local automatic local-SR override is not applied — the VDI lands exactly where the VAC points.

apiVersion: storage.k8s.io/v1beta1
kind: VolumeAttributesClass
metadata:
  name: csi-xo-specific-sr
driver: csi.xenorchestra.vates.tech
parameters:
  storageRepositoryId: "<sr-uuid>"
Name Meaning Example Required
storageRepositoryId UUID of the target Storage Repository. The VDI is created directly in this SR. aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee Yes

Any other parameter key in the VolumeAttributesClass is rejected with InvalidArgument — the driver only accepts the keys listed above.

Explicit pool (simple)

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

Name Meaning Example Required Default
poolId UUID of the Xen Orchestra pool. The VDI is created on the pool's default SR. aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee No —
storageType Storage placement: shared (pool default SR) or local (host-local SR, migrated at attach time). local No shared 
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>"

Topology-aware (no poolId)

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

🚀 TODO / Roadmap

Core CSI Operations

  • 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

Storage Management

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

Security & Configuration

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

Performance & Monitoring

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

Other

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

CI & Testing

  • Proper CI pipelines
  • Unit test and integration tests

XO related

  • 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...)
  • Local SR support (storageType: local — VDI migration to host-local SR in ControllerPublishVolume)
  • Multi-pool support
  • XO CCM

Contributing

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.

License

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.