Added AVD agent update schedule Azure#2946 (Azure#2947)

BernieWhite · Jun 18, 2024 · 5095d47 · 5095d47
1 parent 9f9b5ea
commit 5095d47
Show file tree

Hide file tree

Showing 8 changed files with 511 additions and 0 deletions.
diff --git a/docs/CHANGELOG-v1.md b/docs/CHANGELOG-v1.md
@@ -39,6 +39,9 @@ What's changed since pre-release v1.38.0-B0011:
   - Azure Kubernetes Service:
     - Added check to automatically upgrade AKS cluster node image by @sharmilamusunuru.
       [#2445](https://github.com/Azure/PSRule.Rules.Azure/issues/2445)
+  - Azure Virtual Desktop:
+    - Added check for scheduled agent updates on host pools by @BernieWhite.
+      [#2946](https://github.com/Azure/PSRule.Rules.Azure/issues/2946)
 - Engineering:
   - Quality updates to rule documentation by @BernieWhite.
     [#2570](https://github.com/Azure/PSRule.Rules.Azure/issues/2570)

diff --git a/docs/en/rules/Azure.AVD.ScheduleAgentUpdate.md b/docs/en/rules/Azure.AVD.ScheduleAgentUpdate.md
@@ -0,0 +1,113 @@
+---
+reviewed: 2024-06-18
+severity: Important
+pillar: Reliability
+category: RE:04 Target metrics
+resource: Azure Virtual Desktop
+online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.AVD.ScheduleAgentUpdate/
+---
+
+# Schedule agent updates for host pools
+
+## SYNOPSIS
+
+Define a windows for agent updates to minimize disruptions to users.
+
+## DESCRIPTION
+
+Azure Virtual Desktop (AVD) regularly provide updates to the agent software that runs on host pools.
+The agent software is responsible for managing user sessions and providing access to resources.
+These updates provide new functionality and fixes.
+While the update process is designed to minimize disruptions, updates should be applied outside of peak load times.
+
+By default, agent updates are applied automatically when they become available.
+If you have configured a maintenance window, updates are only applied during the maintenance window that you specify.
+Each host pool can configure up to two maintenance windows per week.
+
+## RECOMMENDATION
+
+Consider defining a maintenance window for agent updates to minimize disruptions to users on AVD host pools.
+
+## EXAMPLES
+
+### Configure with Azure template
+
+To deploy host pools that pass this rule:
+
+- Set the `properties.agentUpdate.type` property to `Scheduled`. _AND_
+- Configure one or more maintenance windows in the `properties.agentUpdate.maintenanceWindows` property.
+
+For example:
+
+```json
+{
+  "type": "Microsoft.DesktopVirtualization/hostPools",
+  "apiVersion": "2024-04-03",
+  "name": "[parameters('name')]",
+  "location": "[parameters('location')]",
+  "identity": {
+    "type": "SystemAssigned"
+  },
+  "properties": {
+    "hostPoolType": "Pooled",
+    "loadBalancerType": "DepthFirst",
+    "preferredAppGroupType": "Desktop",
+    "maxSessionLimit": 10,
+    "agentUpdate": {
+      "type": "Scheduled",
+      "maintenanceWindowTimeZone": "AUS Eastern Standard Time",
+      "maintenanceWindows": [
+        {
+          "dayOfWeek": "Sunday",
+          "hour": 1
+        }
+      ]
+    }
+  }
+}
+```
+
+### Configure with Bicep
+
+To deploy host pools that pass this rule:
+
+- Set the `properties.agentUpdate.type` property to `Scheduled`. _AND_
+- Configure one or more maintenance windows in the `properties.agentUpdate.maintenanceWindows` property.
+
+For example:
+
+```bicep
+resource pool 'Microsoft.DesktopVirtualization/hostPools@2024-04-03' = {
+  name: name
+  location: location
+  identity: {
+    type: 'SystemAssigned'
+  }
+  properties: {
+    hostPoolType: 'Pooled'
+    loadBalancerType: 'DepthFirst'
+    preferredAppGroupType: 'Desktop'
+    maxSessionLimit: 10
+    agentUpdate: {
+      type: 'Scheduled'
+      maintenanceWindowTimeZone: 'AUS Eastern Standard Time'
+      maintenanceWindows: [
+        {
+          dayOfWeek: 'Sunday'
+          hour: 1
+        }
+      ]
+    }
+  }
+}
+```
+
+<!-- external:avm avm/res/desktop-virtualization/host-pool agentUpdate -->
+
+## LINKS
+
+- [RE:04 Target metrics](https://learn.microsoft.com/azure/well-architected/reliability/metrics)
+- [Get started with the Azure Virtual Desktop Agent](https://learn.microsoft.com/azure/virtual-desktop/agent-overview#agent-update-process)
+- [Scheduled Agent Updates for Azure Virtual Desktop host pools](https://learn.microsoft.com/azure/virtual-desktop/scheduled-agent-updates)
+- [What's new in the Azure Virtual Desktop Agent?](https://learn.microsoft.com/azure/virtual-desktop/whats-new-agent)
+- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.desktopvirtualization/hostpools)
diff --git a/docs/examples-avd.bicep b/docs/examples-avd.bicep
@@ -0,0 +1,89 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+@description('The name of the resource.')
+param name string
+
+@description('The location resources will be deployed.')
+param location string = resourceGroup().location
+
+// An example pooled desktop host pool using depth first load balancing.
+resource pool 'Microsoft.DesktopVirtualization/hostPools@2024-04-03' = {
+  name: name
+  location: location
+  identity: {
+    type: 'SystemAssigned'
+  }
+  properties: {
+    hostPoolType: 'Pooled'
+    loadBalancerType: 'DepthFirst'
+    preferredAppGroupType: 'Desktop'
+    maxSessionLimit: 10
+    agentUpdate: {
+      type: 'Scheduled'
+      maintenanceWindowTimeZone: 'AUS Eastern Standard Time'
+      maintenanceWindows: [
+        {
+          dayOfWeek: 'Sunday'
+          hour: 1
+        }
+      ]
+    }
+  }
+}
+
+// An example scaling plan for a host pool.
+resource scaling 'Microsoft.DesktopVirtualization/scalingPlans@2024-04-03' = {
+  name: name
+  location: location
+  properties: {
+    timeZone: 'E. Australia Standard Time'
+    hostPoolType: 'Pooled'
+    hostPoolReferences: [
+      {
+        hostPoolArmPath: pool.id
+        scalingPlanEnabled: true
+      }
+    ]
+    schedules: [
+      {
+        rampUpStartTime: {
+          hour: 8
+          minute: 0
+        }
+        peakStartTime: {
+          hour: 9
+          minute: 0
+        }
+        rampDownStartTime: {
+          hour: 18
+          minute: 0
+        }
+        offPeakStartTime: {
+          hour: 22
+          minute: 0
+        }
+        name: 'weekdays_schedule'
+        daysOfWeek: [
+          'Monday'
+          'Tuesday'
+          'Wednesday'
+          'Thursday'
+          'Friday'
+        ]
+        rampUpLoadBalancingAlgorithm: 'BreadthFirst'
+        rampUpMinimumHostsPct: 20
+        rampUpCapacityThresholdPct: 60
+        peakLoadBalancingAlgorithm: 'DepthFirst'
+        rampDownLoadBalancingAlgorithm: 'DepthFirst'
+        rampDownMinimumHostsPct: 10
+        rampDownCapacityThresholdPct: 90
+        rampDownForceLogoffUsers: true
+        rampDownWaitTimeMinutes: 30
+        rampDownNotificationMessage: 'You will be logged off in 30 min. Make sure to save your work.'
+        rampDownStopHostsWhen: 'ZeroSessions'
+        offPeakLoadBalancingAlgorithm: 'DepthFirst'
+      }
+    ]
+  }
+}
diff --git a/docs/examples-avd.json b/docs/examples-avd.json
@@ -0,0 +1,112 @@
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "metadata": {
+    "_generator": {
+      "name": "bicep",
+      "version": "0.28.1.47646",
+      "templateHash": "18117889941546285249"
+    }
+  },
+  "parameters": {
+    "name": {
+      "type": "string",
+      "metadata": {
+        "description": "The name of the resource."
+      }
+    },
+    "location": {
+      "type": "string",
+      "defaultValue": "[resourceGroup().location]",
+      "metadata": {
+        "description": "The location resources will be deployed."
+      }
+    }
+  },
+  "resources": [
+    {
+      "type": "Microsoft.DesktopVirtualization/hostPools",
+      "apiVersion": "2024-04-03",
+      "name": "[parameters('name')]",
+      "location": "[parameters('location')]",
+      "identity": {
+        "type": "SystemAssigned"
+      },
+      "properties": {
+        "hostPoolType": "Pooled",
+        "loadBalancerType": "DepthFirst",
+        "preferredAppGroupType": "Desktop",
+        "maxSessionLimit": 10,
+        "agentUpdate": {
+          "type": "Scheduled",
+          "maintenanceWindowTimeZone": "AUS Eastern Standard Time",
+          "maintenanceWindows": [
+            {
+              "dayOfWeek": "Sunday",
+              "hour": 1
+            }
+          ]
+        }
+      }
+    },
+    {
+      "type": "Microsoft.DesktopVirtualization/scalingPlans",
+      "apiVersion": "2024-04-03",
+      "name": "[parameters('name')]",
+      "location": "[parameters('location')]",
+      "properties": {
+        "timeZone": "E. Australia Standard Time",
+        "hostPoolType": "Pooled",
+        "hostPoolReferences": [
+          {
+            "hostPoolArmPath": "[resourceId('Microsoft.DesktopVirtualization/hostPools', parameters('name'))]",
+            "scalingPlanEnabled": true
+          }
+        ],
+        "schedules": [
+          {
+            "rampUpStartTime": {
+              "hour": 8,
+              "minute": 0
+            },
+            "peakStartTime": {
+              "hour": 9,
+              "minute": 0
+            },
+            "rampDownStartTime": {
+              "hour": 18,
+              "minute": 0
+            },
+            "offPeakStartTime": {
+              "hour": 22,
+              "minute": 0
+            },
+            "name": "weekdays_schedule",
+            "daysOfWeek": [
+              "Monday",
+              "Tuesday",
+              "Wednesday",
+              "Thursday",
+              "Friday"
+            ],
+            "rampUpLoadBalancingAlgorithm": "BreadthFirst",
+            "rampUpMinimumHostsPct": 20,
+            "rampUpCapacityThresholdPct": 60,
+            "peakLoadBalancingAlgorithm": "DepthFirst",
+            "rampDownLoadBalancingAlgorithm": "DepthFirst",
+            "rampDownMinimumHostsPct": 10,
+            "rampDownCapacityThresholdPct": 90,
+            "rampDownForceLogoffUsers": true,
+            "rampDownWaitTimeMinutes": 30,
+            "rampDownNotificationMessage": "You will be logged off in 30 min. Make sure to save your work.",
+            "rampDownStopHostsWhen": "ZeroSessions",
+            "offPeakLoadBalancingAlgorithm": "DepthFirst"
+          }
+        ]
+      },
+      "dependsOn": [
+        "[resourceId('Microsoft.DesktopVirtualization/hostPools', parameters('name'))]"
+      ]
+    }
+  ]
+}
diff --git a/pipeline.build.ps1 b/pipeline.build.ps1
@@ -345,6 +345,7 @@ task Rules Dependencies, {
         As           = 'Summary'
         Outcome      = 'Problem'
     }
+    Import-Module PSRule -RequiredVersion 2.9.0;
     Import-Module (Join-Path -Path $PWD -ChildPath out/modules/PSRule.Rules.Azure) -Force;
     Assert-PSRule @assertParams -InputPath $PWD -Module PSRule.Rules.MSFT.OSS -Format File -OutputPath reports/ps-rule-file.xml;
 

diff --git a/src/PSRule.Rules.Azure/rules/Azure.AVD.Rule.yaml b/src/PSRule.Rules.Azure/rules/Azure.AVD.Rule.yaml
@@ -0,0 +1,32 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+#
+# Validation rules for Azure Virtual Desktop
+#
+
+#region Rules
+
+---
+# Synopsis: Define a windows for agent updates to minimize disruptions to users.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Rule
+metadata:
+  name: Azure.AVD.ScheduleAgentUpdate
+  ref: AZR-000437
+  tags:
+    release: GA
+    ruleSet: 2024_06
+    Azure.WAF/pillar: Reliability
+spec:
+  type:
+  - Microsoft.DesktopVirtualization/hostPools
+  condition:
+    allOf:
+      - field: properties.agentUpdate.type
+        equals: Scheduled
+
+      - field: properties.agentUpdate.maintenanceWindows
+        greaterOrEquals: 1
+
+#endregion Rules