Use static provisioning with the Azure Managed Lustre CSI driver

Use static provisioning to mount an existing Azure Managed Lustre file system in AKS. Create a StorageClass with its MGS IP address and a PersistentVolumeClaim for the workload.

Prerequisites for static provisioning

Create an Azure Managed Lustre file system cluster for static provisioning

If you didn't already create your Azure Managed Lustre file system cluster, create the cluster now. For instructions, see Create an Azure Managed Lustre file system by using the Azure portal. Static provisioning requires an existing Azure Managed Lustre file system.

Install the driver for static provisioning

Complete the shared cluster preparation and driver installation steps once for either provisioning method. If the driver is already installed, follow Upgrade the CSI driver instead of installing a second copy.

Complete the driver readiness checks before creating claims or mounting volumes. Create the example PVCs and pods in the same workload namespace, selected by your current kubectl context.

Create and configure a persistent volume for static provisioning

To create a persistent volume for an existing Azure Managed Lustre file system:

  1. Copy the following configuration files from the /docs/examples/ folder in the v0.6.0 azurelustre-csi-driver source.

    • storageclass_existing_lustre.yaml
    • pvc_storageclass.yaml

    If you don't want to clone the entire repository, you can download each file individually. Open each of the following links, copy the file's contents, and then paste the contents into a local file with the same file name.

  2. In the Azure portal, open your Azure Managed Lustre file system and select Client connection. Copy the MGS IP address. In storageclass_existing_lustre.yaml, replace the entire ${EXISTING_LUSTRE_IP_ADDRESS} placeholder with that address.

  3. To create the storage class and the persistent volume claim, run the following kubectl command:

    kubectl create -f storageclass_existing_lustre.yaml
    kubectl create -f pvc_storageclass.yaml
    

Create a pod for static provisioning

Create a pod that uses the PVC to mount the Azure Managed Lustre file system. This example targets Linux amd64 nodes with the driver installed. For supported ARM64 nodes, use an ARM64-compatible image and set kubernetes.io/arch to arm64 in nodeSelector.

Create a file called pod_echo_date.yaml and copy in the following YAML:

apiVersion: v1
kind: Pod
metadata:
  name: lustre-echo-date
spec:
  nodeSelector:
    kubernetes.io/os: linux
    kubernetes.io/arch: amd64
  containers:
  - image: mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine
    name: lustre-echo-date
    command:
      - "/bin/sh"
      - "-c"
      - "while true; do echo $(date) >> /mnt/lustre/outfile; sleep 1; done"
    volumeMounts:
    - name: lustre-storage
      mountPath: /mnt/lustre
  volumes:
  - name: lustre-storage
    persistentVolumeClaim:
      claimName: pvc-lustre

Apply the pod to your AKS cluster:

kubectl apply -f pod_echo_date.yaml

Verify static provisioning

Wait for the example pod to become ready, and then check its mount:

kubectl wait --for=condition=Ready pod/lustre-echo-date --timeout=10m &&
kubectl exec -it lustre-echo-date -- df -h

You should see the Azure Managed Lustre file system mounted at /mnt/lustre.

Confirm that new timestamps continue to appear in the mounted file.

kubectl exec lustre-echo-date -- tail -f /mnt/lustre/outfile

Press Ctrl+C after you confirm that new timestamps appear.

Clean up static resources

When you finish the example, find its PV name in the VOLUME column:

kubectl get pvc pvc-lustre -o wide

Replace <pv-name> with that name, and then delete the example pod, PVC, PV, and StorageClass:

kubectl delete pod lustre-echo-date
kubectl delete pvc pvc-lustre
kubectl delete pv <pv-name>
kubectl delete storageclass sc.azurelustre.csi.azure.com

Important

This step only deletes the Kubernetes resources. The Azure Managed Lustre file system itself continues to exist and can be reused.

Troubleshooting

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

For common driver installation, node scheduling, and upgrade issues, see CSI driver troubleshooting.

Common issues for static provisioning include:

  • Network connectivity problems between AKS and Azure Managed Lustre - verify virtual network peering or subnet configuration.
  • Incorrect configuration - double-check the MGS IP address in your storage class configuration.
  • Pod scheduling issues - verify that the node's effective OS SKU is Ubuntu2204, or Ubuntu2404. Check node architecture and taints too.
  • Network setup permission issues - verify that the AKS control-plane identity has appropriate permissions on the AKS subnet. Static provisioning doesn't require the controller to create an Azure Managed Lustre file system.

For additional troubleshooting resources, see: