Edit

Add session hosts to a host pool

  • Article

Important

Azure Virtual Desktop for Azure Stack HCI is currently in preview for Azure Government and Azure China. 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.

Once you've created a host pool, workspace, and an application group, you need to add session hosts to the host pool for your users to connect to. You may also need to add more session hosts for extra capacity.

You can create new virtual machines (VMs) to use as session hosts and add them to a host pool natively using the Azure Virtual Desktop service in the Azure portal. Alternatively you can also create VMs outside of the Azure Virtual Desktop service, such as with an automated pipeline, then add them as session hosts to a host pool. When using Azure CLI or Azure PowerShell you'll need to create the VMs outside of Azure Virtual Desktop, then add them as session hosts to a host pool separately.

For Azure Stack HCI, you can also create new VMs to use as session hosts and add them to a host pool natively using the Azure Virtual Desktop service in the Azure portal. Alternatively, if you want to create the VMs outside of the Azure Virtual Desktop service, see Create Arc virtual machines on Azure Stack HCI, then add them as session hosts to a host pool separately.

This article shows you how to generate a registration key using the Azure portal, Azure CLI, or Azure PowerShell, then how to add session hosts to a host pool using the Azure Virtual Desktop service or add them to a host pool separately.

Prerequisites

Review the Prerequisites for Azure Virtual Desktop for a general idea of what's required, such as operating systems, virtual networks, and identity providers. In addition, you'll need:

Important

If you want to create Microsoft Entra joined session hosts, we only support this using the Azure portal with the Azure Virtual Desktop service.

Generate a registration key

When you add session hosts to a host pool, first you'll need to generate a registration key. A registration key needs to be generated per host pool and it authorizes session hosts to join that host pool. It's only valid for the duration you specify. If an existing registration key has expired, you can also use these steps to generate a new key.

To generate a registration key, select the relevant tab for your scenario and follow the steps.

Here's how to generate a registration key using the Azure portal.

  1. Sign in to the Azure portal.

  2. In the search bar, type Azure Virtual Desktop and select the matching service entry.

  3. Select Host pools, then select the name of the host pool you want to generate a registration key for.

  4. On the host pool overview, select Registration key.

  5. Select Generate new key, then enter an expiration date and time and select OK. The registration key will be created.

  6. Select Download to download a text file containing the registration key, or copy the registration key to your clipboard to use later. You can also retrieve the registration key later by returning to the host pool overview.

Create and register session hosts with the Azure Virtual Desktop service

You can create session hosts and register them to a host pool in a single end-to-end process with the Azure Virtual Desktop service using the Azure portal or an ARM template. You can find some example ARM templates in our GitHub repo.

Important

If you want to create virtual machines using an alternative method outside of Azure Virtual Desktop, such as an automated pipeline, you'll need to register them separately as session hosts to a host pool. Skip to the section Register session hosts to a host pool.

Here's how to create session hosts and register them to a host pool using the Azure Virtual Desktop service in the Azure portal. Make sure you're generated a registration key first.

  1. Sign in to the Azure portal.

  2. In the search bar, enter Azure Virtual Desktop and select the matching service entry.

  3. Select Host pools, then select the name of the host pool you want to add session hosts to.

  4. On the host pool overview, select Session hosts, then select + Add.

  5. The Basics tab will be greyed out because you're using the existing host pool. Select Next: Virtual Machines.

  6. On the Virtual machines tab, complete the following information, depending on whether you want to create session hosts on Azure or Azure Stack HCI:

    To add session hosts on Azure, select to expand this section.
    Parameter Value/Description
    Resource group This automatically defaults to the same resource group as your host pool, but you can select an alternative existing one from the drop-down list.
    Name prefix Enter a name for your session hosts, for example hp01-sh.

    This value is be used as the prefix for your session hosts. Each session host has a suffix of a hyphen and then a sequential number added to the end, for example hp01-sh-0.

    This name prefix can be a maximum of 11 characters and is used in the computer name in the operating system. The prefix and the suffix combined can be a maximum of 15 characters. Session host names must be unique.
    Virtual machine location Select the Azure region where you want to deploy your session hosts. This must be the same region that your virtual network is in.
    Availability options Select from availability zones, availability set, or No infrastructure dependency required. If you select availability zones or availability set, complete the extra parameters that appear.
    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 images you've created and stored as an Azure Compute Gallery shared image or a managed image.
    Virtual machine size Select a SKU. If you want to use different SKU, select Change size, then select from the list.
    Hibernate (preview) Check the box to enable hibernate. Hibernate is only available for personal host pools. For more information, see Hibernation in virtual machines. If you're using Teams media optimizations you should update the WebRTC redirector service to 1.45.2310.13001.
    Number of VMs Enter the number of virtual machines you want to deploy. You can deploy up to 400 session hosts at this point if you wish (depending on your subscription quota), or you can add more later.

    For more information, see Azure Virtual Desktop service limits and Virtual Machines limits.
    OS disk type Select the disk type to use for your session hosts. We recommend only Premium SSD is used for production workloads.
    OS disk size Select a size for the OS disk.

    If you enable hibernate, ensure the OS disk is large enough to store the contents of the memory in addition to the OS and other applications.
    Confidential computing encryption If you're using a confidential VM, you must select the Confidential compute encryption check box to enable OS disk encryption.

    This check box only appears if you selected Confidential virtual machines as your security type.
    Boot Diagnostics Select whether you want to enable boot diagnostics.
    Network and security
    Virtual network Select your virtual network. An option to select a subnet appears.
    Subnet Select a subnet from your virtual network.
    Network security group Select whether you want to use a network security group (NSG).

    - None doesn't create a new NSG.

    - Basic creates a new NSG for the VM NIC.

    - Advanced enables you to select an existing NSG.

    We recommend that you don't create an NSG here, but create an NSG on the subnet instead.
    Public inbound ports You can select a port to allow from the list. Azure Virtual Desktop doesn't require public inbound ports, so we recommend you select No.
    Domain to join
    Select which directory you would like to join Select from Microsoft Entra ID or Active Directory and complete the relevant parameters for the option you select.

    To learn more about joining session hosts to Microsoft Entra ID, see Microsoft Entra joined session hosts.
    Virtual Machine Administrator account
    Username Enter a name to use as the local administrator account for the new session hosts.
    Password Enter a password for the local administrator account.
    Confirm password Reenter the password.
    Custom configuration
    Custom configuration script URL If you want to run a PowerShell script during deployment you can enter the URL here.
    To add session hosts on Azure Stack HCI, select to expand this section.
    Parameter Value/Description
    Resource group This automatically defaults to the resource group you chose your host pool to be in on the Basics tab, but you can also select an alternative.
    Name prefix Enter a name for your session hosts, for example hp01-sh.

    This value is used as the prefix for your session hosts. Each session host has a suffix of a hyphen and then a sequential number added to the end, for example hp01-sh-0.

    This name prefix can be a maximum of 11 characters and is used in the computer name in the operating system. The prefix and the suffix combined can be a maximum of 15 characters. Session host names must be unique.
    Virtual machine type Select Azure Stack HCI virtual machine.
    Custom location Select the Azure Stack HCI cluster where you want to deploy your session hosts from the drop-down list.
    Images Select the OS image you want to use from the list, or select Manage VM images to manage the images available on the cluster you selected.
    Number of VMs Enter the number of virtual machines you want to deploy. You can add more later.
    Virtual processor count Enter the number of virtual processors you want to assign to each session host. This value isn't validated against the resources available in the cluster.
    Memory type Select Static for a fixed memory allocation, or Dynamic for a dynamic memory allocation.
    Memory (GB) Enter a number for the amount of memory in GB you want to assign to each session host. This value isn't validated against the resources available in the cluster.
    Network and security
    Network dropdown Select an existing network to connect each session to.
    Domain to join
    Select which directory you would like to join Active Directory is the only available option.
    AD domain join UPN Enter the User Principal Name (UPN) of an Active Directory user that has permission to join the session hosts to your domain.
    Password Enter the password for the Active Directory user.
    Specify domain or unit Select yes if you want to join session hosts to a specific domain or be placed in a specific organization unit (OU). If you select no, the suffix of the UPN will be used as the domain.
    Virtual Machine Administrator account
    Username Enter a name to use as the local administrator account for the new session hosts.
    Password Enter a password for the local administrator account.
    Confirm password Reenter the password.

    Once you've completed this tab, select Next: Tags.

  7. On the Tags tab, you can optionally enter any name/value pairs you need, then select Next: Review + create.

  8. On the Review + create tab, ensure validation passes and review the information that will be used during deployment. If validation doesn't pass, review the error message and check what you entered in each tab.

  9. Select Create. Once your deployment is complete, the session hosts should appear in the host pool.

Important

Once you've added session hosts with the Azure Virtual Desktop service, skip to the section Post deployment for some extra configuration you may need to do.

Register session hosts to a host pool

If you created virtual machines using an alternative method outside of Azure Virtual Desktop, such as an automated pipeline, you'll need to register them separately as session hosts to a host pool. To register session hosts to a host pool, you need to install the Azure Virtual Desktop Agent and the Azure Virtual Desktop Agent Bootloader on each virtual machine and use the registration key you generated. You can register session hosts to a host pool using the agent installers' graphical user interface (GUI) or using msiexec from a command line. Once complete, four applications will be listed as installed applications:

  • Remote Desktop Agent Boot Loader.
  • Remote Desktop Services Infrastructure Agent.
  • Remote Desktop Services Infrastructure Geneva Agent.
  • Remote Desktop Services SxS Network Stack.

Select the relevant tab for your scenario and follow the steps.

  1. Make sure the virtual machines you want to use as session hosts are joined to Microsoft Entra ID or an Active Directory domain (AD DS or Microsoft Entra Domain Services).

  2. If your virtual machines are running a Windows Server OS, you'll need to install the Remote Desktop Session Host role, then restart the virtual machine. For more information, see Install roles, role services, and features by using the add Roles and Features Wizard.

  3. Sign in to your virtual machine as an administrator.

  4. Download the Agent and the Agent Bootloader installation files using the following links You may need to unblock them; right-click each file and select Properties, then select Unblock, and finally select OK.

    Tip

    The Azure Virtual Desktop Agent download link is for the latest production version in non-validation environments. This download link is updated once the automatic production rollout is complete, so you might see a delay between a production version being released and the download link being updated. Once the Azure Virtual Desktop Agent is installed, it's updated automatically. For more information about the rollout of new versions of the agent, see What's new in the Azure Virtual Desktop Agent.

  5. Run the Microsoft.RDInfra.RDAgent.Installer-x64-<version>.msi file to install the Remote Desktop Services Infrastructure Agent.

  6. Follow the prompts and when the installer prompts for the registration token, paste it into the text box, which will appear on a single line. Select Next, then complete the installation.

    Screenshot showing where to paste the registration token

  7. Run the Microsoft.RDInfra.RDAgentBootLoader.Installer-x64.msi file to install the remaining components.

  8. Follow the prompts and complete the installation.

  9. After a short time, the virtual machines should now be listed as session hosts in the host pool. The status of the session hosts may initially show as Unavailable and if there is a newer agent version available, it will upgrade automatically.

  10. Once the status of the session hosts is Available, restart the virtual machines.

Post deployment

After you've added session hosts to your host pool, there's some extra configuration you may need to do, which is covered in the following sections.

Licensing

To ensure your session hosts have licenses applied correctly, you'll need to do the following tasks:

  • If you have the correct licenses to run Azure Virtual Desktop workloads, you can apply a Windows or Windows Server license to your session hosts as part of Azure Virtual Desktop and run them without paying for a separate license. This is automatically applied when creating session hosts with the Azure Virtual Desktop service, but you may have to apply the license separately if you create session hosts outside of Azure Virtual Desktop. For more information, see Apply a Windows license to session host virtual machines.

  • If your session hosts are running a Windows Server OS, you'll also need to issue them a Remote Desktop Services (RDS) Client Access License (CAL) from a Remote Desktop Licensing Server. For more information, see License your RDS deployment with client access licenses (CALs).

  • For session hosts on Azure Stack HCI, you must license and activate the virtual machines you use before you use them with Azure Virtual Desktop. For activating Windows 10 and Windows 11 Enterprise multi-session, and Windows Server 2022 Datacenter: Azure Edition, use Azure verification for VMs. For all other OS images (such as Windows 10 and Windows 11 Enterprise, and other editions of Windows Server), you should continue to use existing activation methods. For more information, see Activate Windows Server VMs on Azure Stack HCI.

Microsoft Entra joined session hosts

If your users are going to connect to session hosts joined to Microsoft Entra ID, you'll also need to enable single sign-on or legacy authentication protocols, assign an RBAC role to users, and review your multifactor authentication policies so they can sign in to the VMs.

For more information about using Microsoft Entra joined session hosts, see Microsoft Entra joined session hosts.

Next steps

Now that you've expanded your existing host pool, you can sign in to an Azure Virtual Desktop client to test them as part of a user session. You can connect to a session with any of the following clients: