Hydra 3.0.0 Hydra 2.9.0 Hydra 2.8.0 Hydra 2.7.0 Hydra 2.6.0
Auto Light Dark
Auto Light Dark
Hydra 3.0.0 Hydra 2.9.0 Hydra 2.8.0 Hydra 2.7.0 Hydra 2.6.0

Configuring Hydra to Support AVD Hybrid Environments

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) 

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 

  1. 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.

  1. 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:

  • HyperV (use this type for AVD Hybrid on Hyper-V)

  • AzureLocal (use this type for Azure Local)

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: “[]”).
Example: C:\LocalStorage\Images\Repository.json

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)
Example: "/subscriptions/12345678-1234-1234-1234-123456789ABC/resourceGroups/AVD.ARC-Hybrid/providers/Microsoft.HybridCompute/gateways/ARC-Gatway-EUS”

vSphere 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:

  • vSphere (use this type for vSphere)

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)
Example: "/subscriptions/12345678-1234-1234-1234-123456789ABC/resourceGroups/AVD.ARC-Hybrid/providers/Microsoft.HybridCompute/gateways/ARC-Gatway-EUS”

    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.

  1. Continue with Installing and Using the Hydra Proxy and skip the test of creating a local image on Azure Local. 

  2. Ensure that the Hydra Proxy is running. For testing purposes, we recommend running it as an administrator: 

Frame 2450.png

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: 

  1. Enable the validation environment option.

  2. 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.

  3. In the Azure Portal, enable the Host Pool's System-assigned managed identity for later use. To learn more, see the Microsoft documentation.

Frame 2440 (1).png
  1. 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. 

    1. Add a name, like ARC.Onboarding.

    2. Generate a secret and store it for later use. 

    3. Store the application ID for later use. 

  2. 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).

  3. 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: 

Frame 2441.png

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. 

  1. Create a new VM with your operating system on a Hyper-V node 

  2. Rename the computer hostname to match the name of the VM in Hyper-V (!) 

  3. Install necessary updates 

  4. Install your applications 

  5. Install the Azure Connected Machine Agent (ARC)

    1. Choose Onboard in the Azure Portal for more instructions: https://portal.azure.com/#servicemenu/Microsoft_Azure_ArcCenterUX/AzureArcCenterHub/servers

    2. 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: 

Frame 2442.png

Capturing an Image 

  1. 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”. 

  2. 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.

  3. Click Create Image to start the imaging process.

Frame 2443.png

The image is stored in the folder and added as an entry to the JSON file. Example: 

Frame 2444.png

Rolling Out a Host in a Pool 

  1. To adjust the rollout configuration in Hydra, click on the menu icon in the Host Pool tile:

Frame 2445.png
  1. 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: 

Frame 2446.png
  1. 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).

Frame 2447.png

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. 

  1. 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): 

Frame 2448.png

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.