AzCLI support for Ephemeral OS disk with full caching during VM/VMSS create/update

[viveksingla08]

Preconditions

• [x] No need to upgrade Python SDK or the Python SDK is ready.

Related command

We are launching a new feature Ephemeral OS disk with full caching wiht GA target Mar'26. There are many 1P customers like AKS Underlay, PostGreSQL, App Gateway etc. who are interested in the offering. Change required - To add additional field in AzCLI/PS

AzCLI az vm create
--resource-group vivek-rg --name myVM --image Win2022AzureEditionCore --ephemeral-os-disk true --ephemeral-os-disk-placement ResourceDisk --ephemeral-os-disk-enable-full-caching true/false <- New field introduced --admin-username XXX --admin-password XXX --generate-ssh-keys --size Standard_B16ms --storage-sku StandardSSD_LRS

az vmss update --ephemeral-os-disk true --ephemeral-os-disk-placement ResourceDisk --ephemeral-os-disk-enable-full-caching true/false <- New field introduced

Corresponding Arm template: "osDisk": { "diffDiskSettings": { "option": "Local", "placement": "ResourceDisk", “enableFullCaching ":“True“ ß New field introduced }, "caching": "ReadOnly", "createOption": "FromImage", "managedDisk": { "storageAccountType": "StandardSSD_LRS" } }ar'26

Resource Provider

Microsoft.Compute/virtualmachines

Description of Feature or Work Requested

Microsoft announces the enhanced ephemeral OS disk feature for Azure Virtual Machines (VMs), designed to optimize performance and deployment efficiency for stateless workloads. Ephemeral OS Disks are stored directly on the VM’s local storage, eliminating reliance on remote Azure Storage. This approach delivers lower read/write latency, faster VM reimaging, and accelerated deployment times, making it ideal for applications that prioritize agility and responsiveness. Ephemeral OS Disk is available in two caching modes, catering to diverse workload needs:

• Partial caching (Default): Partial caching splits OS disk between a diff disk on local storage and a base disk in managed disks. All writes occur on the diff disk, while the base disk serves read operations for original files. Optimized for cloud-native and stateless applications, partial ephemeral OS disk balances performance with efficiency. All existing ephemeral VMs have been created in partial mode.

• Full caching (new feature): Full caching caches the entire OS disk on local storage, completely removing dependency on remote storage in steady state. Ideal for IO-sensitive stateless workloads, full caching enhances both performance and reliability by eliminating remote read/write latency. Workloads such as quorum-based databases, data analytics, and real-time processing, benefit from this feature. However, full caching requires 2x the OS disk space to store the complete image locally.

Key Advantages of ephemeral OS disk with full caching mode:

• High Performance: Provides extremely high-performance OS disks with consistently fast response times.
• Reliability: Ensures high availability, making it suitable for critical workloads. By leveraging ephemeral OS disks, Azure customers can achieve faster deployments, reduced latency, and enhanced performance, ensuring their applications remain highly responsive and scalable.

Minimum API Version Required

2025-11-01

Swagger PR link / SDK link

https://github.com/Azure/azure-rest-api-specs/pull/37861

Request Example

No response

Target Date

2026-03-31

PM Contact

viveksingla

Engineer Contact

aygaur, sgundu;

Additional context

No response

[yonzhan]

Thank you for opening this issue, we will look into it.

[github-actions[bot]]

Here are some similar issues that might help you. Please check if they can solve your problem.

• #19751
• #25987

---

Possible solution (Extracted from existing issue, might be incorrect; please verify carefully)

Solution 1:

Here is the swagger link PR: https://github.com/Azure/azure-rest-api-specs/pull/8847 (As I mentioned this one is merged into swagger long time back in 2019-12-01 API version) So I am sure that SDK python should have these changes.

Updates should be like For az vmss create, az vm create cmds, currently we have param called [--ephemeral-os-disk {false, true}], we should have another param called that goes together with this is [--ephemeral-os-disk-placement {CacheDisk,ResourceDisk}] which customer can set when customer selected the ephemeral-os-disk value as true.

Reference:

• https://github.com/azure/azure-cli/issues/19751#issuecomment-934575349

Solution 2:

We will release at 11/2~ And this PR can be closed automated after the related PR (https://github.com/Azure/azure-cli/pull/19886) finish review and merge into our CLI repo, can you give a quick review about the related PR.

Reference:

• https://github.com/azure/azure-cli/issues/19751#issuecomment-946303828

Powered by issue-sentinel

[zhoxing-ms]

@viveksingla08 Since our sprint is already fully planned, can we postpone the release time of this feature to 11-18?

[william051200]

Hi @viveksingla08,

As the newer API version that supports the enableFullCaching parameter is not available yet, we are unable to test the CLI command development on our side.

Here are the error details for confirmation:

• From az vm list:

  (InvalidResourceType) The resource type 'virtualMachines' could not be found in the namespace 'Microsoft.Compute' for api version '2025-11-01'.  
  Supported api-versions: 2015-05-01-preview, …, 2025-04-01
  

• From az vm create --ephemeral-full-caching (newly developed parameter for az vm create):

  {"status":"Failed","error":{"code":"DeploymentFailed","details":[{"code":"BadRequest","target":"vm.properties.storageProfile.osDisk.diffDiskSettings.enableFullCaching","message":"Could not find member 'enableFullCaching' on object of type 'DiffDiskSettings'."}]}}
  

These errors indicate that the Compute RP does not yet support enableFullCaching and the latest recognized API version is 2025-04-01.

Please confirm when this feature will be available so we can resume development and validate the new implementation.

cc @yanzhudd

Thank you!