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 ephemeralDisk driver, and creates a default storage class. You can install and use both local NVMe and Elastic SAN by providing comma-separated values 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. You can install and use both local NVMe and Elastic SAN by providing comma-separated values such as ephemeralDisk,elasticSan.

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>

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.