Use the Azure Managed Lustre CSI driver with Azure Kubernetes Service

By using the Azure Lustre CSI Driver for Kubernetes, you can use Azure Managed Lustre as persistent storage for workloads running in Azure Kubernetes Service (AKS). This driver is based on the Container Storage Interface (CSI) specification.

Supported Kubernetes and AKS versions

The Azure Lustre CSI Driver for Kubernetes is compatible with AKS. Other Kubernetes installations aren't currently supported.

Version 0.6.0 requires Kubernetes 1.29 or later because the node plugin uses a native sidecar container.

Important

Version 0.6.0 provides images for Ubuntu 22.04 (Ubuntu2204), and Ubuntu 24.04 (Ubuntu2404) node pools. Windows node pools aren't supported.

The Azure Lustre CSI Driver for Kubernetes is compatible with Azure Managed Lustre. Other Lustre installations aren't currently supported.

Azure Lustre CSI Driver versions

These articles document the v0.6.0 release. Use a versioned release instead of the main branch for production deployments.

Version 0.6.0 uses separate node images for Ubuntu 22.04 (Jammy), and Ubuntu 24.04 (Noble). Both the Helm chart and script installer deploy the two node DaemonSets. Kubernetes schedules the appropriate driver pod by using the kubernetes.azure.com/os-sku-effective node label. Jammy node image supports amd64; Noble supports amd64 and arm64.

The controller uses the Noble image, which supports amd64 and arm64.

Driver version Image AKS node OS SKU Supported k8s version Lustre client version Dynamic Provisioning
v0.6.0 (Jammy) mcr.microsoft.com/oss/v2/kubernetes-csi/azurelustre-csi:v0.6.0-jammy Ubuntu2204 1.29+ 2.15.8 ✅
v0.6.0 (Noble) mcr.microsoft.com/oss/v2/kubernetes-csi/azurelustre-csi:v0.6.0-noble Ubuntu2404 1.29+ 2.17.0 ✅
v0.4.0 (Jammy) mcr.microsoft.com/oss/v2/kubernetes-csi/azurelustre-csi:v0.4.0-jammy Ubuntu2204; 1.21+ 2.15.7 ✅
v0.4.0 (Noble) mcr.microsoft.com/oss/v2/kubernetes-csi/azurelustre-csi:v0.4.0-noble Ubuntu2404 1.21+ 2.16.1 ✅
v0.3.1 mcr.microsoft.com/oss/v2/kubernetes-csi/azurelustre-csi:v0.3.1 Ubuntu Linux 1.21+ 2.15.7 ✅
v0.3.0 mcr.microsoft.com/oss/v2/kubernetes-csi/azurelustre-csi:v0.3.0 Ubuntu Linux 1.21+ 2.15.5 ✅
v0.2.0 mcr.microsoft.com/oss/v2/kubernetes-csi/azurelustre-csi:v0.2.0 Ubuntu Linux 1.21+ 2.15.5 ❌
v0.1.18 mcr.microsoft.com/oss/kubernetes-csi/azurelustre-csi:v0.1.18 Ubuntu Linux 1.21+ 2.15.5 ❌
v0.1.17 mcr.microsoft.com/oss/kubernetes-csi/azurelustre-csi:v0.1.17 Ubuntu Linux 1.21+ 2.15.5 ❌
v0.1.15 mcr.microsoft.com/oss/kubernetes-csi/azurelustre-csi:v0.1.15 Ubuntu Linux 1.21+ 2.15.4 ❌
v0.1.14 mcr.microsoft.com/oss/kubernetes-csi/azurelustre-csi:v0.1.14 Ubuntu Linux 1.21+ 2.15.3 ❌
v0.1.13 mcr.microsoft.com/oss/kubernetes-csi/azurelustre-csi:v0.1.13 Ubuntu Linux 1.21+ 2.15.4 ❌
v0.1.12 mcr.microsoft.com/oss/kubernetes-csi/azurelustre-csi:v0.1.12 Ubuntu Linux 1.21+ 2.15.3 ❌
v0.1.11 mcr.microsoft.com/oss/kubernetes-csi/azurelustre-csi:v0.1.11 Ubuntu Linux 1.21+ 2.15.1 ❌
v0.1.10 mcr.microsoft.com/oss/kubernetes-csi/azurelustre-csi:v0.1.10 Ubuntu Linux 1.21+ 2.15.2 ❌

For a complete list of all driver releases and their changelog, see the Azure Lustre CSI driver releases page.

Note

Version 0.6.0 requires AKS node pools that report the kubernetes.azure.com/os-sku-effective label, in addition to the Kubernetes version requirement shown in the table.

Prerequisites

Provisioning methods

The Azure Lustre CSI Driver supports two provisioning methods:

Dynamic provisioning (available in v0.3.0+)

Dynamic provisioning allows the CSI driver to automatically create Azure Managed Lustre file systems on demand when persistent volume claims are created.

Note

Dynamic provisioning is available starting with Azure Lustre CSI Driver version 0.3.0. For more information, see the v0.3.0 release notes.

For full step-by-step instructions, see Use dynamic provisioning with the Azure Managed Lustre CSI driver.

Static provisioning

Static provisioning uses an existing Azure Managed Lustre file system. This method involves:

  • Creating storage classes that reference existing Lustre clusters
  • Specifying the Lustre MGS IP address
  • Suitable for scenarios where you have preexisting Lustre infrastructure

For full step-by-step instructions, see Use static provisioning with the Azure Managed Lustre CSI driver.

Install the CSI driver

Install the driver once for either provisioning method. For shared cluster preparation, Helm or script installation, and readiness checks, see Install the Azure Managed Lustre CSI driver.

Upgrade the CSI driver

For maintenance planning, workload and mount preflight checks, installation, verification, and recovery, see Upgrade or uninstall the Azure Managed Lustre CSI driver.

Uninstall the driver

Stop every workload that uses Lustre and confirm that no Lustre mounts remain before removing the driver. For the Helm and script uninstall procedures, see Uninstall the driver.

Troubleshooting

To troubleshoot issues with the Azure Lustre CSI Driver, see the v0.6.0 CSI driver troubleshooting guide in the GitHub repository.

Common issues include:

  • Network connectivity problems - verify virtual network peering or subnet configuration between AKS and Azure Managed Lustre.
  • Incorrect configuration - verify the MGS IP address in your storage class.
  • Pod scheduling issues - verify that the node's effective OS SKU is Ubuntu2204, or Ubuntu2404. Check node architecture and taints too.
  • No v0.6.0 node pod on an AKS node - verify that the kubernetes.azure.com/os-sku-effective label is present and matched by the Jammy, or Noble DaemonSet.
  • A DaemonSet has zero desired pods - this condition is expected if no eligible nodes match that flavor. Confirm that every intended workload node has a CSI node pod.
  • Upgrade rollout timeout - inspect the DaemonSet status, affected pod events, and both lustre-loader and azurelustre container logs before retrying.
  • Ready pods using an old Lustre client - compare the loaded kernel module version with the expected version in Verify the upgrade.
  • Helm ownership errors - follow the uninstall/reinstall procedure instead of installing over existing script-managed resources.
  • Image pull or Lustre client installation failures - verify node egress to mcr.microsoft.com and packages.microsoft.com.
  • Permission issues during dynamic provisioning - check the identity that the CSI controller uses against the dynamic provisioning permission requirements.

For provisioning-specific issues, see Dynamic provisioning troubleshooting or Static provisioning troubleshooting.

For additional troubleshooting resources, see: