Citrix Integration with Azure Local for Linux workload (Preview)

March 21, 2025

Contributed by:

Azure Local is a hyper-converged infrastructure (HCI) solution that connects the on-premises system to Azure for cloud-based services, monitoring, and management.

With this feature, MCS supports Azure Local as a new platform, and thus supports:

Provisioning of Azure Arc-enabled Linux VMs on Azure Local.
Power management of Linux VMs created on Azure Local.

Benefits

Hybrid Cloud Integration: Seamlessly combine your on-premises infrastructure with Azure cloud services, enabling a hybrid environment that boosts flexibility and performance.
Data Sovereignty compliance: Keep your data on-premises while using cloud services, ensuring compliance with data sovereignty regulations and providing enhanced control over your data.
Unified VM provisioning and management: Simplify the provisioning and management of your VMs, offering a cohesive approach to managing both on-premises and cloud resources.

Known issues

Only one storage location can be selected for both OS and temporary storage when creating a hosting connection.
When powering on MCS provisioned non-persistent Azure Arc VMs, the power states in both the Azure portal and Studio UI might not refresh immediately. During this time, the VMs run in the cluster and register to the Delivery Controller, even though the power states might still be displayed as “Powering on”.
After you create a new catalog or update an existing one, a new Azure Arc gallery image is created as the base image. MCS cleans any outdated Azure Arc gallery images, however, due to a Microsoft issue, those outdated images are not deleted. As a workaround, manually delete the images from the Azure Compute Gallery using the Azure portal or CLI.
If you select to use Citrix managed resource group (that is, not an existing resource group) when creating the machine catalog, the Citrix created resource group (prefixed with citrix-xd-) is not deleted when you delete the catalog. This behavior is because the Azure Arc gallery images are not deleted inside the resource group.

Participate in Tech Preview

If you’re interested in participating in the Tech Preview, provide your contact information here.

Prerequisites

Citrix DaaS only.
VDA version: 2407 or later
Azure Local cluster version: 23H2
- Storage path created
- Logical network created with DHCP enabled
To deploy an Azure Local cluster, refer to the Microsoft documentation About Azure Local deployment.

Key steps

Following are the key steps to create an MCS catalog in the Azure Local cluster:

Prepare a master image.
Create a host connection and hosting unit.
Create an MCS catalog in the Azure Local cluster using PowerShell.

Note:

You can currently create Linux VM catalogs using only the PowerShell command. See Create an MCS catalog in the Azure Local cluster using PowerShell.

Prepare a master image

MCS uses the Azure Arc gallery image as the master image. Before using MCS to provision workload in the Azure Local cluster, prepare an Azure Arc gallery image with VDA installed.

For Linux-based master image, see Create Linux VDAs using Machine Creation Services (MCS) to prepare an MCS master VM and follow Prepare a Linux image for Azure Local virtual machines to create an Azure Arc gallery image.

Create a host connection and hosting unit

Use PowerShell commands to create host connection and hosting unit.

Header of the script

Make sure that you provide the correct parameter values defined in the header of the script.

$azureSubscription = "" # Azure Subscription ID
$azureTenantId = "" # Azure AD Tenant ID
$appClientId = "" # Client ID of an Azure AD application which is grant with sufficient permissions
$appClientSecret = "" # Client secret of above client ID
$appClientSecretExpirationDateTimestamp = "" # Client secret expiration date in epoch timestamp format
$region = "" # Azure region of your Azure Local cluster
$resourceGroupName = "" # Azure resource group of your Azure Local cluster
$clusterName = "" # Name of your Azure Local cluster
$storagePathName = "" # Storage path in your Azure Local cluster that want to be used in this hosting unit
$logicalNetworkName = "" # Logical network in your Azure Local cluster that want to be used in this hosting unit
$zoneUid = "" # Zone UID of your resource location
$hostingConnectionName = "" # Name of the created hosting connection
$hostingUnitName = "" # Name of the created hosting unit
 

Create a host connection

asnp Citrix.Host.Admin.V2
[SecureString]$appClientSecretSecureString = $appClientSecret | ConvertTo-SecureString -AsPlainText -Force
$conn = New-Item -ConnectionType "Custom" -CustomProperties "<CustomProperties xmlns=`"http://schemas.citrix.com/2014/xd/machinecreation`" xmlns:xsi=`"http://www.w3.org/2001/XMLSchema-instance`"><Property xsi:type=`"StringProperty`" Name=`"SubscriptionId`" Value=`"$azureSubscription`" /><Property xsi:type=`"StringProperty`" Name=`"ManagementEndpoint`" Value=`"https://management.azure.com/`" /><Property xsi:type=`"StringProperty`" Name=`"AuthenticationAuthority`" Value=`"https://login.microsoftonline.com/`" /><Property xsi:type=`"StringProperty`" Name=`"TenantId`" Value=`"$azureTenantId`" /></CustomProperties>" -HypervisorAddress @("https://management.azure.com/") -Path @("XDHyp:\Connections\$hostingConnectionName") -Persist -PluginId "AzureArcFactory" -Scope @() -SecurePassword $appClientSecretSecureString -UserName $appClientId -ZoneUid $zoneUid
New-BrokerHypervisorConnection -HypHypervisorConnectionUid $conn.HypervisorConnectionUid
Set-HypHypervisorConnectionMetadata -HypervisorConnectionUid $conn.HypervisorConnectionUid -Name Citrix_Orchestration_Hypervisor_Secret_Allow_Edit -Value true
Set-HypHypervisorConnectionMetadata -HypervisorConnectionUid $conn.HypervisorConnectionUid -Name Citrix_Orchestration_Hypervisor_Secret_Expiration_Date -Value $appClientSecretExpirationDateTimestamp
 

Create a hosting unit

$guid = (New-Guid).Guid
New-HypStorage -StoragePath @("XDHyp:\Connections\$hostingConnectionName\$region.region\$resourceGroupName.resourcegroup\cluster.folder\$clusterName.cluster\storage.folder\$storagePathName.storage") -StorageType "TemporaryStorage" -JobGroup $guid

New-Item -Path XDHyp:\HostingUnits -Name $hostingUnitName -HypervisorConnectionName $hostingConnectionName -RootPath "XDHyp:\Connections\$hostingConnectionName\$region.region\$resourceGroupName.resourcegroup\cluster.folder\$clusterName.cluster" -NetworkPath "XDHyp:\Connections\$hostingConnectionName\$region.region\$resourceGroupName.resourcegroup\cluster.folder\$clusterName.cluster\network.folder\$logicalNetworkName.network" -StoragePath "XDHyp:\Connections\$hostingConnectionName\$region.region\$resourceGroupName.resourcegroup\cluster.folder\$clusterName.cluster\storage.folder\$storagePathName.storage" -JobGroup $guid
 

Minimum permissions

For creating a catalog in the Azure Local cluster

Following are the minimum permissions required for creating a catalog in the Azure Local cluster:

"Microsoft.AzureStackHCI/VirtualMachines/Read",
"Microsoft.AzureStackHCI/VirtualMachines/Write",
"Microsoft.AzureStackHCI/VirtualMachines/Delete",
"Microsoft.AzureStackHCI/virtualMachineInstances/Read",
"Microsoft.AzureStackHCI/virtualMachineInstances/Write",
"Microsoft.AzureStackHCI/virtualMachineInstances/Delete",
"Microsoft.HybridCompute/machines/read",
"Microsoft.HybridCompute/machines/write",
"Microsoft.HybridCompute/machines/delete",
"Microsoft.Resources/tenants/read",
"Microsoft.Resources/subscriptions/read",
"Microsoft.Resources/subscriptions/locations/read",
"Microsoft.Resources/subscriptions/resourceGroups/read",
"Microsoft.AzureStackHCI/LogicalNetworks/Read",
"Microsoft.AzureStackHCI/StorageContainers/Read",
"Microsoft.AzureStackHCI/GalleryImages/Read",
"Microsoft.AzureStackHCI/GalleryImages/Write",
"Microsoft.AzureStackHCI/GalleryImages/Delete",
"Microsoft.AzureStackHCI/NetworkInterfaces/Read",
"Microsoft.AzureStackHCI/NetworkInterfaces/Write",
"Microsoft.AzureStackHCI/NetworkInterfaces/Delete",
"Microsoft.AzureStackHCI/VirtualHardDisks/Read",
"Microsoft.AzureStackHCI/VirtualHardDisks/Write",
"Microsoft.AzureStackHCI/VirtualHardDisks/Delete",
"Microsoft.AzureStackHCI/Clusters/Read",
"Microsoft.ExtendedLocation/customLocations/Read",
"Microsoft.KubernetesConfiguration/extensions/read",
"Microsoft.AzureStackHCI/virtualMachineInstances/start/action",
"Microsoft.AzureStackHCI/virtualMachineInstances/stop/action",
"Microsoft.AzureStackHCI/virtualMachineInstances/restart/action",
"Microsoft.Resources/subscriptions/resourceGroups/write",
"Microsoft.Resources/subscriptions/resourceGroups/delete",
"Microsoft.Compute/disks/read",
"Microsoft.Compute/disks/write",
"Microsoft.Compute/disks/delete",
"Microsoft.Compute/disks/beginGetAccess/action",
"Microsoft.Compute/disks/endGetAccess/action",
"Microsoft.Compute/snapshots/read",
"Microsoft.Compute/snapshots/write",
"Microsoft.Compute/snapshots/delete",
"Microsoft.Compute/snapshots/beginGetAccess/action",
"Microsoft.Compute/snapshots/endGetAccess/action",
"Microsoft.AzureStackHCI/virtualHardDisks/write",
"Microsoft.ExtendedLocation/customLocations/deploy/action",
"Microsoft.AzureStackHCI/storageContainers/deploy/action",
"Microsoft.AzureStackHCI/virtualMachineInstances/write",
"Microsoft.AzureStackHCI/galleryImages/deploy/action",
"Microsoft.AzureStackHCI/marketplaceGalleryImages/deploy/action",
"Microsoft.AzureStackHCI/networkInterfaces/write",
"Microsoft.AzureStackHCI/logicalNetworks/join/action"
 

For power management of VMs

Following are the minimum permissions required for the power management of VMs:

"Microsoft.AzureStackHCI/VirtualMachines/Read",
"Microsoft.AzureStackHCI/virtualMachineInstances/Read",
"Microsoft.HybridCompute/machines/read",
"Microsoft.Resources/tenants/read",
"Microsoft.Resources/subscriptions/read",
"Microsoft.Resources/subscriptions/locations/read",
"Microsoft.Resources/subscriptions/resourceGroups/read",
"Microsoft.AzureStackHCI/LogicalNetworks/Read",
"Microsoft.AzureStackHCI/StorageContainers/Read",
"Microsoft.AzureStackHCI/Clusters/Read",
"Microsoft.ExtendedLocation/customLocations/Read",
"Microsoft.KubernetesConfiguration/extensions/read",
"Microsoft.AzureStackHCI/virtualMachineInstances/start/action",
"Microsoft.AzureStackHCI/virtualMachineInstances/stop/action",
"Microsoft.AzureStackHCI/virtualMachineInstances/restart/action"
 

Create an MCS catalog in the Azure Local cluster using PowerShell

You can currently create Linux VM catalogs using only the PowerShell command.

Open the PowerShell window.
Run asnp citrix*.
Run the following New-ProvScheme command to create an Azure Local machine catalog with Linux-based master image:

Note:

Skip image preparation is mandatory when creating a Linux-based machine catalog in Azure Local. Specify -NoImagePreparation in the New-ProvScheme command.

New-ProvScheme -CleanOnBoot -CustomProperties "<CustomProperties xmlns=`"http://schemas.citrix.com/2014/xd/machinecreation`" xmlns:xsi=`"http://www.w3.org/2001/XMLSchema-instance`"><Property xsi:type=`"StringProperty`" Name=`"OsType`" Value=`"Linux`" /><Property xsi:type=`"StringProperty`" Name=`"ResourceGroups`" Value=`"MyResourceGroup`" /></CustomProperties>" -HostingUnitName "MyHostingUnit" -IdentityPoolName "MyAzureLocalCatalog2"  -MasterImageVM "XDHyp:\HostingUnits\MyHostingUnit\image.folder\MyLinuxImage.galleryimage" -NetworkMapping @{"0"="XDHyp:\HostingUnits\MyHostingUnit\network.folder\MyVmNetwork.network"} -ProvisioningSchemeName "MyAzureLocalCatalog2" -ProvisioningSchemeType "MCS" -RunAsynchronously -VMCpuCount 4 -VMMemoryMB 8192 -NoImagePreparation
 

All other commands used to create an Azure Local machine catalog are the same as for any other catalog.

Create catalog by importing VMs

There can be VMs created on Azure Local outside Citrix DaaS. In such cases, you can use Citrix DaaS to power manage those VMs by importing the VMs.

To create a catalog by importing the VMs created on Azure Local outside Citrix DaaS:

On the Machine Management page, select Machines that are power managed, and then select Other service or technology as the way of deploying machines.
On the Virtual Machines page, add or import the VMs created on Azure Local outside Citrix DaaS.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.