Edit

Full caching mode for ephemeral OS disks in Azure Kubernetes Service (AKS) (preview)

Ephemeral OS disks with full caching enhance the standard ephemeral OS disk by fully caching the OS disk onto the local disk. This feature improves the resiliency of general-purpose virtual machines (VMs) and virtual machine scale sets by ensuring the OS disk remains available even during storage disruptions.

This article provides guidance on how to enable full caching for ephemeral OS disks in AKS.

Important

AKS preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available," and they're excluded from the service-level agreements and limited warranty. AKS previews are partially covered by customer support on a best-effort basis. As such, these features aren't meant for production use. For more information, see the following support articles:

How full caching works

When you create a VM with full caching enabled, the following actions occur:

  • The temporary disk size is reduced by two times the OS disk size, and the freed space is used to create the OS disk.
  • The OS disk is cached in the background after the VM boots up. This caching process ensures no impact on VM creation times.

Limitations

  • You can only enable full-cache ephemeral OS disks during node pool creation; you can't update existing node pools to use full caching.
  • The feature requires an ephemeral OS disk configuration.
  • You can access the feature only through preview AKS API versions and tooling.
  • Full-cache ephemeral OS disks are designed for stateless workloads; they're not recommended for stateful workloads.
  • The local disk size must be greater than (2x the OS disk size + 1 GiB) to support full caching.
  • All VM SKUs are supported except for 2-core and 4-core VMs.

Prerequisites

  • Azure CLI version 2.76.0 or later. Check your version using the az --version command. To install or update the Azure CLI, see Install the Azure CLI.
  • AKS REST API version 2026-04-02-preview or later.
  • The aks-preview extension installed and updated to version 21.0.0.b2 or later. To install or update the aks-preview extension, see Install the aks-preview extension.
  • The FullCachePreview feature flag registered on your subscription. To register the feature flag, see Register the FullCachePreview feature flag.

Install the aks-preview extension

Install the aks-preview extension using the az extension add command.

az extension add --name aks-preview

Update the aks-preview extension to the latest version using the az extension update command.

az extension update --name aks-preview

Register the FullCachePreview feature flag

  1. Register the FullCachePreview feature flag using the az feature register command.

    az feature register --namespace Microsoft.ContainerService --name FullCachePreview

  2. Check the registration status using the az feature show command. The registration process can take several minutes to complete.

    az feature show --namespace Microsoft.ContainerService --name FullCachePreview

  3. After the feature flag is registered, refresh the provider registration using the az provider register command.

    az provider register --namespace Microsoft.ContainerService

Create a node pool with full-cache ephemeral OS disks

Create a new node pool with full caching enabled for ephemeral OS disks using the az aks nodepool add command with the --enable-osdisk-full-caching flag.

Note

You can also use the abbreviated flag --enable-osdisk-fc to enable full caching.

# Set environment variables
export RESOURCE_GROUP=<resource-group>
export CLUSTER_NAME=<cluster-name>
export NODE_POOL_NAME=<node-pool-name>

# Create a new node pool with full caching enabled for ephemeral OS disks
az aks nodepool add \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --name $NODE_POOL_NAME \
    --enable-osdisk-full-caching

Related content

To learn more about storage options for AKS, see the following articles:

  • Last updated on