Edit

Share via

Update session hosts using session host update in Azure Virtual Desktop (preview)

  • Article

Important

Session host update for Azure Virtual Desktop is currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

When you want to update session hosts in a host pool with a session host configuration, you use session host update. Session host update enables you to update the underlying virtual machine (VM) image, size, disk type, and other configuration properties. During an update, the existing virtual machines are deleted or deallocated, and new ones are created with the updated configuration stored in the session host configuration. The update also uses the values from the session host management policy to determine how session hosts should get updated.

This article shows you how to update a host pool's session host configuration, update the session hosts in that pool, and how to monitor the progress of an update using the Azure portal and Azure PowerShell.

To learn more about how session host update works, see Session host update.

Prerequisites

Before you update session hosts using session host update, you need:

  • An existing pooled host pool with a session host configuration with session hosts that are all in the same Azure region and resource group. Personal host pools aren't supported.

  • The new image must be supported for Azure Virtual Desktop and match the generation of virtual machine. If you're using Trusted launch virtual machines or Confidential virtual machines, your image must be for generation 2 VMs. It can be from:

    • Azure Marketplace.
    • An existing Azure Compute Gallery shared image. We recommend having at least two replicas of the image you use.
    • An existing managed image.

  • Remove any resource locks on session hosts or the resource group they're in.

  • Assign the Azure Virtual Desktop service principal the Desktop Virtualization Virtual Machine Contributor role-based access control (RBAC) role on the resource group or subscription with the host pools and session hosts you want to use with session host update. For more information, see Assign Azure RBAC roles or Microsoft Entra roles to the Azure Virtual Desktop service principals.

  • An Azure account you use to configure session host update with the following Azure RBAC roles to update the following resource types. You can also use another built-in role that includes the same permissions, or create a custom role.

    Resource type Built-in Azure RBAC role Scope
    Host pool Desktop Virtualization Host Pool Contributor
    Desktop Virtualization Application Group Contributor    		 Resource group or subscription
    Session hosts Virtual Machine Contributor Resource group or subscription

  • You can only join session hosts to an Active Directory domain. Joining session hosts to Microsoft Entra ID isn't supported, but you can use Microsoft Entra hybrid join.

    • If you're joining session hosts to a Microsoft Entra Domain Services domain, you need to be a member of the AAD DC Administrators group.

    • If you're joining session hosts to an Active Directory Domain Services (AD DS) domain, you need to use an account with more permissions than typically required for joining a domain because the new OS image reuses the existing computer object. The permissions and properties in the following table need to be applied to the account on the Organizational Unit (OU) containing your session hosts:

      Name Type Applies to
      Reset password Allow Decendent Computer objects
      Validated write to DNS host name Allow Decendent Computer objects
      Validated write to service principal name Allow Decendent Computer objects
      Read account restrictions Allow Decendent Computer objects
      Write account restrictions Allow Decendent Computer objects

      Beginning with KB5020276, further protections were introduced for the reuse of computer accounts in an Active Directory domain. To successfully reuse the existing computer object for the session host, either:

      • The user account joining the session host to the domain is the creator of the existing computer account.
      • The computer account was created by a member of the domain administrators security group.
      • Apply the Group Policy setting Domain controller: Allow computer account re-use during domain join to the owner of the computer account. For more information on the scope of this setting, see KB5020276.

  • A key vault containing the secrets you want to use for your virtual machine local administrator account credentials and, if you're joining session hosts to an Active Directory domain, your domain join account credentials. You need one secret for each username and password. The virtual machine local administrator password must meet the password requirements when creating a VM.

    See Assign Azure RBAC roles or Microsoft Entra roles to the Azure Virtual Desktop service principals to make sure you're using the correct service principal.

  • For any custom configuration PowerShell scripts you specify in the session host configuration to run after an update, the URL to the script must be resolvable from the public internet.

  • If you want to use Azure PowerShell locally, see Use Azure CLI and Azure PowerShell with Azure Virtual Desktop to make sure you have the Az.DesktopVirtualization PowerShell module installed. Alternatively, use the Azure Cloud Shell.

  • Azure PowerShell cmdlets for Azure Virtual Desktop that support session host update are in preview. You need to download and install the preview version of the Az.DesktopVirtualization module to use these cmdlets, which are added in version 5.3.0.

Schedule an update and edit a session host configuration

When you schedule an update, the session host configuration for the host pool is used. You need to make changes to the session host configuration when scheduling an update, otherwise your session hosts are redeployed with the same session host configuration values. Any changes you make when scheduling an update are saved to the session host configuration.

To schedule an update for your session hosts, select the relevant tab for your scenario and follow the steps.

Important

  • During an update, the number of available session hosts for user sessions is reduced and any logged on users will be asked to log off. We recommend you schedule an update during less busy periods to minimize disruption to end users.

  • If you use a custom network security group (NSG) for the session hosts you want to update, there's a known issue where you can't start an update using the Azure portal. To work around this issue, use Azure PowerShell to start the update.

Here's how to schedule a new update for your session hosts using the Azure portal.

Tip

When you schedule an update using the Azure portal, values are populated from the session host configuration. If this is the first update and a session host configuration hasn't already been created, the portal shows the default session host configuration until the session host configuration is created. Any changes you make to the session host configuration during an update will be saved.

If you edit the session host configuration using the Azure portal, you have to schedule an update.

  1. Make sure you've registered for the limited preview using the link at the beginning of this article, then sign in to the Azure portal using the specific link provided to you after registration. From the Azure Virtual Desktop overview, select Host pools, then select the host pool with a session host configuration that you want to update.

  2. Select Session hosts.

  3. If you want to review the session host configuration before you schedule an update, select Manage session host configuration, then View. Once you review the session host configuration, select Cancel.

  4. To schedule a new update, select Manage session host update, then select New update. Alternatively, select Manage session host configuration, then Edit.

  5. On the Basics tab, complete the following information:

    Parameter Value/Description
    Enable saving original virtual machines after the update Useful in rollback scenarios, but normal costs apply for storing the original VM's components.
    Current host pool size (read-only) The number of session hosts in your host pool.
    VM batch size authorized to be removed from the host pool during the update The maximum number of session hosts that are updated at a time.

    When the update starts, only one session host, known as the initial, is updated first to verify the update process before updating the remaining session hosts in batches. If the update of the initial isn't successful, the update stops.
    Session hosts available during the update (read-only) The minimum number of session hosts that are available for user sessions during the update.

    Once you complete this tab, select Next: Session hosts.

  6. On the Session hosts tab, you can optionally update the following parameters in your session host configuration:

    Parameter Value/Description
    Security type Select from Standard, Trusted launch virtual machines, or Confidential virtual machines.

    - If you select Trusted launch virtual machines, options for secure boot and vTPM are automatically selected.

    - If you select Confidential virtual machines, options for secure boot, vTPM, and integrity monitoring are automatically selected. You can't opt out of vTPM when using a confidential VM.
    Image Select the OS image you want to use from the list, or select See all images to see more, including any custom images you created and stored as an Azure Compute Gallery shared image or a managed image.
    Virtual machine size Select a recommended SKU from the list. If you want to use different SKU, select See all sizes, then select from the list.
    OS disk type Select the disk type to use for your session hosts. We recommend you use Premium SSD for production workloads.

    The disk type needs to be supported on the VM family and size selected. Ensure that you're selecting a combination that Azure compute supports. The name of the OS disk of the updated session hosts has a new name in the format SessionHostName-DateTime_Hash.
    Domain to join
    Select which directory you would like to join Select Active Directory, then select the key vault that contains the secrets for the username and password for the domain join account.

    You can optionally specify a domain name and organizational unit path.
    Virtual Machine Administrator account Complete the relevant parameters by selecting the key vault and secret for the username and password for the local administrator account of the updated session host VMs. The username and password must meet the requirements for Windows VMs in Azure.
    Custom configuration
    Custom configuration script URL If you want to run a PowerShell script during deployment you can enter the URL here.

    Once you review or finish making changes to the session host configuration, select Next: Schedule.

  7. On the Schedule tab, either check the box to Schedule update now, or select a date, time, and time zone that you want the update to start, up to a maximum of two weeks from the current time.

    Once you set your schedule, select Next: Notifications.

  8. On the Notifications tab, complete the following information:

    Parameter Value/Description
    Minutes before the users are signed out The amount of time to wait after the update start time for users to be notified to sign out. This value is configurable between 0 and 60 minutes. Users will automatically be logged off after this elapsed time.
    Sign out message A message you can specify to inform users that the session host they're using is about to start updating.

    Once you complete this tab, select Next: Review.

  9. On the Review tab, ensure validation passes and review the information that is used during the update.

  10. Select Update to schedule the update. When you view the list of session hosts, the column Current Version shows the timestamp of the version of the session host configuration that the session host is using. If the Current Version column has a warning icon, it means the timestamp of the version in the column Target Version is later and the session host needs to be updated.

Note

The first time you schedule an update, the settings you provide overwrite the default settings in the session host management policy. Subsequent updates will have those parameters pre-populated and any changes are saved.

Important

  • Once an update has been scheduled, you can't edit the schedule or settings. If you need to make any changes, you'll need to cancel the update and schedule a new one.

  • Don't remove any VMs from the host pool while the update is ongoing. Doing so may create issues with the ongoing update.

  • Don't change the drain mode of any VMs in the host pool while an update is ongoing. The drain mode of the VMs is automatically changed based on which stage of the update it is in. If a session host is not recoverable after an update, its drain mode setting will be enabled. Once the update is complete, the drain mode is reset.

  • It takes around 20 minutes for a session host to update. The number of session hosts that you specify in the batch size will be updated concurrently before moving on to the next batch. You should factor the overall completion time into your scheduled time.

Monitor the progress of an update

Once an update begins, you can check its progress. Select the relevant tab for your scenario and follow the steps.

Here's how to monitor the progress of an update using the Azure portal.

  1. From the Azure Virtual Desktop overview, select Host pools, then select the host pool you scheduled an update for.

  2. Select Session hosts.

  3. A blue banner provides the status of the update. It only shows a point in time, so you need to select Refresh to check the latest progress.

If you selected to start the update immediately, the message will state that the update is scheduled while it begins, but this message is updated once you refresh. During an update, you see the batch size number of session hosts that are removed from the host pool during the update.

Tip

You can also see the activity of an update using Azure Monitor activity log.

Pause, resume, cancel, or retry an update

You can pause, resume, or cancel an update that is in progress. If you pause or cancel an update, the current activity is completed before it pauses the rest of the update. For example, if a batch of session hosts is being updated, the update to these session hosts completes first. The blue banner showing the status of the update changes to show how far the update got when it paused. Once an update is paused, you can only resume it, which continues from the point it was paused.

If you don't resume an update within two weeks, the update is canceled. Once an update is canceled, you can't resume it.

Caution

If you cancel an update part way through, there will be differences between the session hosts in the host pool, such as a different operating system version, or joined to a different Active Directory domain. This may provide an inconsistent experience to users, so you will need to schedule another update as soon as possible to make sure there is parity across all session hosts.

Here's how to pause, resume, cancel, or retry an update using the Azure portal.

  1. From the Azure Virtual Desktop overview, select Host pools, then select the host pool you scheduled an update for.

  2. Select Session hosts, then select Manage session host update.

  3. Select Pause, Resume, Cancel, or Retry depending on the current state of the update.

  4. Select Refresh to update the status message in the blue banner. It can take approximately 20 seconds to show the correct status.

Next steps