Tutorial: Install Azure Container Storage for use with Azure Kubernetes Service

Prerequisites

• Create an Azure subscription if you don’t already have one by signing up for a free account.

• Confirm that your target region is supported by reviewing the Azure Container Storage regional availability.

• Plan your node pool configuration:

  • Use Linux as the OS type (Windows is not supported).
  • Select a 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 the latest version of the Azure CLI (2.77.0 or later), then sign in with az login. Avoid using Azure Cloud Shell (since az upgrade isn’t available), and disable conflicting extensions such as aks-preview if issues occur.

• Install the Kubernetes command-line client, kubectl. You can install it locally by running az aks install-cli.

Install the required extension

Add or upgrade to the latest version of k8s-extension by running the following command.

az extension add --upgrade --name k8s-extension

Set subscription context

Set your Azure subscription context using the az account set command. You can view the subscription IDs for all the subscriptions you have access to by running the az account list --output table command. Remember to replace <subscription-id> with your subscription ID.

az account set --subscription <subscription-id>

Create a resource group

An Azure resource group is a logical group that holds your Azure resources that you want to manage as a group. When you create a resource group, you're prompted to specify a location. This location is:

• The storage location of your resource group metadata.
• Where your resources run in Azure if you don't specify another region during resource creation.

Create a resource group using the az group create command. Replace <resource-group-name> with the name of the resource group you want to create, and replace <location> with an Azure region such as eastus, westus2, westus3, or westeurope. If you're enabling 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 an AKS cluster

Choose the scenario that matches your environment.

Option 1: Creating a new AKS cluster with Azure Container Storage enabled

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 takes 5-10 minutes. When it completes, you have an AKS cluster with Azure Container Storage installed and the components for local NVMe storage type deployed.

Option 2: Enabling Azure Container Storage on an existing AKS cluster

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 takes 5-10 minutes. When it completes, the targeted AKS cluster has Azure Container Storage installed and the components for local NVMe storage type deployed.

Prerequisites

• Create an Azure subscription if you don’t already have one by signing up for a free account.

• Verify that your target region is supported by checking the Azure Container Storage regional availability.

• Plan your node pool configuration:

  • Use Linux as the OS type (Windows is not supported).
  • Select a 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 the Azure CLI version 2.77.0 or later, then sign in with az login.

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

• Install kubectl so you can validate the cluster after deployment. If needed, run az aks install-cli to install it locally.

Set subscription context

Terraform can determine a target Azure subscription via various means:

• 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 an AKS cluster

Choose the scenario that matches your environment.

Option 1: Creating a new AKS cluster with Azure Container Storage enabled

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.x"
       }
     }
   }
   
   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"
   
     configuration_settings = {
       enable-azure-container-storage = "true"
     }
   }
   

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-10 minutes.

   terraform apply
   

Option 2: Enabling Azure Container Storage on an existing AKS cluster

If your AKS cluster already exists and you're managing 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.x"
    }
  }
}

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"

  configuration_settings = {
    enable-azure-container-storage = "true"
  }
}

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