Edit

Statically provision Azure Managed Lustre volumes for AKS

Static provisioning connects an existing Azure Managed Lustre file system to your Azure Kubernetes Service (AKS) cluster. In this example, a storage class identifies the existing file system and the driver creates a Kubernetes persistent volume (PV) for your persistent volume claim (PVC). It doesn't create a new Azure Managed Lustre file system.

To create a new file system through Kubernetes instead, see Dynamic provisioning.

Before you begin

  • Complete Install the Azure Managed Lustre CSI driver, including the verification steps for your chosen installation method. Don't install a second driver if one is already installed.
  • Have an existing Azure Managed Lustre file system with network connectivity from AKS. If needed, create a file system.
  • Copy the Lustre Management Service (MGS) IP address from the file system's Client connection page in the Azure portal.
  • Configure kubectl for your cluster. Create the example PVC and pod in the same namespace.

Create a storage class

Create a file named azure-managed-lustre-storage-class.yaml. Replace <MGS_IP_ADDRESS> with the MGS IP address of your Azure Managed Lustre file system.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: azurelustre-static
provisioner: azurelustre.csi.azure.com
parameters:
  mgs-ip-address: <MGS_IP_ADDRESS>
reclaimPolicy: Retain
volumeBindingMode: Immediate
mountOptions:
  - noatime
  - flock

Apply the storage class:

kubectl apply -f azure-managed-lustre-storage-class.yaml

Create a persistent volume claim

Create a file named azure-managed-lustre-pvc.yaml:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: azurelustre-pvc
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: azurelustre-static
  resources:
    requests:
      storage: 4Ti

The requested capacity doesn't resize the existing Azure Managed Lustre file system.

Apply the claim and check its status:

kubectl apply -f azure-managed-lustre-pvc.yaml
kubectl get pvc azurelustre-pvc

Wait until the claim reaches the Bound state before continuing. To inspect provisioning events, run kubectl describe pvc azurelustre-pvc.

Mount and verify the volume

Create a file named azure-managed-lustre-pod.yaml. Run the example on a supported node pool with the driver installed.

apiVersion: v1
kind: Pod
metadata:
  name: azurelustre-test
spec:
  containers:
    - name: writer
      image: ubuntu:24.04
      command:
        - /bin/sh
        - -c
        - while true; do date >> /mnt/lustre/outfile; sleep 5; done
      volumeMounts:
        - name: lustre
          mountPath: /mnt/lustre
  volumes:
    - name: lustre
      persistentVolumeClaim:
        claimName: azurelustre-pvc

Apply the pod and wait for it to become ready:

kubectl apply -f azure-managed-lustre-pod.yaml
kubectl wait --for=condition=Ready pod/azurelustre-test --timeout=10m

Verify that the file system is mounted and the pod is writing to it:

kubectl exec azurelustre-test -- df -h /mnt/lustre
kubectl exec azurelustre-test -- tail /mnt/lustre/outfile

Clean up the example

Find the PV name in the claim's VOLUME column before deleting the claim:

kubectl get pvc azurelustre-pvc -o wide

Stop the test pod and let its volume unmount. Then delete the claim, its retained PV, and the storage class. Replace <PV_NAME> with the name you recorded:

kubectl delete pod azurelustre-test
kubectl delete pvc azurelustre-pvc
kubectl delete pv <PV_NAME>
kubectl delete storageclass azurelustre-static

The storage class uses Retain, so deleting the claim alone leaves the PV behind. These commands remove the example's Kubernetes resources, not the Azure Managed Lustre file system or its data. They don't uninstall the driver.

Troubleshooting

  • Network connectivity problems: Verify virtual network peering or subnet configuration using the network planning guide.
  • Incorrect configuration: Check the MGS IP address in the storage class.
  • Pod scheduling issues: Confirm that the workload uses a supported node pool and review the pod events.
  • Network setup permission issues: Verify that the AKS control-plane identity has appropriate permissions on the AKS subnet. Static provisioning doesn't require the CSI controller to create an Azure Managed Lustre file system.

For common driver issues, see CSI driver troubleshooting. For version-specific diagnostics, see the upstream v0.6.0 troubleshooting guide. For file system deployment issues, see Azure Managed Lustre troubleshooting.

Next steps

  • Last updated on