Updates and fixes for Azure.VM.DiskCaching #3673 (#3725)

Author: BernieWhite

docs/changelog.md

@@ -51,8 +51,14 @@ What's changed since v1.47.0:
   - Azure Kubernetes Service:
     - Updated `Azure.AKS.Version` to use `1.33.7` as the minimum version by @BernieWhite.
       [#3708](https://github.com/Azure/PSRule.Rules.Azure/issues/3708)
-- Improved documentation for expansion internals with a high-level flow diagram and code references by @BernieWhite.
-  [#3715](https://github.com/Azure/PSRule.Rules.Azure/issues/3715)
+  - Virtual Machine:
+    - Updated `Azure.VM.DiskCaching` to check for `ReadWrite` caching on OS disks instead only by @BernieWhite.
+      [#3673](https://github.com/Azure/PSRule.Rules.Azure/issues/3673)
+      - Renamed the rule from `Azure.VM.DiskCaching` to `Azure.VM.OSDiskCache` to reflect updated scope.
+      - Updates to provide more complete documentation.
+- Engineering
+  - Improved documentation for expansion internals with a high-level flow diagram and code references by @BernieWhite.
+    [#3715](https://github.com/Azure/PSRule.Rules.Azure/issues/3715)
 
 ## v1.47.0
 

docs/en/rules/Azure.VM.DiskCaching.md

@@ -0,0 +1,161 @@
+---
+reviewed: 2026-03-25
+severity: Important
+pillar: Performance Efficiency
+category: PE:08 Data performance
+resource: Virtual Machine
+resourceType: Microsoft.Compute/virtualMachines
+online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.VM.OSDiskCache/
+ms-content-id: d28da16e-4639-466f-95e5-4ab6bf61aec7
+---
+
+# Virtual Machine OS disk read write caching is not enabled
+
+## SYNOPSIS
+
+Operating system (OS) disk read/ write caching can improve virtual machines (VMs) performance.
+
+## DESCRIPTION
+
+Azure Virtual Machines (VMs) support caching for OS disks to improve performance.
+The caching mode can be set to `ReadOnly`, `ReadWrite`, or `None`.
+By default, the OS disks have `ReadWrite` caching enabled.
+
+The appropriate caching mode depends on the specific workload configuration and performance requirements.
+For most workloads `ReadWrite` caching provides improved performance and acceptable integrity of operating system files.
+This is because operating system files and processes typically infrequently change and support flushing writes during changes.
+
+In cases where workload data files are stored on the OS disk, `ReadWrite` caching may be inappropriate.
+When designing high performance workloads, separate workload data files from the OS disk and use data disks.
+
+## RECOMMENDATION
+
+Consider enabling `ReadWrite` caching for OS disks to improve OS storage performance.
+
+## EXAMPLES
+
+### Configure with Bicep
+
+To deploy VMs that pass this rule:
+
+- Set the `properties.storageProfile.osDisk.caching` property to `ReadWrite`.
+
+For example:
+
+```bicep
+resource linux 'Microsoft.Compute/virtualMachines@2025-04-01' = {
+  name: name
+  location: location
+  identity: {
+    type: 'SystemAssigned'
+  }
+  properties: {
+    hardwareProfile: {
+      vmSize: 'Standard_D8ds_v6'
+    }
+    osProfile: {
+      computerName: name
+      adminUsername: adminUsername
+      linuxConfiguration: {
+        provisionVMAgent: true
+        disablePasswordAuthentication: true
+      }
+    }
+    storageProfile: {
+      imageReference: {
+        publisher: 'MicrosoftCblMariner'
+        offer: 'azure-linux-3'
+        sku: 'azure-linux-3-gen2'
+        version: 'latest'
+      }
+      osDisk: {
+        name: '${name}-disk0'
+        caching: 'ReadWrite'
+        createOption: 'FromImage'
+        managedDisk: {
+          storageAccountType: 'Premium_LRS'
+        }
+      }
+    }
+    networkProfile: {
+      networkInterfaces: [
+        {
+          id: nic.id
+        }
+      ]
+    }
+  }
+  zones: [
+    '1'
+  ]
+}
+```
+
+### Configure with Azure template
+
+To deploy VMs that pass this rule:
+
+- Set the `properties.storageProfile.osDisk.caching` property to `ReadWrite`.
+
+For example:
+
+```json
+{
+  "type": "Microsoft.Compute/virtualMachines",
+  "apiVersion": "2025-04-01",
+  "name": "[parameters('name')]",
+  "location": "[parameters('location')]",
+  "identity": {
+    "type": "SystemAssigned"
+  },
+  "properties": {
+    "hardwareProfile": {
+      "vmSize": "Standard_D8ds_v6"
+    },
+    "osProfile": {
+      "computerName": "[parameters('name')]",
+      "adminUsername": "[parameters('adminUsername')]",
+      "linuxConfiguration": {
+        "provisionVMAgent": true,
+        "disablePasswordAuthentication": true
+      }
+    },
+    "storageProfile": {
+      "imageReference": {
+        "publisher": "MicrosoftCblMariner",
+        "offer": "azure-linux-3",
+        "sku": "azure-linux-3-gen2",
+        "version": "latest"
+      },
+      "osDisk": {
+        "name": "[format('{0}-disk0', parameters('name'))]",
+        "caching": "ReadWrite",
+        "createOption": "FromImage",
+        "managedDisk": {
+          "storageAccountType": "Premium_LRS"
+        }
+      }
+    },
+    "networkProfile": {
+      "networkInterfaces": [
+        {
+          "id": "[resourceId('Microsoft.Network/networkInterfaces', parameters('nicName'))]"
+        }
+      ]
+    }
+  },
+  "zones": [
+    "1"
+  ],
+  "dependsOn": [
+    "[resourceId('Microsoft.Network/networkInterfaces', parameters('nicName'))]"
+  ]
+}
+```
+
+## LINKS
+
+- [PE:08 Data performance](https://learn.microsoft.com/azure/well-architected/performance-efficiency/optimize-data-performance)
+- [Design for high performance](https://learn.microsoft.com/azure/virtual-machines/premium-storage-performance#disk-caching)
+- [Virtual machine and disk performance](https://learn.microsoft.com/azure/virtual-machines/disks-performance)
+- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.compute/virtualmachines)

docs/en/rules/Azure.VM.OSDiskCache.md

@@ -29,7 +29,7 @@ param subnetId string
 param amaIdentityId string
 
 // An example virtual machine running Windows Server and one data disk attached.
-resource vm 'Microsoft.Compute/virtualMachines@2024-11-01' = {
+resource vm 'Microsoft.Compute/virtualMachines@2025-04-01' = {
   name: name
   location: location
   identity: {
@@ -94,7 +94,7 @@ resource vm 'Microsoft.Compute/virtualMachines@2024-11-01' = {
 }
 
 // An example of a VM managed disk.
-resource dataDisk 'Microsoft.Compute/disks@2023-10-02' = {
+resource dataDisk 'Microsoft.Compute/disks@2025-01-02' = {
   name: name
   location: location
   sku: {
@@ -109,7 +109,7 @@ resource dataDisk 'Microsoft.Compute/disks@2023-10-02' = {
 }
 
 // An example of configuring a VM extension for the Azure Monitor Agent.
-resource windowsAgent 'Microsoft.Compute/virtualMachines/extensions@2024-03-01' = {
+resource windowsAgent 'Microsoft.Compute/virtualMachines/extensions@2025-04-01' = {
   parent: vm
   name: 'AzureMonitorWindowsAgent'
   location: location
@@ -156,7 +156,7 @@ resource config 'Microsoft.Maintenance/configurationAssignments@2023-04-01' = {
 }
 
 // An example virtual machine with Azure Hybrid Benefit.
-resource vm_with_benefit 'Microsoft.Compute/virtualMachines@2024-07-01' = {
+resource vm_with_benefit 'Microsoft.Compute/virtualMachines@2025-04-01' = {
   name: name
   location: location
   zones: [
@@ -204,7 +204,7 @@ resource vm_with_benefit 'Microsoft.Compute/virtualMachines@2024-07-01' = {
 param nicName string
 
 // An example network interface
-resource nic 'Microsoft.Network/networkInterfaces@2023-06-01' = {
+resource nic 'Microsoft.Network/networkInterfaces@2025-05-01' = {
   name: nicName
   location: location
   properties: {
@@ -223,15 +223,15 @@ resource nic 'Microsoft.Network/networkInterfaces@2023-06-01' = {
 }
 
 // An example virtual machine running Azure Linux.
-resource linux 'Microsoft.Compute/virtualMachines@2024-03-01' = {
+resource linux 'Microsoft.Compute/virtualMachines@2025-04-01' = {
   name: name
   location: location
   identity: {
     type: 'SystemAssigned'
   }
   properties: {
     hardwareProfile: {
-      vmSize: 'Standard_D8d_v5'
+      vmSize: 'Standard_D8ds_v6'
     }
     osProfile: {
       computerName: name
@@ -244,8 +244,8 @@ resource linux 'Microsoft.Compute/virtualMachines@2024-03-01' = {
     storageProfile: {
       imageReference: {
         publisher: 'MicrosoftCblMariner'
-        offer: 'Cbl-Mariner'
-        sku: 'cbl-mariner-2-gen2'
+        offer: 'azure-linux-3'
+        sku: 'azure-linux-3-gen2'
         version: 'latest'
       }
       osDisk: {

docs/examples/resources/vm.bicep

@@ -4,13 +4,15 @@
   "metadata": {
     "_generator": {
       "name": "bicep",
-      "version": "0.34.44.8038",
-      "templateHash": "18140604143517495412"
+      "version": "0.41.2.15936",
+      "templateHash": "12918842436261158023"
     }
   },
   "parameters": {
     "name": {
       "type": "string",
+      "minLength": 1,
+      "maxLength": 15,
       "metadata": {
         "description": "The name of the resource."
       }
@@ -64,7 +66,7 @@
   "resources": [
     {
       "type": "Microsoft.Compute/virtualMachines",
-      "apiVersion": "2024-11-01",
+      "apiVersion": "2025-04-01",
       "name": "[parameters('name')]",
       "location": "[parameters('location')]",
       "identity": {
@@ -133,7 +135,7 @@
     },
     {
       "type": "Microsoft.Compute/disks",
-      "apiVersion": "2023-10-02",
+      "apiVersion": "2025-01-02",
       "name": "[parameters('name')]",
       "location": "[parameters('location')]",
       "sku": {
@@ -148,7 +150,7 @@
     },
     {
       "type": "Microsoft.Compute/virtualMachines/extensions",
-      "apiVersion": "2024-03-01",
+      "apiVersion": "2025-04-01",
       "name": "[format('{0}/{1}', parameters('name'), 'AzureMonitorWindowsAgent')]",
       "location": "[parameters('location')]",
       "properties": {
@@ -188,7 +190,7 @@
     {
       "type": "Microsoft.Maintenance/configurationAssignments",
       "apiVersion": "2023-04-01",
-      "scope": "[format('Microsoft.Compute/virtualMachines/{0}', parameters('name'))]",
+      "scope": "[resourceId('Microsoft.Compute/virtualMachines', parameters('name'))]",
       "name": "[parameters('name')]",
       "location": "[parameters('location')]",
       "properties": {
@@ -201,7 +203,7 @@
     },
     {
       "type": "Microsoft.Compute/virtualMachines",
-      "apiVersion": "2024-07-01",
+      "apiVersion": "2025-04-01",
       "name": "[parameters('name')]",
       "location": "[parameters('location')]",
       "zones": [
@@ -247,7 +249,7 @@
     },
     {
       "type": "Microsoft.Network/networkInterfaces",
-      "apiVersion": "2023-06-01",
+      "apiVersion": "2025-05-01",
       "name": "[parameters('nicName')]",
       "location": "[parameters('location')]",
       "properties": {
@@ -266,15 +268,15 @@
     },
     {
       "type": "Microsoft.Compute/virtualMachines",
-      "apiVersion": "2024-03-01",
+      "apiVersion": "2025-04-01",
       "name": "[parameters('name')]",
       "location": "[parameters('location')]",
       "identity": {
         "type": "SystemAssigned"
       },
       "properties": {
         "hardwareProfile": {
-          "vmSize": "Standard_D8d_v5"
+          "vmSize": "Standard_D8ds_v6"
         },
         "osProfile": {
           "computerName": "[parameters('name')]",
@@ -287,8 +289,8 @@
         "storageProfile": {
           "imageReference": {
             "publisher": "MicrosoftCblMariner",
-            "offer": "Cbl-Mariner",
-            "sku": "cbl-mariner-2-gen2",
+            "offer": "azure-linux-3",
+            "sku": "azure-linux-3-gen2",
             "version": "latest"
           },
           "osDisk": {