Note: As of Hydra version 3.0.0, AVD Hybrid support with Microsoft Hyper-V and VMware vSphere is generally available.
Using the Hydra Proxy
The Hydra Proxy feature is used to perform operations on-premises on behalf of the Hydra instance running in Azure. For more information on Hydra Proxy, see Installing and Using the Hydra Proxy (Preview).
When using AVD Hybrid, the Hydra Proxy is responsible for:
-
Starting VMs
-
Stopping VMs
-
Restarting VMs
-
Deleting VMs and their disks
-
Creating new VMs / session hosts, including
-
Azure Connected Machine Agent (ARC) Installation
-
Azure Virtual Desktop (AVD) Agent
-
Domain join (AD and Entra)
-
Azure Monitoring Agent (if selected)
-
-
Imaging of existing Golden Master VMs (note: a Golden Master VM must have the ARC agent installed)
-
Etc.
Grouping Hybrid Locations in Hydra Proxy Configuration File
The Hydra Proxy can handle multiple groups of Hyper-V or vSphere nodes (servers) as a “Hybrid Location”. All nodes in a group are represented by their Location ID. That is similar to custom locations as it relates to Azure Local. The group of nodes can also be part of a failover cluster.
Note: Don’t mix clusters and nodes across different Hybrid Locations.
Preparing Hyper-V Nodes
All Cluster Nodes and stand-alone Hyper-V servers must be configured similarly:
-
At least one Network Switch with the same name across all nodes
-
One or more local folders to store the virtual machines. (Note: SYSTEM, SERVICE, and Administrators should have FULL CONTROL access to those folders):
-
C:\LocalStorage (for nodes without cluster shares)
-
C:\ClusterStorage\UserStorage_1 (for nodes with cluster shares)
Preparing an Image Gallery for Hyper-V
Hyper-V Virtual Machine images are sysprep’d VHDX files. Hydra needs a shared resource to store those files. For a stand-alone Hyper-V server Hybrid Location, a local folder would work. For clusters with multiple nodes, use a cluster share, or a share on a file server. (Note: SYSTEM, SERVICE, and Administrators should have FULL CONTROL access to those folders). If a network share is used, add the Everyone full permission (to let the NTFS permission apply). To access the network share, each node needs permission to this share in the right context.
Examples:
-
C:\LocalStorage\Images
-
C:\ClusterStorage\UserStorage_1\Images
Installing the Hydra Proxy
-
To start, enable and install the Hydra Proxy (always use the latest version to ensure full functionality). For steps, see Installing and Using the Hydra Proxy.
Note: Follow the documentation through the step that creates the HydraProxy.json file. Then, continue to step 2 below.
-
For AVD Hybrid, add a new custom location.
Here is an example for both Hyper-V and vSphere locations:
{
"CustomLocations":[
{
“Enabled”:True,
"LocationType":"HyperV",
"LocationId":"almere-datacenter",
"LocationName":"Almere",
"ClusterName":"HYPERV-ALMERE.almere.nl",
"ClusterNodes":[
"HYPERV-ALMERE-0.almere.nl",
"HYPERV-ALMERE-1.almere.nl",
"HYPERV-ALMERE-2.almere.nl"
],
"ClusterShares":[
"C:\\LocalStorage",
"D:\\ClusterStorage\\UserStorage_2"
],
"Networks":[
{
"Name":"External-vSwitch"
},
{
"Name":"Internal High Security"
}
],
"ImageGalleries":[
{
"Name":"Default",
"GalleryLibraryPath":"C:\\LocalStorage\\Images\\Repository.json"
},
{
"Name":"AdvancedRemote",
"GalleryLibraryPath":"C:\\LocalStorage\\Images\\Repository-Secure.json"
},
{
"Name":"On-Share",
"GalleryLibraryPath":"\\\\HYPERV-ALMERE-0\\Images-FileShare\\Repository-Share.json"
}
]
},
{
“Enabled”:True,
"LocationType": "vSphere",
"LocationId": "almere-vsphere-01",
"LocationName": "Almere vSphere",
"ClusterName": "almlabvc01.lvsilabs.com",
"ApiVersion": "8.0.3.0",
"ApiIgnoreCertificateErrors": true,
"Networks": [
{ "Name": "VM Network" },
{ "Name": "VM Network with display name", "ID": "network-14" },
{ "Name": "DPortGroup",
"WebProxy": {"Url" : "http://192.168.111.1:8080"},
"ArcGatewayId": "/subscriptions/12345678-1234-1234-1234-123456789ABC/resourceGroups/AVD.ARC-Hybrid/providers/Microsoft.HybridCompute/gateways/ARG-GateWay-WEU"
}
],
"ClusterShares": [
"datastore1",
"datastore2"
],
"ClusterNodes": [
"AVD-Hosts",
"Templates for AVD",
"Test"
],
"ImageGalleries": [
{
"Name": "Default"
}
]
}
]
}
Hyper-V custom location properties:
|
Property |
Description |
|---|---|
|
Enabled |
Enables the location in Hydra Proxy. (optional) This setting is only read when Hydra Proxy starts. (true or false) |
|
LocationType |
The configuration type for different environments. Choices are currently:
|
|
LocationId |
A given name of the location: LocationId can only include alphanumeric, underscore, parentheses, hyphen, period (except at end), and Unicode characters that match the allowed URL-safe characters. |
|
LocationName |
A given short name. |
|
ClusterName |
If a failover cluster is representing the Hybrid Location, use the FQDN of the failover cluster. Otherwise, leave the value empty. (Also handle this name like the cluster nodes in the documentation (giving permission) – Note: We will add the functionality to publish a VM to the failover cluster soon. |
|
ClusterNodes |
Specifies the fully qualified domain names (FQDN) of the nodes / Hyper-V servers |
|
ClusterShares |
A list of the local folders or cluster shares. See Preparation of Hyper-V nodes |
|
ImageGalleries |
A list of image galleries |
|
ImageGallery.Name |
A given name of the location: ImageGallery.Name can only include alphanumeric, underscore, parentheses, hyphen, period (except at end), and Unicode characters that match the allowed URL-safe characters. |
|
ImageGallery.GalleryLibraryPath |
Path to the folder for the gallery, including the name of a JSON file. This file will contain the content of the gallery. The JSON file must not exist. It will be created automatically (or add an empty text file with an open and closed square bracket: “[]”).
|
|
Networks |
A list of the network switches. Each node must have a switch with the same name. |
|
Network.Name |
Name of the network switch |
|
WebProxy |
Adds the URL and port for the Web proxy (optional) |
|
ArcGatewayId |
Adds the ArcGatewayId URI. (optional)
|
vSphere custom location properties:
|
Property |
Description |
|---|---|
|
Enabled |
Enables the location in Hydra Proxy. (optional)
|
|
LocationType |
The configuration type for different environments. Choices are currently:
|
|
LocationId |
A given name of the location: LocationId can only include alphanumeric, underscore, parentheses, hyphen, period (except at end), and Unicode characters that match the allowed URL-safe characters. |
|
LocationName |
A given short name. |
|
ClusterName |
The FQDN of the vSphere management server |
|
ApiVersion |
vSphere API Version. (e.g., 8.0.3.0) |
|
ApiIgnoreCertificateErrors |
Ignore certificate errors (true or false) |
|
ClusterShares |
A list of the datastore names: “datastore1”, “datastore2” |
|
ImageGalleries |
A list of strings, representing the folder in vSphere to create resources |
|
ImageGallery.Name |
Currently fixed: "Name": "Default" |
|
Networks |
A list of the network switches |
|
Name |
Name of the network switch. If used in combination with ID property, it can be used as a friendly DisplayName. |
|
WebProxy |
Adds the URL and port for the Web proxy (optional) |
|
ArcGatewayId |
Adds the ArcGatewayId URI. (optional)
|
|
ID |
The optional ID of the network. When used, it converts the Name property to a display name, which is useful in environments with duplicate network names. To get this ID, navigate to the network or port group and you will see it in the web browser URL, such as network-14. |
-
Continue with Installing and Using the Hydra Proxy and skip the test of creating a local image on Azure Local.
-
Ensure that the Hydra Proxy is running. For testing purposes, we recommend running it as an administrator:
Configuring permissions
The Hydra proxy needs access to the resources on Hyper-V and/or to vSphere. Besides the option of using CMDKEY to store the credentials per Hyper-V node and failover server, we recommend giving the account running the Hydra Proxy the needed permissions or giving it explicit credentials.
Needed permissions:
-
Hyper-V: Administrative permissions to each node and, if used, to the failover cluster server
-
vSphere: Create a new account in vSphere with the proper permissions. We require the same permissions as a typical linked/instant clone deployment, so feel free to use Omnissa’s vCenter permissions doc for least-privileged access.
-
Make sure to update the password if needed in vSphere and Hyper-V
If not configured, the Hydra Proxy would use the current credentials to access Hyper-V nodes, shares, and a failover cluster (if necessary).
Configuring explicit accounts to access resources
Same context / running Hydra Proxy interactively
We can configure explicit credentials for each Hydra Proxy location by running the following command in the same context:
HydraAgent.exe ProxyAuthenticationCurrent set "Germany-NRW-DC01" ".\HyperVAdmin" "SuperSecretPassword"
We can also overwrite this configuration by running “set” again, or delete it by running:
HydraAgent.exe ProxyAuthenticationCurrent delete "Germany-NRW-DC01"
We can list all settings by running (passwords are not displayed):
HydraAgent.exe ProxyAuthenticationCurrent list
That data is stored in the Windows Credential Manager and used if available for a custom location.
For vSphere: This data is mandatory and used to authenticate against vSphere. E.g.:
HydraAgent.exe ProxyAuthenticationCurrent set "Germany-NRW-VS01" ".\vSphereHydraProxy" "SuperSecretPassword"
Setting the credentials for the scheduled task
The Hydra Proxy usually runs as a scheduled task. The scheduled task context differs from the administrator configuring the Hydra Proxy. To add/delete/list location-based credentials for a running Hydra Proxy process, we can use the following commands as a local administrator:
HydraAgent.exe ProxyAuthentication set "Germany-NRW-DC01" ".\HyperVAdmin" "SuperSecretPassword"
We can also overwrite this configuration by running “set” again, or delete it by running:
HydraAgent.exe ProxyAuthentication delete "Germany-NRW-DC01"
We can list all settings by running (passwords are not displayed):
HydraAgent.exe ProxyAuthentication list
Note: In addition, a local administrator can connect to the log stream by running
HydraAgent.exe ShowLogs
Configuring a Host Pool for AVD Hybrid
Create a new Host Pool for your AVD Hybrid deployment in Hydra (Azure Resource > Virtual Desktop) or in the Azure Portal. Please ensure the following configurations:
-
Enable the validation environment option.
-
If not already done, grant the Hydra service principal the appropriate permissions (such as our custom role Hydra - Resource Access Role). For more information on roles, see Assigning Roles in Hydra.
-
In the Azure Portal, enable the Host Pool's System-assigned managed identity for later use. To learn more, see the Microsoft documentation.
-
If you haven’t already, create a service principal with a secret in https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApp. The new service principal is needed for the automated ARC deployment.
-
Add a name, like ARC.Onboarding.
-
Generate a secret and store it for later use.
-
Store the application ID for later use.
-
-
Create or use a resource group for our ARC objects and add the account ARC.Onboarding (from the previous step) to the resource group with the role “Azure Connected Machine Onboarding” (for a new resource group, also add the Hydra service principal).
-
Add the managed identity of the Host Pool as a “Reader” to the resource group for the ARC objects.
Example: Permissions on the resource group for the ARC objects:
Preparing a Golden Master
Before we can capture an image to roll out new session hosts, we need a new Golden Master VM on one of our nodes. If you want to use Entra ID-only joined hosts, we recommend Windows Server 2025.
-
Create a new VM with your operating system on a Hyper-V node
-
Rename the computer hostname to match the name of the VM in Hyper-V (!)
-
Install necessary updates
-
Install your applications
-
Install the Azure Connected Machine Agent (ARC)
-
Choose Onboard in the Azure Portal for more instructions: https://portal.azure.com/#servicemenu/Microsoft_Azure_ArcCenterUX/AzureArcCenterHub/servers
-
If asked for a resource group to store the ARC object, select the same resource group referenced in “Configuring a Host Pool for AVD Hybrid.”
-
The ARC object should be visible in Azure:
Capturing an Image
-
Go to Imaging in Hydra and select your tenant. If the Hydra Proxy is connected and configured successfully, you should be able to select your Hybrid Location in the drop-down list “Hybrid Location”.
-
After that, select your Golden Master from the Virtual Machine list and your Target Image Gallery (that is the name from your HydraProxy.json configuration):
Note: vSphere also allows you to create snapshot images by selecting the checkbox. Those images always create linked-clone virtual machines later. -
Click Create Image to start the imaging process.
The image is stored in the folder and added as an entry to the JSON file. Example:
Rolling Out a Host in a Pool
-
To adjust the rollout configuration in Hydra, click on the menu icon in the Host Pool tile:
-
Selecting a network switch from Hyper-V is the trigger for Hydra to let you configure the settings related to AVD Hybrid. You can find the switches (similar to the name in the HydraProxy.json) at the bottom of the list:
-
Fill out the missing parameters to describe how a session host should be built in this pool. There are some AVD Hybrid-specific settings in Host Pool Configuration > New Session Host Rollout:
Hyper-V configuration
|
Field |
Description |
|
Image |
Contains a list of images available for the Hybrid Location |
|
Cluster Storage Path |
A list of available storage paths. Auto can be used to let Hydra decide where to store the data of the next VM. |
|
Node |
A specific node or auto. Auto will use the host with the least amount of VMs. |
|
Service principal for ARC join |
The service principal and secret from the step before to join a computer as an ARC object (the resource group is the target for the ARC object). |
vSphere configuration
|
Field |
Description |
|
Image |
Contains a list of images and deployable snapshots available for the Hybrid Location. Deployable snapshots create linked-clones. |
|
Data Store |
A list of data stores. Auto can be used to let Hydra decide where to store the data of the next VM. |
|
Folder |
A list of folders (configure in Hydra Proxy) to store the new hosts to. |
|
Service principal for ARC join |
The service principal and secret from the step before to join a computer as an ARC object (the resource group is the target for the ARC object). |
Note: In New Session Host Rollout > Advanced Settings, there is an option to use an incremental disk. We don’t suggest this for performance reasons.
The local administrator's name is not forced yet. It will be inherited from the Golden Master. All local administrators on the newly deployed session hosts will get the new administrator password.
-
Click Save to apply the changes.
Rolling Out New Hosts: Starting, Stopping, Restarting
Clicking on the Host Pool tile opens the session host list. There are several actions to start, stop, restart, or roll out a new host (similar to native Azure Virtual Machines):
Known limitations
-
Currently only working in Azure Global (not GOV-cloud tenants)
-
The configured local admin username for a rollout is ignored. The name is the same as on the Golden Master (Administrator)
-
All local administrator accounts of the Golden Master are reset to the configured local admin password
-
Hybrid images do not (yet) show up in Hydra’s Image Inventory page
Notes from the Field
-
Ensure Bitlocker is completely disabled and prevent it from running on the image in order for sysprep to function. Encrypting the disk is unfortunately Windows 11’s default behavior when a vTPM is detected.
-
Before kicking off an image capture, shut down the golden VM. Wait until the Arc VM status shows “Offline.” Kicking off a capture while the VM is powered on or showing Online in Arc will cause Hydra to immediately attempt a Run command on the VM, which will fail with a HCRP500 error.
-
In legacy Hydra deployments, the default value for “Use the remote script engine for Hybrid VMs if size is higher then” setting is 0. Ensure this is set to 400 for the generalization scripts to work correctly. If set to 0, you will receive a HCRP500 about 10-15 minutes into the VM capture process.