Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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
- An Azure account with an active subscription. Create an account for trial.
- A terminal environment with the Azure CLI tools installed. See Get started with the Azure CLI.
- kubectl, the Kubernetes management tool, installed in your terminal environment. See Quickstart: Deploy an Azure Kubernetes Service (AKS) cluster by using the Azure CLI.
cluster-adminpermissions to install or replace the driver and its cluster-scoped resources.- Helm 3, version 3.8.0 or later, for the recommended Helm installation method.
- Bash and
curlfor the script installation method;gitfor the script uninstall procedure. - An AKS cluster that meets the compatibility requirements.
- For static provisioning, an existing Azure Managed Lustre deployment. Dynamic provisioning creates the file system. See the Azure Managed Lustre documentation.
- Network connectivity between your AKS cluster and Azure Managed Lustre virtual network. See Plan network architecture for AKS with Azure Managed Lustre for configuration options.
- Sufficient subnet IP addresses and the inbound and outbound access described in Azure Managed Lustre network prerequisites. New private subnets need an explicit outbound connection, such as a NAT gateway.
- Access from the installation machine to
mcr.microsoft.comfor Helm, orraw.githubusercontent.comfor the script; access togithub.comfor the uninstall script's source checkout. AKS nodes need access to MCR,packages.microsoft.com, and their node image's OS package repositories. - Appropriate nodes for the controller deployment, plus eligible nodes for your Lustre workloads. For custom-tainted nodes, see the node pool guidance.
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, orUbuntu2404. Check node architecture and taints too. - No v0.6.0 node pod on an AKS node - verify that the
kubernetes.azure.com/os-sku-effectivelabel 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-loaderandazurelustrecontainer 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.comandpackages.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:
- Troubleshoot Azure Managed Lustre CSI driver extension errors
- Azure Managed Lustre troubleshooting
- Azure Lustre CSI Driver GitHub repository
Related content
- Plan network architecture for AKS with Azure Managed Lustre.
- Install the Azure Managed Lustre CSI driver
- Use dynamic provisioning with the Azure Managed Lustre CSI driver
- Use static provisioning with the Azure Managed Lustre CSI driver
- Upgrade or uninstall the Azure Managed Lustre CSI driver
- Validate CSI driver image security.
- Export data from Azure Managed Lustre to Blob Storage
- Azure Lustre CSI Driver GitHub repository