Add session hosts to a host pool

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 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 virtual machines outside of the Azure Virtual Desktop service, such as 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 virtual machines outside of Azure Virtual Desktop, 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 adding 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 Azure Active Directory-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:

    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 aad-hp01-sh.

    This will be used as the prefix for your session host VMs. Each session host has a suffix of a hyphen and then a sequential number added to the end, for example aad-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 your session host VMs will be deployed. 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.
    Number of VMs Enter the number of virtual machines you want to deploy. You can deploy up to 400 session host VMs 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.
    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 will appear.
    Subnet Select a subnet from your virtual network.
    Network security group Select whether you want to use a network security group (NSG).

    - Basic will create a new NSG for the VM NIC.

    - Advanced enables you to select an existing NSG.
    Public inbound ports We recommend you select No.
    Domain to join
    Select which directory you would like to join Select from Azure Active Directory or Active Directory and complete the relevant parameters for the option you select.

    To learn more about joining session hosts to Azure AD, see Azure AD-joined session hosts.
    Virtual Machine Administrator account
    Username Enter a name to use as the local administrator account for the new session host VMs.
    Password Enter a password for the local administrator account.
    Confirm password Re-enter the password.
    Custom configuration
    ARM template file URL If you want to use an extra ARM template during deployment you can enter the URL here.
    ARM template parameter file URL Enter the URL to the parameters file for the ARM template.

    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 Azure Active Directory or an Active Directory domain (AD DS or Azure AD DS).

  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

    This is the latest downloadable version of the Azure Virtual Desktop Agent in non-validation environments. 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).

Azure AD-joined session hosts

If your users are going to connect to session hosts joined to Azure Active Directory, you'll need to do the following tasks:

  • If your users are going to connect to session hosts joined to Azure Active Directory, you must assign them the Virtual Machine User Login or Virtual Machine Administrator Login RBAC role either on each virtual machine, the resource group containing the virtual machines, or the subscription. We recommend you assign the Virtual Machine User Login RBAC role on the resource group containing your session hosts to the same user group as you assign to the application group. For more information, see Log in to a Windows virtual machine in Azure by using Azure AD.

  • For users connecting from Windows devices that aren't joined to Azure AD or non-Windows devices, add the custom RDP property targetisaadjoined:i:1 to the host pool's RDP properties. These connections are restricted to entering user name and password credentials when signing in to a session host. For more information, see Customize RDP properties for a host pool.

For more information about using session hosts joined to Azure AD, see Azure AD-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: