Add session hosts to a host pool

Article
07/11/2023

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:

An existing host pool.
If you have existing session hosts in the host pool, make a note of the virtual machine size, the image, and name prefix that was used. All session hosts in a host pool should be the same configuration, including the same identity provider. For example, a host pool shouldn't contain some session hosts joined to Azure AD and some session hosts joined to an Active Directory domain.

The Azure account you use must have the following built-in role-based access control (RBAC) roles as a minimum on the resource group:

Action	RBAC role(s)
Generate a host pool registration key	Desktop Virtualization Host Pool Contributor
Create and add session hosts using the Azure portal	Desktop Virtualization Host Pool Contributor Virtual Machine Contributor

Alternatively you can assign the Contributor RBAC role.

Don't disable Windows Remote Management (WinRM) when creating and adding session hosts using the Azure portal, as it's required by PowerShell DSC.
If you want to use Azure CLI or Azure PowerShell locally, see Use Azure CLI and Azure PowerShell with Azure Virtual Desktop to make sure you have the desktopvirtualization Azure CLI extension or the Az.DesktopVirtualization PowerShell module installed. Alternatively, use the Azure Cloud Shell.

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.

Sign in to the Azure portal.
In the search bar, type Azure Virtual Desktop and select the matching service entry.
Select Host pools, then select the name of the host pool you want to generate a registration key for.
On the host pool overview, select Registration key.
Select Generate new key, then enter an expiration date and time and select OK. The registration key will be created.
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.

Here's how to generate a registration key using the desktopvirtualization extension for Azure CLI.

Important

In the following examples, you'll need to change the <placeholder> values for your own.

Launch the Azure Cloud Shell in the Azure portal with the Bash terminal type, or run Azure CLI on your local device.
1. If you're using Cloud Shell, make sure your Azure context is set to the subscription you want to use.
2. If you're using Azure CLI locally, first Sign in with Azure CLI, then make sure your Azure context is set to the subscription you want to use.

Use the az desktopvirtualization workspace update command with the following example to generate a registration key that is valid for 24 hours.

az desktopvirtualization hostpool update \
    --name <Name> \
    --resource-group <ResourceGroupName> \
    --registration-info expiration-time=$(date -d '+24 hours' --iso-8601=ns) registration-token-operation="Update"

Get the registration key and copy it to your clipboard to use later. You can also retrieve the registration key later by running this command again anytime while the registration key is valid.
```
az desktopvirtualization hostpool retrieve-registration-token \
    --name <Name> \
    --resource-group <ResourceGroupName> \
    --query token --output tsv
```

Here's how to generate a registration key using the Az.DesktopVirtualization PowerShell module.

Important

In the following examples, you'll need to change the <placeholder> values for your own.

Launch the Azure Cloud Shell in the Azure portal with the PowerShell terminal type, or run PowerShell on your local device.
1. If you're using Cloud Shell, make sure your Azure context is set to the subscription you want to use.
2. If you're using PowerShell locally, first Sign in with Azure PowerShell, then make sure your Azure context is set to the subscription you want to use.

Use the New-AzWvdRegistrationInfo cmdlet with the following example to generate a registration key that is valid for 24 hours.

$parameters = @{
    HostPoolName = '<HostPoolName>'
    ResourceGroupName = '<ResourceGroupName>'
    ExpirationTime = $((Get-Date).ToUniversalTime().AddHours(24).ToString('yyyy-MM-ddTHH:mm:ss.fffffffZ'))
}

New-AzWvdRegistrationInfo @parameters

Get the registration key and copy it to your clipboard to use later. You can also retrieve the registration key later by running this command again anytime while the registration key is valid.
```
$parameters = @{
    HostPoolName = '<HostPoolName>'
    ResourceGroupName = '<ResourceGroupName>'
}

(Get-AzWvdHostPoolRegistrationToken @parameters).Token
```

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.

Sign in to the Azure portal.
In the search bar, enter Azure Virtual Desktop and select the matching service entry.
Select Host pools, then select the name of the host pool you want to add session hosts to.
On the host pool overview, select Session hosts, then select + Add.
The Basics tab will be greyed out because you're using the existing host pool. Select Next: Virtual Machines.

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.

On the Tags tab, you can optionally enter any name/value pairs you need, then select Next: Review + create.
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.
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.

GUI
Command line

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).
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.
Sign in to your virtual machine as an administrator.
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.
- Azure Virtual Desktop Agent
- Azure Virtual Desktop Agent Bootloader
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.
Run the Microsoft.RDInfra.RDAgent.Installer-x64-<version>.msi file to install the Remote Desktop Services Infrastructure Agent.
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.
Run the Microsoft.RDInfra.RDAgentBootLoader.Installer-x64.msi file to install the remaining components.
Follow the prompts and complete the installation.
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.
Once the status of the session hosts is Available, restart the virtual machines.

Using msiexec enables you to install the agent and boot loader from the command line using automated deployment tools, such as Intune or Configuration Manager from Microsoft Endpoint Manager.

Important

In the following examples, you'll need to change the <placeholder> values for your own.

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).
If your virtual machines are running a Windows Server OS, you'll need to install the Remote Desktop Session Host role by running the following command as an administrator, which will also restart the virtual machines:
```
Install-WindowsFeature -Name RDS-RD-Server -Restart
```

Download the Agent and the Agent Bootloader installation files and unblock them by running the following commands. The files will be downloaded to the current working directory.

$uris = @(
    "https://query.prod.cms.rt.microsoft.com/cms/api/am/binary/RWrmXv"
    "https://query.prod.cms.rt.microsoft.com/cms/api/am/binary/RWrxrH"
)

$installers = @()
foreach ($uri in $uris) {
    $download = Invoke-WebRequest -Uri $uri -UseBasicParsing

    $fileName = ($download.Headers.'Content-Disposition').Split('=')[1].Replace('"','')
    $output = [System.IO.FileStream]::new("$pwd\$fileName", [System.IO.FileMode]::Create)
    $output.write($download.Content, 0, $download.RawContentLength)
    $output.close()
    $installers += $output.Name
}

foreach ($installer in $installers) {
    Unblock-File -Path "$installer"
}

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.

To install the Remote Desktop Services Infrastructure Agent, run the following command as an administrator:

msiexec /i Microsoft.RDInfra.RDAgent.Installer-x64-<version>.msi /quiet REGISTRATIONTOKEN=<RegistrationToken>

To install the remaining components, run the following command as an administrator:
```
msiexec /i Microsoft.RDInfra.RDAgentBootLoader.Installer-x64.msi /quiet
```
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.
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:

Add session hosts to a host pool

Prerequisites

Generate a registration key

Create and register session hosts with the Azure Virtual Desktop service

Register session hosts to a host pool

Post deployment

Licensing

Azure AD-joined session hosts

Next steps

Feedback

Additional resources

Additional resources