Updated Azure.VM.MaintenanceConfig #2925 (#2929)

docs/CHANGELOG-v1.md

@@ -29,23 +29,26 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 ## Unreleased
 
-- New rules:
-  - Azure Database for PostgreSQL:
-    - Verify that Azure Database for PostgreSQL servers have a customer-controlled maintenance window configured by @BenjaminEngeset.
-      [#2927](https://github.com/Azure/PSRule.Rules.Azure/issues/2927)
-
-What's changed since pre-release v1.37.0:
+What's changed since v1.37.0:
 
 - New rules:
   - Azure Database for MySQL:
     - Verify that Azure Database for MySQL servers have a customer-controlled maintenance window configured by @BenjaminEngeset.
       [#2916](https://github.com/Azure/PSRule.Rules.Azure/issues/2916)
+  - Azure Database for PostgreSQL:
+    - Verify that Azure Database for PostgreSQL servers have a customer-controlled maintenance window configured by @BenjaminEngeset.
+      [#2927](https://github.com/Azure/PSRule.Rules.Azure/issues/2927)
   - Azure Firewall:
     - Verify that firewalls have availability zones configured by @BenjaminEngeset.
       [#2909](https://github.com/Azure/PSRule.Rules.Azure/issues/2909)
   - Virtual Network Gateway:
     - Verify that VPN/ExpressRoute gateways have a customer-controlled maintenance configuration configured by @BenjaminEngeset.
       [#2910](https://github.com/Azure/PSRule.Rules.Azure/issues/2910)
+- Updated rules:
+  - Virtual Machine:
+    - Updated `Azure.VM.MaintenanceConfig` to align to the reliability pillar by @BernieWhite.
+      [#2925](https://github.com/Azure/PSRule.Rules.Azure/issues/2925)
+      - Promoted to GA and bumped rule set to `2024_06`.
 
 ## v1.37.0
 

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

@@ -1,7 +1,8 @@
 ---
+reviewed: 2024-06-12
 severity: Important
-pillar: Operational Excellence
-category: Repeatable infrastructure
+pillar: Reliability
+category: RE:04 Target metrics
 resource: Virtual Machine
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.VM.MaintenanceConfig/
 ---
@@ -14,11 +15,21 @@ Use a maintenance configuration for virtual machines.
 
 ## DESCRIPTION
 
-Virtual machines can be attached to a maintenance configuration which allows customer managed assessments and updates for machine patches within the guest operating system.
+Azure Virtual Machines (VMs) support maintenance configurations.
+You can use the Maintenance Configurations to control and manage updates for Azure VM resources.
+Configuring a maintenance window and time zone allows you to reduce disruptions to your workloads during peak hours.
+
+If a maintenance configuration is not associated:
+
+- Updates managed by the platform may be still be scheduled for your virtual machine.
+- The schedule determined by the platform may not align with your maintenance window.
+
+Maintenance configurations also integrate with Azure Update Manager.
+Azure Update Manager can be used to apply guest operating system (OS) updates to keep your VMs secure and compliant.
 
 ## RECOMMENDATION
 
-Consider automatically managing and applying operating system updates by associating a maintenance configuration.
+Consider associating a maintenance configuration to your VM to reduce unplanned disruptions to your workloads.
 
 ## EXAMPLES
 
@@ -34,14 +45,15 @@ For example:
 ```json
 {
   "type": "Microsoft.Maintenance/configurationAssignments",
-  "apiVersion": "2022-11-01-preview",
-  "name": "[parameters('assignmentName')]",
-  "location": "[parameters('location')]",
+  "apiVersion": "2023-04-01",
   "scope": "[format('Microsoft.Compute/virtualMachines/{0}', parameters('name'))]",
+  "name": "[parameters('name')]",
+  "location": "[parameters('location')]",
   "properties": {
-    "maintenanceConfigurationId": "[parameters('maintenanceConfigurationId')]"
+    "maintenanceConfigurationId": "[resourceId('Microsoft.Maintenance/maintenanceConfigurations', parameters('name'))]"
   },
   "dependsOn": [
+    "[resourceId('Microsoft.Maintenance/maintenanceConfigurations', parameters('name'))]",
     "[resourceId('Microsoft.Compute/virtualMachines', parameters('name'))]"
   ]
 }
@@ -57,27 +69,21 @@ To deploy virtual machines that pass this rule:
 For example:
 
 ```bicep
-resource config 'Microsoft.Maintenance/configurationAssignments@2022-11-01-preview' = {
-  name: assignmentName
+resource config 'Microsoft.Maintenance/configurationAssignments@2023-04-01' = {
+  name: name
   location: location
   scope: vm
   properties: {
-    maintenanceConfigurationId: maintenanceConfigurationId
+    maintenanceConfigurationId: maintenanceConfiguration.id
   }
 }
 ```
 
-## NOTES
-
-Operating system updates with Update Management center is a preview feature.
-Not all operating systems are supported, check out the `LINKS` section for more information.
-Update management center doesn't support driver updates.
-
 ## LINKS
 
-- [Repeatable infrastructure](https://learn.microsoft.com/azure/well-architected/devops/automation-infrastructure)
-- [About Update management center](https://learn.microsoft.com/azure/update-center/overview)
-- [How to programmatically manage updates for Azure VMs](https://learn.microsoft.com/azure/update-center/manage-vms-programmatically)
-- [Manage Update configuration settings](https://learn.microsoft.com/azure/update-center/manage-update-settings)
-- [Supported operating systems](https://learn.microsoft.com/azure/update-center/support-matrix?tabs=azurevm%2Cazurevm-os#supported-operating-systems)
+- [RE:04 Target metrics](https://learn.microsoft.com/azure/well-architected/reliability/metrics)
+- [Managing VM updates with Maintenance Configurations](https://learn.microsoft.com/azure/virtual-machines/maintenance-configurations)
+- [About Azure Update Manager](https://learn.microsoft.com/azure/update-manager/overview)
+- [Manage update configuration settings](https://learn.microsoft.com/azure/update-manager/manage-update-settings)
+- [Support matrix for Azure Update Manager](https://learn.microsoft.com/azure/update-manager/support-matrix)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.maintenance/configurationassignments)

docs/examples-vm.bicep

@@ -27,7 +27,7 @@ param subnetId string
 param amaIdentityId string
 
 // An example virtual machine running Windows Server and one data disk attached.
-resource vm 'Microsoft.Compute/virtualMachines@2023-09-01' = {
+resource vm 'Microsoft.Compute/virtualMachines@2024-03-01' = {
   name: name
   location: location
   zones: [
@@ -78,7 +78,7 @@ resource vm 'Microsoft.Compute/virtualMachines@2023-09-01' = {
 }
 
 // An example of a VM managed disk.
-resource dataDisk 'Microsoft.Compute/disks@2023-04-02' = {
+resource dataDisk 'Microsoft.Compute/disks@2023-10-02' = {
   name: name
   location: location
   sku: {
@@ -93,7 +93,7 @@ resource dataDisk 'Microsoft.Compute/disks@2023-04-02' = {
 }
 
 // An example of configuring a VM extension for the Azure Monitor Agent.
-resource windowsAgent 'Microsoft.Compute/virtualMachines/extensions@2023-09-01' = {
+resource windowsAgent 'Microsoft.Compute/virtualMachines/extensions@2024-03-01' = {
   parent: vm
   name: 'AzureMonitorWindowsAgent'
   location: location
@@ -114,6 +114,31 @@ resource windowsAgent 'Microsoft.Compute/virtualMachines/extensions@2023-09-01'
   }
 }
 
+// An example maintenance configuration for specifying a in-guest patch maintenance window.
+resource maintenanceConfiguration 'Microsoft.Maintenance/maintenanceConfigurations@2023-04-01' = {
+  name: name
+  location: location
+  properties: {
+    maintenanceScope: 'InGuestPatch'
+    maintenanceWindow: {
+      startDateTime: '2021-08-21 01:18'
+      expirationDateTime: '2221-05-19 03:30'
+      duration: '01:30'
+      recurEvery: 'Day'
+    }
+  }
+}
+
+// An example of an assignment of a maintenance configuration to a virtual machine.
+resource config 'Microsoft.Maintenance/configurationAssignments@2023-04-01' = {
+  name: name
+  location: location
+  scope: vm
+  properties: {
+    maintenanceConfigurationId: maintenanceConfiguration.id
+  }
+}
+
 // An example virtual machine with Azure Hybrid Benefit.
 resource vm_with_benefit 'Microsoft.Compute/virtualMachines@2023-09-01' = {
   name: name

docs/examples-vm.json

@@ -4,8 +4,8 @@
   "metadata": {
     "_generator": {
       "name": "bicep",
-      "version": "0.24.24.22086",
-      "templateHash": "15227880975941749724"
+      "version": "0.28.1.47646",
+      "templateHash": "14523451418990638896"
     }
   },
   "parameters": {
@@ -64,7 +64,7 @@
   "resources": [
     {
       "type": "Microsoft.Compute/virtualMachines",
-      "apiVersion": "2023-09-01",
+      "apiVersion": "2024-03-01",
       "name": "[parameters('name')]",
       "location": "[parameters('location')]",
       "zones": [
@@ -119,7 +119,7 @@
     },
     {
       "type": "Microsoft.Compute/disks",
-      "apiVersion": "2023-04-02",
+      "apiVersion": "2023-10-02",
       "name": "[parameters('name')]",
       "location": "[parameters('location')]",
       "sku": {
@@ -134,7 +134,7 @@
     },
     {
       "type": "Microsoft.Compute/virtualMachines/extensions",
-      "apiVersion": "2023-09-01",
+      "apiVersion": "2024-03-01",
       "name": "[format('{0}/{1}', parameters('name'), 'AzureMonitorWindowsAgent')]",
       "location": "[parameters('location')]",
       "properties": {
@@ -156,6 +156,35 @@
         "[resourceId('Microsoft.Compute/virtualMachines', parameters('name'))]"
       ]
     },
+    {
+      "type": "Microsoft.Maintenance/maintenanceConfigurations",
+      "apiVersion": "2023-04-01",
+      "name": "[parameters('name')]",
+      "location": "[parameters('location')]",
+      "properties": {
+        "maintenanceScope": "InGuestPatch",
+        "maintenanceWindow": {
+          "startDateTime": "2021-08-21 01:18",
+          "expirationDateTime": "2221-05-19 03:30",
+          "duration": "01:30",
+          "recurEvery": "Day"
+        }
+      }
+    },
+    {
+      "type": "Microsoft.Maintenance/configurationAssignments",
+      "apiVersion": "2023-04-01",
+      "scope": "[format('Microsoft.Compute/virtualMachines/{0}', parameters('name'))]",
+      "name": "[parameters('name')]",
+      "location": "[parameters('location')]",
+      "properties": {
+        "maintenanceConfigurationId": "[resourceId('Microsoft.Maintenance/maintenanceConfigurations', parameters('name'))]"
+      },
+      "dependsOn": [
+        "[resourceId('Microsoft.Maintenance/maintenanceConfigurations', parameters('name'))]",
+        "[resourceId('Microsoft.Compute/virtualMachines', parameters('name'))]"
+      ]
+    },
     {
       "type": "Microsoft.Compute/virtualMachines",
       "apiVersion": "2023-09-01",

src/PSRule.Rules.Azure/rules/Azure.VM.Rule.ps1

@@ -277,8 +277,8 @@ Rule 'Azure.VM.AMA' -Ref 'AZR-000345' -Type 'Microsoft.Compute/virtualMachines'
 
 #region Maintenance Configuration
 
-# Synopsis: Use a maintenance configuration for virtual machines. 
-Rule 'Azure.VM.MaintenanceConfig' -Ref 'AZR-000375' -Type 'Microsoft.Compute/virtualMachines' -Tag @{ release = 'preview'; ruleSet = '2023_06'; 'Azure.WAF/pillar' = 'Operational Excellence'; } {
+# Synopsis: Use a maintenance configuration for virtual machines.
+Rule 'Azure.VM.MaintenanceConfig' -Ref 'AZR-000375' -Type 'Microsoft.Compute/virtualMachines' -Tag @{ release = 'GA'; ruleSet = '2024_06'; 'Azure.WAF/pillar' = 'Reliability'; } {
     $maintenanceConfig = @(GetSubResources -ResourceType 'Microsoft.Maintenance/configurationAssignments' |
         Where-Object { $_.properties.maintenanceConfigurationId })
     $Assert.GreaterOrEqual($maintenanceConfig, '.', 1).Reason($LocalizedData.VMMaintenanceConfig, $PSRule.TargetName)

tests/PSRule.Rules.Azure.Tests/Azure.Baseline.Tests.ps1

@@ -199,7 +199,7 @@ Describe 'Baselines' -Tag Baseline {
             $result = @(Get-PSRule -Module PSRule.Rules.Azure -Baseline 'Azure.Preview_2023_06' -WarningAction Ignore);
             $filteredResult = @($result | Where-Object { $_.Tag.release -in 'preview'});
             $filteredResult | Should -Not -BeNullOrEmpty;
-            $filteredResult.Length | Should -Be 8;
+            $filteredResult.Length | Should -Be 7;
         }
 
         It 'With Azure.GA_2023_09' {
@@ -213,7 +213,7 @@ Describe 'Baselines' -Tag Baseline {
             $result = @(Get-PSRule -Module PSRule.Rules.Azure -Baseline 'Azure.Preview_2023_09' -WarningAction Ignore);
             $filteredResult = @($result | Where-Object { $_.Tag.release -in 'preview'});
             $filteredResult | Should -Not -BeNullOrEmpty;
-            $filteredResult.Length | Should -Be 9;
+            $filteredResult.Length | Should -Be 8;
         }
 
         It 'With Azure.GA_2023_12' {
@@ -227,7 +227,7 @@ Describe 'Baselines' -Tag Baseline {
             $result = @(Get-PSRule -Module PSRule.Rules.Azure -Baseline 'Azure.Preview_2023_12' -WarningAction Ignore);
             $filteredResult = @($result | Where-Object { $_.Tag.release -in 'preview'});
             $filteredResult | Should -Not -BeNullOrEmpty;
-            $filteredResult.Length | Should -Be 9;
+            $filteredResult.Length | Should -Be 8;
         }
 
         It 'With Azure.GA_2024_03' {
@@ -241,7 +241,7 @@ Describe 'Baselines' -Tag Baseline {
             $result = @(Get-PSRule -Module PSRule.Rules.Azure -Baseline 'Azure.Preview_2024_03' -WarningAction Ignore);
             $filteredResult = @($result | Where-Object { $_.Tag.release -in 'preview'});
             $filteredResult | Should -Not -BeNullOrEmpty;
-            $filteredResult.Length | Should -Be 9;
+            $filteredResult.Length | Should -Be 8;
         }
     }
 }