Install Azure Container Storage for use with Azure Kubernetes Service

Prerequisites

• If you don't have an Azure subscription, create a free account before you begin.

• This article requires Azure CLI version v2.83.0 or later. For more information, see How to install the Azure CLI. Disable extensions such as aks-preview if issues occur. Install or update extensions as needed:

  • az extension add --upgrade --name k8s-extension
  • az extension add --upgrade --name elastic-san (Elastic SAN only)

• You need the Kubernetes command-line client, kubectl. It's already installed if you're using Azure Cloud Shell. You can install it locally by running the az aks install-cli command.

• Check if your target region is supported in Azure Container Storage regions.

• Plan your node pool configuration:

  • Use Linux as the OS type (Windows isn't supported).
  • Select a virtual machine (VM) SKU that supports local NVMe data disks if you plan to use the local NVMe storage type, such as storage-optimized or GPU-accelerated VMs.
  • For existing clusters, ensure node pools already use a supported VM SKU before enabling Azure Container Storage.

• If you use Elastic SAN for the first time in the subscription, run this one-time registration command:

  az provider register --namespace Microsoft.ElasticSan
  

Set subscription context

Set your Azure subscription context using the az account set command. You can view subscription IDs by running az account list --output table. Replace <subscription-id> with your subscription ID.

az account set --subscription <subscription-id>

Create a resource group

An Azure resource group is a logical container for resources. When you create a resource group, you specify a location. That location stores resource group metadata and serves as the default region for resources you create without an explicit region.

Create a resource group using az group create. Replace <resource-group-name> with your resource group name and <location> with an Azure region such as eastus, westus2, westus3, or westeurope. If you enable Azure Container Storage on an existing AKS cluster, use the resource group that already hosts the cluster.

az group create --name <resource-group-name> --location <location>

If the resource group is created successfully, you see output similar to this example:

{
  "id": "/subscriptions/<guid>/resourceGroups/myContainerStorageRG",
  "location": "eastus",
  "managedBy": null,
  "name": "myContainerStorageRG",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null
}

Install Azure Container Storage on a new AKS cluster

Choose the scenario that matches your environment.

Installer-only installation

Run the following command to create a new AKS cluster and install Azure Container Storage. Replace <cluster-name> and <resource-group> with your own values, and specify which VM type you want to use.

az aks create -n <cluster-name> -g <resource-group> --node-vm-size Standard_L8s_v3 --enable-azure-container-storage --generate-ssh-keys

The deployment can take up to 5 minutes. CSI driver installation is deferred until you create a storage class or enable a storage type later.

Follow the instructions for creating a local NVMe storage class or Elastic SAN storage class.

Installer + storage type installation

Run the following command to create a new AKS cluster and install Azure Container Storage. Replace <cluster-name> and <resource-group> with your own values, and specify which VM type you want to use.

az aks create -n <cluster-name> -g <resource-group> --node-vm-size Standard_L8s_v3 --enable-azure-container-storage ephemeralDisk --generate-ssh-keys

This command installs the installer, deploys the local NVMe CSI driver, and creates a default storage class called local-csi. You can install and use both local NVMe and Elastic SAN by providing a list such as ephemeralDisk elasticSan.

Install Azure Container Storage on an existing AKS cluster

Installer-only installation

Run the following command to enable Azure Container Storage on an existing AKS cluster. Replace <cluster-name> and <resource-group> with your own values.

az aks update -n <cluster-name> -g <resource-group> --enable-azure-container-storage

The deployment can take up to 5 minutes. When it completes, the cluster has the Azure Container Storage installer component installed. CSI driver installation is deferred until you create a storage class or enable a storage type later. Follow the instructions for creating a local NVMe storage class or Elastic SAN storage class.

Installer + storage type installation

Run the following command to enable Azure Container Storage on an existing AKS cluster. Replace <cluster-name> and <resource-group> with your own values, and specify which storage type you want to use.

az aks update -n <cluster-name> -g <resource-group> --enable-azure-container-storage elasticSan

This command installs the installer, deploys the Elastic SAN CSI driver, and creates a default storage class called azuresan-csi. You can install and use both local NVMe and Elastic SAN by providing a list such as ephemeralDisk elasticSan.

Install distributed accelerator for cloud storage (preview)

Enable distributed accelerator for cloud storage on an existing AKS cluster by using the distributedAccelerator value. The uppercase A is required. The extension installs on the AKS managed-cluster resource; you don't need to Arc-connect the cluster.

Use aks-preview version 22.0.0b9 or later. Install or upgrade the extension, verify its version, and install or upgrade connectedk8s and k8s-extension to manage and inspect the DACS extension:

az extension add --name aks-preview --upgrade --yes
az extension show --name aks-preview --query version --output tsv
az extension add --name connectedk8s --upgrade --yes
az extension add --name k8s-extension --upgrade --yes

Before enabling DACS, select a Linux node pool with local NVMe data disks dedicated to the cache. Apply the dacs.azure.com/processing-unit=cpu label through the node-pool configuration, preserving any existing custom labels. Follow Verify the cache node pool.

Run the following command, replacing <cluster-name> and <resource-group> with your values:

az aks update \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --enable-azure-container-storage distributedAccelerator

This command installs the distributedaccelerator extension, the DACS controller and NVMe prerequisite DaemonSet in kube-system, and the caches.storage.azure.com custom resource definition (CRD). You don't install a separate prerequisite chart or manage the extension's Helm release yourself. It doesn't create a StorageClass or provision a Cache resource and cache-server pods by default. Successful extension installation doesn't by itself mean that a cache is ready for application traffic.

Pass distributedAccelerator on its own in this command rather than combining it with the persistent-volume storage options shown earlier. Before provisioning cache servers, verify that the managed prerequisites are ready on every labeled cache node. For the cache setup and application workflow, see Get started with distributed accelerator for cloud storage on AKS.

To remove DACS, follow Remove distributed accelerator for cloud storage. Delete Cache resources while the controller is running, then disable DACS. Disablement removes the controller and managed prerequisite DaemonSet; don't remove those prerequisites separately.

Prerequisites

• If you don't have an Azure subscription, create a free account before you begin.

• This article requires Azure CLI version v2.83.0 or later. For more information, see How to install the Azure CLI. Disable extensions such as aks-preview if issues occur. Install or update extensions as needed:

  • az extension add --upgrade --name k8s-extension
  • az extension add --upgrade --name elastic-san (Elastic SAN only)

• You need the Kubernetes command-line client, kubectl. It's already installed if you're using Azure Cloud Shell. You can install it locally by running the az aks install-cli command.

• Check if your target region is supported in Azure Container Storage regions.

• Plan your node pool configuration:

  • Use Linux as the OS type (Windows isn't supported).
  • Select a virtual machine (VM) SKU that supports local NVMe data disks, such as storage-optimized or GPU-accelerated VMs.
  • For existing clusters, ensure node pools already use a supported VM SKU before enabling Azure Container Storage.

• Install Terraform version 1.5 or later and confirm the installation with terraform version. Terraform can reuse your Azure CLI authentication.

• If you use Elastic SAN for the first time in the subscription, run this one-time registration command:

  az provider register --namespace Microsoft.ElasticSan
  

Set subscription context

Terraform can determine a target Azure subscription via multiple methods:

• subscription_id in the provider block
• ARM_SUBSCRIPTION_ID environment variable
• Azure CLI default subscription
• Managed identity (when running in Azure)

For local use, set the Azure CLI context:

az account set --subscription <subscription-id>

If you deploy with Terraform for the first time in the subscription, run this one-time registration command:

az provider register --namespace Microsoft.KubernetesConfiguration

# Wait for registration to complete (can take a few minutes)
az provider show --namespace Microsoft.KubernetesConfiguration --query "registrationState" -o tsv

Install Azure Container Storage on a new AKS cluster

1. In an empty working directory, create a main.tf file with the following minimal configuration of an AKS cluster. Update the resource names, locations, and VM sizes to meet your requirements.

   terraform {
     required_version = ">= 1.5.0"
     required_providers {
       azurerm = {
         source  = "hashicorp/azurerm"
         version = "~> 4.0"
       }
     }
   }
   
   provider "azurerm" {
     features {}
   }
   
   resource "azurerm_resource_group" "rg" {
     name     = "demo-aks-rg"
     location = "eastus"
   }
   
   resource "azurerm_kubernetes_cluster" "aks" {
     name                = "demo-aks-cluster"
     dns_prefix          = "demo-aks"
     location            = azurerm_resource_group.rg.location
     resource_group_name = azurerm_resource_group.rg.name
   
     default_node_pool {
       name       = "systempool"
       vm_size    = "Standard_L8s_v3"
       node_count = 3
     }
   
     identity {
       type = "SystemAssigned"
     }
   }
   
   resource "azurerm_kubernetes_cluster_extension" "container_storage" {
     # NOTE: the `name` parameter must be "acstor" for Azure CLI compatibility
     name           = "acstor"
     cluster_id     = azurerm_kubernetes_cluster.aks.id
     extension_type = "microsoft.azurecontainerstoragev2"
   }
   

2. Initialize the working directory to download the AzureRM provider.

   terraform init
   

3. Review the planned changes.

   terraform plan
   

4. Apply the configuration to create the resource group, AKS cluster, and Azure Container Storage extension. Deployment typically takes 5 minutes.

   terraform apply
   

When it completes, the cluster has the Azure Container Storage installer component installed. CSI driver installation is deferred until you create a storage class. Follow the instructions for creating a local NVMe storage class or Elastic SAN storage class.

Install Azure Container Storage on an existing AKS cluster

If your AKS cluster already exists and you manage it outside of Terraform, you can still enable Azure Container Storage by authoring only the extension resource. Use a data source to look up the cluster ID.

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

provider "azurerm" {
  features {}
}

data "azurerm_kubernetes_cluster" "existing" {
  name                = "existing-aks"
  resource_group_name = "existing-aks-rg"
}

resource "azurerm_kubernetes_cluster_extension" "container_storage" {
  # NOTE: the `name` parameter must be "acstor" for Azure CLI compatibility
  name           = "acstor"
  cluster_id     = data.azurerm_kubernetes_cluster.existing.id
  extension_type = "microsoft.azurecontainerstoragev2"
}

Run terraform init (if this is a new working directory) followed by terraform apply to install Azure Container Storage on the targeted cluster. Deployment typically takes 5 minutes.

When it completes, the cluster has the Azure Container Storage installer component installed. CSI driver installation is deferred until you create a storage class. Follow the instructions for creating a local NVMe storage class or Elastic SAN storage class.