Citrix Virtual Apps and Desktops service

Microsoft Azure Resource Manager virtualization environments

Follow the guidance in this article when using the Microsoft Azure Resource Manager to provision virtual machines in your Citrix Virtual Apps or Citrix Virtual Desktops service deployment.

We assume you are familiar with the following:

Note:

Azure supports disk encryption at rest by default, using Azure-managed encryption keys. This form of encryption is used by all catalogs in MCS and requires no user configuration.

Azure on-demand provisioning

When you use MCS to create machine catalogs in the Azure Resource Manager, the Azure on-demand provisioning feature:

  • Reduces your storage costs
  • Provides faster catalog creation
  • Provides faster virtual machine (VM) power operations

For administrators, on-demand provisioning introduces no differences in the Full Configuration interface procedures for creating host connections and MCS machine catalogs. The differences lie in how and when resources are created and managed in Azure, and VM visibility in the Azure portal.

Before Citrix Virtual Apps and Desktops service integrated Azure on-demand provisioning, MCS behavior was different. When MCS created a catalog, VMs were created in Azure during the provisioning process.

With Azure on-demand provisioning, VMs are created only when Citrix Virtual Apps and Desktops initiates a power-on action, after the provisioning completes. A VM is visible in the Azure portal only when it is running. In the Manage > Full Configuration interface, VMs are visible, if they’re running.

When you create an MCS catalog, the Azure portal displays the resource groups, network security group, storage accounts, network interfaces, base images, and identity disks. The Azure portal does not show a VM until Citrix Virtual Apps and Desktops initiates a power-on action for it. Then, the VM’s status in the Full Configuration interface changes to On.

  • For a pooled machine, the operating system disk and write-back cache exist only when the VM exists. The cache can result in significant storage savings if you routinely shut down machines (for example, outside of working hours).
  • For a dedicated machine, the operating system disk is created the first time the VM is powered on. It remains in storage until the machine identity is deleted.

When Citrix Virtual Apps and Desktops initiates a power-off action for a VM, that machine identity is deleted in Azure. It no longer appears in the Azure portal. (The VM’s status in the Full Configuration interface changes to Off.)

Catalogs created before on-demand provisioning Machine catalogs created before Citrix Virtual Apps and Desktops service supported the Azure on-demand provisioning feature (mid-2017) behaved differently. VMs in those catalogs are visible in the Azure portal if they’re running. You cannot convert an image in a region other than where MCS provisions the catalog. The image is copied to a VHD in a conventional storage account in the catalog’s region. It is then converted back to a managed disk.

On the Storage and License Types page of the catalog creation wizard, you can select a check box to use conventional storage accounts instead of managed disks. This check box is disabled when you are provisioning in an Azure region that does not support managed disks.

Create a connection to Azure Resource Manager

Create and manage connections describes the wizards that create a connection. The following information covers details specific to Azure Resource Manager connections.

Considerations:

  • Service principals must have been granted contributor role for the subscription.
  • When creating the first connection, Azure prompts you to grant it the necessary permissions. For future connections you must still authenticate, but Azure remembers your previous consent and does not display the prompt again.
  • Accounts used for authentication must be a co-administrator of the subscription.
  • The account used for authentication must be a member of the subscription’s directory. There are two types of accounts to be aware of: ‘Work or School’ and ‘personal Microsoft account.’ See CTX219211 for details.
  • While you can use an existing Microsoft account by adding it as a member of the subscription’s directory, there can be complications if the user was previously granted guest access to one of the directory’s resources. In this case, they might have a placeholder entry in the directory that does not grant them the necessary permissions, and an error is returned.

    Rectify this by removing the resources from the directory and add them back explicitly. However, exercise this option carefully, because it has unintended effects for other resources that account can access.

  • There is a known issue where certain accounts are detected as directory guests when they are actually members. Configurations like this typically occurs with older established directory accounts. Workaround: add an account to the directory, which takes the proper membership value.
  • Resource groups are simply containers for resources, and they can contain resources from regions other than their own region. This can potentially be confusing if you expect resources displayed in a resource group’s region to be available.
  • Ensure that your network and subnet are large enough to host the number of machines you require. This requires some foresight, but Microsoft helps you specify the right values, with guidance about the address space capacity.

You can establish a host connection to Azure in two ways:

  • Authenticate to Azure to create a service principal.
  • Use the details from a previously created service principal to connect to Azure.

Create a service principal

Important:

This feature is not yet available for Azure China and Azure Germany subscriptions.

Before you start, authenticate to Azure. Ensure:

  • You have a user account in your subscription’s Azure Active Directory tenant.
  • The Azure AD user account is also a co-administrator for the Azure subscription you want to use for provisioning resources.
  • Authentication requires global administrator permissions.

When you authenticate to Azure to create a service principal, an application is registered in Azure. A secret key (client secret) is created for the registered application.

To view the application ID, sign in to the Azure portal and navigate to Azure Active Directory > App registrations > All applications. The name of the application registered through the console (Manage tab) has a prefix citrix-xd-.

Application ID in Azure

To view the application’s client secret, click the application on the All Applications tab and navigate to Certificates & secrets > Client secrets.

Client secret in Azure

The client secret created through the console expires after two years. The registered application uses the client secret to authenticate to Azure AD. Be sure to change the client secret before it expires. To change it, complete the following steps:

  1. In Azure, select Azure Active Directory.

  2. From App registrations in Azure AD, select your application.

  3. Select Certificates & secrets.

  4. Select Client secrets > New client secret.

  5. Provide a description of the secret and specify a duration. When you are done, select Add.

    Note:

    Be sure to save the client secret because you cannot retrieve it later.

  6. Copy the client secret value.

  7. In the console, edit the corresponding connection and replace the content in the Application secret field with the value you copied.

To authenticate to Azure to create a service principal, complete the following steps in the Add Connection and Resources wizard:

  1. On the Connection page, select Create a new connection, the Microsoft Azure connection type, and your Azure environment.

  2. Select which tools to use to create the virtual machines and then select Next.

  3. On the Connection Details page, enter your Azure subscription ID and a name for the connection. After you enter the subscription ID, the Create new button is enabled.

    Note:

    The connection name can contain 1–64 characters, and cannot contain only blank spaces nor the characters \/;:#.*?=<>|[]{}"'()'.

  4. Select Create new and then enter the Azure Active Directory account user name and password.

  5. Select Sign in.

  6. Select Accept to give Citrix Virtual Apps and Desktops the listed permissions. Citrix Virtual Apps and Desktops creates a service principal that allows it to manage Azure resources on behalf of the specified user.

  7. After you select Accept, you return to the Connection page in the wizard.

    Note:

    After you successfully authenticate to Azure, the Create new and Use existing buttons disappear. The Connection successful text appears, with a green check mark, indicating the successful connection to your Azure subscription.

  8. On the Connection Details page, select Next.

    Note:

    You cannot proceed to the next page until you successfully authenticate to Azure and consent to giving the required permissions.

  9. Configure resources for the connection. Resources comprise the region and the network.

    • On the Region page, select a region.
    • On the Network page, do the following:
      • Type a 1–64 character resource name to help identify the region and network combination. A resource name cannot contain only blank spaces nor the characters \/;:#.*?=<>|[]{}"'()'.
      • Select a virtual network/resource group pair. (If you have more than one virtual network with the same name, pairing the network name with the resource group provides unique combinations.) If the region you selected on the previous page does not have any virtual networks, return to that page and select a region that has virtual networks.
  10. On the Summary page, view a summary of settings and select Finish to complete your setup.

Use the details from a previously created service principal to connect to Azure

To create a service principal manually, connect to your Azure Resource Manager subscription and use the PowerShell cmdlets provided in the following sections.

Prerequisites:

  • $SubscriptionId: Azure Resource Manager SubscriptionID for the subscription where you want to provision VDAs.
  • $AADUser: Azure AD user account for your subscription’s AD tenant. Make the $AADUser the co-administrator for your subscription.
  • $ApplicationName: Name for the application to be created in Azure AD.
  • $ApplicationPassword: Password for the application. You use this password as the application secret when creating the host connection.

To create a service principal:

  1. Connect to your Azure Resource Manager subscription.

    Connect-AzAccount

  2. Select the Azure Resource Manager subscription where you want to create the service principal.

    Select-AzSubscription -SubscriptionID $SubscriptionId;

  3. Create the application in your AD tenant.

    $AzureADApplication = New-AzADApplication -DisplayName $ApplicationName -HomePage "https://localhost/$ApplicationName" -IdentifierUris https://$ApplicationName -Password $ApplicationPassword

  4. Create a service principal.

    New-AzADServicePrincipal -ApplicationId $AzureADApplication.ApplicationId

  5. Assign a role to the service principal.

    New-AzRoleAssignment -RoleDefinitionName Contributor -ServicePrincipalName $AzureADApplication.ApplicationId –scope /subscriptions/$SubscriptionId

  6. From the output window of the PowerShell console, note the ApplicationId. You provide that ID when creating the host connection.

In the Add Connection and Resources wizard:

  1. On the Connection page, select Create a new connection, the Microsoft Azure connection type, and your Azure environment.

  2. Select which tools to use to create the virtual machines and then select Next.

  3. On the Connection Details page, enter your Azure subscription ID and a name for the connection.

    Note:

    The connection name can contain 1–64 characters, and cannot contain only blank spaces nor the characters \/;:#.*?=<>|[]{}"'()'.

  4. Select Use existing. In the Existing Service Principal Details window, enter the following settings for the existing service principal. After you enter the details, the Save button is enabled. Select Save. You cannot progress beyond this page until you provide valid details.

    • Subscription ID. Enter your Azure subscription ID. To obtain your subscription ID, sign in to the Azure portal and navigate to Subscriptions > Overview.
    • Active Directory ID (tenant ID). Enter the Directory (tenant) ID of the application you registered with Azure AD.
    • Application ID. Enter the Application (client) ID of the application you registered with Azure AD.
    • Application secret. Create a secret key (client secret). The registered application uses the key to authenticate to Azure AD. We recommend that you change keys regularly for security purposes. Be sure to save the key because you cannot retrieve the key later.
    • Authentication URL. This field is automatically populated and is not editable.
    • Management URL. This field is automatically populated and is not editable.
    • Storage suffix. This field is automatically populated and is not editable.
  5. After selecting Save, you return to the Connection Details page. Select Next to proceed to the next page.

  6. Configure resources for the connection. Resources comprise the region and the network.

    • On the Region page, select a region.
    • On the Network page, do the following:
      • Type a 1–64 character resource name to help identify the region and network combination. A resource name cannot contain only blank spaces nor the characters \/;:#.*?=<>|[]{}"'()'.
      • Select a virtual network/resource group pair. (If you have more than one virtual network with the same name, pairing the network name with the resource group provides unique combinations.) If the region you selected on the previous page does not have any virtual networks, return to that page and select a region that has virtual networks.
  7. On the Summary page, view a summary of settings and select Finish to complete your setup.

Create a machine catalog using an Azure Resource Manager image

This information is a supplement to the guidance in Create machine catalogs.

An image is the template that is used to create the VMs in a machine catalog. Before creating the machine catalog, create an image in Azure Resource Manager. For general information about images, see Create machine catalogs.

In the machine catalog creation wizard:

  • The Operating System and Machine Management pages do not contain Azure-specific information. Follow the guidance in the Create machine catalogs article.

  • On the Master Image page, select a resource group and then navigate (drill down) through the containers to the Azure VHD or the Shared Image Gallery or the Azure ImageVersion you want to use as the image. The VHD or the ImageVersion must have a Citrix VDA installed on it. If the VHD is attached to a VM, stop the VM.

    Note:

    When image replication is in progress, you can proceed and select the image as the master image and complete the setup. However, catalog creation might take longer to complete while the image is being replicated. MCS requires the replication to complete within an hour starting from catalog creation. If the replication times out, catalog creation fails. You can verify the replication status in Azure. Try again if the replication is still pending or after the replication completes.

    If you want to use a machine profile, enable the Use a machine profile check box and then select a machine profile from the list. (In Azure, you created VMs as machine profile VMs.) By default, the resource group where the master image resides is selected. Navigate to a machine profile within or in a different resource group. The image can inherit the following configurations from the selected machine profile:

    • Accelerated networking
    • Boot diagnostics
    • Host disk caching (relating to OS and MCSIO disks)
    • Machine size (unless otherwise specified)
    • Tags placed on the VM

    After you create the catalog, you can view the configurations that the image inherits from the machine profile. On the Machine Catalogs node, select the catalog to view its details in the lower pane. Then, click the Template Properties tab to view machine profile properties. The Tags section displays up to three tags. To view all tags placed on the VM, click View all.

    If you want MCS to provision VMs on an Azure dedicated host, enable the Use a host group check box and then select a host group from the list. A host group is a resource that represents a collection of dedicated hosts. A dedicated host is a service that provides physical servers that host one or more virtual machines. Your server is dedicated to your Azure subscription, not shared with other subscribers. When you use a dedicated host, Azure ensures that your VMs are the only machines running on that host. This feature is suitable for scenarios where you need to meet regulatory or internal security requirements. To learn more about host groups and considerations for using them, see Azure dedicated hosts.

    Important:

    • Only host groups that have Azure auto-placement enabled are shown.
    • When using a machine profile, you cannot use a host group.
    • Using a host group changes the Virtual Machines page offered later in the wizard. Only machine sizes that the selected host group contains are shown on that page. Also, Availability Zones are selected automatically and not available for selection.
  • The Storage and License Types page appears only when using an Azure Resource Manager image.

    Storage and License Types page

    You have the following storage types to use for the machine catalog:

    • Premium SSD. Offers a high-performance, low-latency disk storage option suitable for VMs with I/O-intensive workloads.
    • Standard SSD. Offers a cost-effective storage option that is suitable for workloads that require consistent performance at lower IOPS levels. An Azure identity disk is always created using Standard SSD.
    • Standard HDD. Offers a reliable, low-cost disk storage option suitable for VMs that run latency-insensitive workloads.

    The storage type determines which machine sizes are offered on the Virtual Machines page of the wizard. MCS configures premium and standard disks to use Locally Redundant Storage (LRS). LRS makes multiple synchronous copies of your disk data within a single data center. For details about Azure storage types and storage replication, see the following:

    Select whether to use existing Windows licenses. Using Windows licenses along with Windows images (Azure platform support images or custom images) lets you run Windows VMs in Azure at a reduced cost. There are two types of licenses:

    • Windows Server license. Lets you use your Windows Server or Azure Windows Server licenses, allowing you to use Azure Hybrid Benefits. For details, see https://azure.microsoft.com/en-us/pricing/hybrid-benefit/. Azure Hybrid Benefit reduces the cost of running VMs in Azure to the base compute rate, waiving the cost of extra Windows Server licenses from the Azure gallery.

    • Windows Client license. Lets you bring your Windows 10 licenses to Azure, allowing you to run Windows 10 VMs in Azure without the need for extra licenses. For details, see Client Access Licenses and Management Licenses.

    Note:

    The Windows Client license option varies depending on the operating system you select during machine catalog setup. If you select Multi-session OS, the option appears as Use my Windows 10 licenses. If you select Single-session OS, the option appears as Use my Windows Client licenses.

    You can verify that the provisioned VM is using the licensing benefit by running the following PowerShell command: Get-AzM -ResourceGroup MyResourceGroup -Name MyVM.

    Alternatively, you can use the Get-Provscheme PowerShell SDK to perform the verification. For example: Get-Provscheme -ProvisioningSchemeName "My Azure Catalog". For more information about this cmdlet, see https://developer-docs.citrix.com/projects/citrix-virtual-apps-desktops-sdk/en/latest/MachineCreation/Get-ProvScheme/.

    Azure Managed Disks are used for VMs in the catalog by default. If you want to use regular storage accounts instead, select the check box at the bottom of the page. The Use unmanaged disks instead of Azure Managed Disks for VMs in this catalog check box is available only in the legacy console.

    Azure Shared Image Gallery (SIG) is a repository for managing and sharing images. It lets you make your images available throughout your organization. We recommend that you store an image in SIG when creating large non-persistent machine catalogs because doing that enables faster resets of VDA OS disks. The Place image in Azure Shared Image Gallery check box is available only in the web-based console. After you select Place image in Azure Shared Image Gallery, the Azure Shared Image Gallery settings section appears, letting you specify more SIG settings:

    • Ratio of virtual machines to image replicas. Lets you specify the ratio of virtual machines to image replicas that you want Azure to keep. By default, Azure keeps a single image replica for every 40 non-persistent machines. For persistent machines, that number defaults to 1,000.

    • Maximum replica count. Lets you specify the maximum number of image replicas that you want Azure to keep. The default is 10.

  • On the Virtual Machines page, indicate how many VMs you want to create. You must specify at least one. Select a machine size. After you create a catalog, you cannot change the machine size. If you later want a different size, delete the catalog and then create a catalog that uses the same image and specifies the desired machine size.

Virtual machine names cannot contain non-ASCII or special characters.

  • (When using MCS) On the Resource Groups page, choose whether to create resource groups or use existing groups.
    • If you choose to create resource groups, select Next.
    • If you choose to use existing resource groups, select groups from the Available Provisioning Resource Groups list. Remember: Select enough groups to accommodate the machines you’re creating in the catalog. A message appears if you choose too few. You might want to select more than the minimum required if you plan to add more VMs to the catalog later. You can’t add more resource groups to a catalog after the catalog is created.

    For more information, see Azure resource groups.

  • The Network Cards, Computer Accounts, and Summary pages do not contain Azure-specific information. Follow the guidance in the Create Machine Catalogs article.

Complete the wizard.

Azure throttling

Azure Resource Manager throttles requests for subscriptions and tenants, routing traffic based on defined limits, tailored to the specific needs of the provider. See Throttling Resource Manager requests on the Microsoft site for more information. Limits exist for subscriptions and tenants, where managing many machines can become problematic. For example, a subscription containing many machines might experience performance problems related to power operations.

Tip:

For more information, see Improving Azure performance with Machine Creation Services.

To help mitigate these issues, Citrix Virtual Apps and Desktops service allows you to remove MCS internal throttling to use more of the available request quota from Azure.

We recommend the following optimal settings when powering VMs on or off in large subscriptions, for example, those containing 1,000 VMs:

  • Absolute simultaneous operations: 500
  • Maximum new operations per minute: 2000
  • Max concurrency of operations: 500

Use the Full Configuration interface to configure Azure operations for a given host connection:

  1. From Manage > Full Configuration, select Hosting in the left pane.
  2. Select an Azure-related connection to edit it.
  3. In the Edit Connection wizard, select Advanced.
  4. On the Advanced page, use the configuration options to specify the number of simultaneous actions and maximum new actions per minute, and any additional connection options.

Azure throttling

MCS supports 500 maximum concurrent operations by default. Alternatively, you can use the Remote PowerShell SDK to set the maximum number of concurrent operations.

Use the PowerShell property, MaximumConcurrentProvisioningOperations, to specify the maximum number of concurrent Azure provisioning operations. When using this property in the provisioning scheme, consider:

  • MCS supports 500 maximum concurrent operations by default, using the custom properties parameter MaximumConcurrentProvisioningOperations.
  • Configure the MaximumConcurrentProvisioningOperations parameter using the PowerShell command Set-ProvScheme.

Azure resource groups

Azure provisioning resource groups provide a way to provision the VMs that provide applications and desktops to users. You can add existing empty Azure resource groups when you create an MCS machine catalog, or have new resource groups created for you. For information about Azure resource groups, see the Microsoft documentation.

Azure Resource Group Usage

There is no limit on the number of virtual machines, managed disks, snapshots, and images per Azure Resource Group. (The limit of 240 VMs per 800 managed disks per Azure Resource Group has been removed.)

  • When using a full scope service principal to create a machine catalog, MCS creates only one Azure Resource Group and uses that group for the catalog.
  • When using a narrow scope service principal to create a machine catalog, you must supply an empty, pre-created Azure Resource Group for the catalog.

Azure ephemeral disks

An Azure ephemeral disk allows you to repurpose the cache disk to store the OS disk for an Azure-enabled virtual machine. This functionality is useful for Azure environments that require a higher performant SSD disk over a standard HDD disk. To use ephemeral disks, you must set the custom property UseEphemeralOsDisk to true when running New-ProvScheme.

Note:

If the custom property UseEphemeralOsDisk is set to false or a value is not specified all provisioned VDAs continue to use a provisioned OS disk.

The following is an example set of custom properties to use in the provisioning scheme:

"CustomProperties": [
            {
                "Name": "UseManagedDisks",
                "Value": "true"
            },
            {
                "Name": "StorageAccountType",
                "Value": "Standard_LRS"
            },
            {
                "Name": "UseSharedImageGallery",
                "Value": "true"
            },
            {
                "Name": "SharedImageGalleryReplicaRatio",
                "Value": "40"
            },
            {
                "Name": "SharedImageGalleryReplicaMaximum",
                "Value": "10"
            },
            {
                "Name": "LicenseType",
                "Value": "Windows_Server"
            },
            {
                "Name": "UseEphemeralOsDisk",
                "Value": "true"
            }
        ],
<!--NeedCopy-->

How to create machines using ephemeral OS disks

Ephemeral OS disks are controlled based on the UseEphemeralOsDisk property in the CustomProperties parameter.

Important considerations for ephemeral disks

To use provision ephemeral OS disks using New-ProvScheme, consider the following constraints:

  • The VM size used for the catalog (the service offering) must support ephemeral OS disks.
  • The cache disk size represented by the VM size must be greater than or equal to the size of the OS disk.

Also consider these issues when:

  • Creating the provisioning scheme.
  • Modifying the provisioning scheme.
  • Updating the image.

Azure server side encryption

Citrix Virtual Apps and Desktops service supports customer-managed encryption keys for Azure managed disks through Azure Key Vault. With this support you can manage your organizational and compliance requirements by encrypting the managed disks of your machine catalog using your own encryption key. For more information, see Server-side encryption of Azure Disk Storage.

When using this feature for managed disks:

  • To change the key that the disk is encrypted with, you change the current key in the DiskEncryptionSet. All resources associated with that DiskEncryptionSet change to be encrypted with the new key.

  • When you disable or delete your key, any VMs with disks using that key automatically shut down. After shutting down, the VMs are not usable unless the key is enabled again or you assign a new key. Any catalog using the key cannot be powered on, and you cannot add VMs to it.

Important considerations when using customer-managed encryption keys

Consider the following when using this feature:

  • All resources related to your customer-managed keys (Azure Key Vaults, disk encryption sets, VMs, disks, and snapshots) must reside in the same subscription and region.

  • Once you have enabled the customer-managed encryption key you cannot disable it later. If you want to disable or remove the customer-managed encryption key, copy all the data to a different managed disk that is not using the customer-managed encryption key.

  • Disks created from encrypted custom images using server-side encryption and customer-managed keys must be encrypted using the same customer-managed keys. These disks must be in the same subscription.

  • Snapshots created from disks that are encrypted with server-side encryption and customer-managed keys must be encrypted with the same customer-managed keys.

  • Disks, snapshots, and images encrypted with customer-managed keys cannot move to another resource group and subscription.

  • Managed disks currently or previously encrypted using Azure Disk Encryption cannot be encrypted using customer-managed keys.

  • You can only create up to 50 disk encryption sets per region, per subscription.

Note:

See Quickstart: Create a Key Vault using the Azure portal for information on configuring Azure server side encryption.

Use Azure Shared Image Gallery as a published image repository for MCS provisioned machines in Azure. You can store a published image in the gallery to accelerate the creation and hydration of OS disks, improving boot and application launch times for non-persistent VMs. Shared image gallery contains the following three elements:

  • Gallery. Images are stored here. MCS creates one gallery for each machine catalog.
  • Gallery Image Definition. This definition includes information (operating system type and state, Azure region) about the published image. MCS creates one image definition for each image created for the catalog.
  • Gallery Image Version. Each image in a Shared Image Gallery can have multiple versions, and each version can have multiple replicas in different regions. Each replica is a full copy of the published image. Citrix Virtual Apps and Desktops service creates one Standard_LRS image version (version 1.0.0) for each image with the appropriate number of replicas in the catalog’s region, based on the number of machines in the catalog, the configured replica ratio, and the configured replica maximum.

Note:

Shared Image Gallery functionality only works with managed disks. It is not available for legacy machine catalogs.

For more information, see Azure shared image gallery overview.

Use the New-ProvScheme command to create a provisioning scheme with Shared Image Gallery support. Use the Set-ProvScheme command to enable or disable this feature for a provisioning scheme and to change the replica ratio and replica maximum values.

Three custom properties were added to provisioning schemes to support the Shared Image Gallery feature:

UseSharedImageGallery

  • Defines whether to use the Shared Image Gallery to store the published images. If set to True, the image is stored as a Shared Image Gallery image, otherwise the image is stored as a snapshot.
  • Valid values are True and False.
  • If the property is not defined, the default value is False.

SharedImageGalleryReplicaRatio

  • Defines the ratio of machines to gallery image version replicas.
  • Valid values are integer numbers greater than 0.
  • If the property is not defined, default values are used. The default value for persistent OS disks is 1000 and the default value for non-persistent OS disks is 40.

SharedImageGalleryReplicaMaximum

  • Defines the maximum number of replicas for each gallery image version.
  • Valid values are integer numbers greater than 0.
  • If the property is not defined, the default value is 10.
  • Azure currently supports up to 10 replicas for a gallery image single version. If the property is set to a value greater than that supported by Azure, MCS attempts to use the specified value. Azure generates an error, which MCS logs then leaves the current replica count unchanged.

Tip:

When using Shared Image Gallery to store a published image for MCS provisioned catalogs, MCS sets the gallery image version replica count based on the number of machines in the catalog, the replica ratio, and the replica maximum. The replica count is calculated by dividing the number of machines in the catalog by the replica ratio (rounding up to the nearest integer value) and then capping the value at the maximum replica count. For example, with a replica ratio of 20 and a maximum of 5, 0–20 machines have one replica created, 21–40 have 2 replicas, 41–60 have 3 replicas, 61–80 have 4 replicas, 81+ have 5 replicas.

The existing machine catalog uses Shared Image Gallery. Use the Set-ProvScheme command to update the custom properties for all existing machines in the catalog and any future machines:

Set-ProvScheme -ProvisioningSchemeName catalog-name -CustomProperties '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Property xsi:type="StringProperty" Name="StorageAccountType" Value="Standard_LRS"/> <Property xsi:type="StringProperty" Name="UseManagedDisks" Value="True"/> <Property xsi:type="StringProperty" Name="UseSharedImageGallery" Value="True"/> <Property xsi:type="IntProperty" Name="SharedImageGalleryReplicaRatio" Value="30"/> <Property xsi:type="IntProperty" Name="SharedImageGalleryReplicaMaximum" Value="20"/></CustomProperties>'
<!--NeedCopy-->

For this use case:

  1. Run Set-ProvScheme with the UseSharedImageGallery flag set to True. Optionally include the SharedImageGalleryReplicaRatio and SharedImageGalleryReplicaMaximum properties.
  2. Update the catalog.
  3. Power cycle the machines to force an update.

For example:

Set-ProvScheme -ProvisioningSchemeName catalog-name -CustomProperties '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Property xsi:type="StringProperty" Name="StorageAccountType" Value="Standard_LRS"/> <Property xsi:type="StringProperty" Name="UseManagedDisks" Value="True"/> <Property xsi:type="StringProperty" Name="UseSharedImageGallery" Value="True"/> <Property xsi:type="IntProperty" Name="SharedImageGalleryReplicaRatio" Value="30"/> <Property xsi:type="IntProperty" Name="SharedImageGalleryReplicaMaximum" Value="20"/></CustomProperties>'
<!--NeedCopy-->

Tip:

The parameters SharedImageGalleryReplicaRatio and SharedImageGalleryReplicaMaximum are not required. After the Set-ProvScheme command completes the Shared Image Gallery image has not yet been created. Once the catalog is configured to use the gallery, the next catalog update operation stores the published image in the gallery. The catalog update command creates the gallery, the gallery image, and the image version. Power cycling the machines updates them, at which point the replica count is updated, if appropriate. From that time, all existing non-persistent machines are reset using the Shared Image Gallery image and all newly provisioned machines are created using the image. The old snapshot is cleaned up automatically within a few hours.

For this use case:

  1. Run Set-ProvScheme with the UseSharedImageGallery flag set to False or not defined.
  2. Update the catalog.
  3. Power cycle the machines to force an update.

For example:

Set-ProvScheme -ProvisioningSchemeName catalog-name -CustomProperties '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Property xsi:type="StringProperty" Name="StorageAccountType" Value="Standard_LRS"/> <Property xsi:type="StringProperty" Name="UseManagedDisks" Value="True"/> <Property xsi:type="StringProperty" Name="UseSharedImageGallery" Value="False"/></CustomProperties>'
<!--NeedCopy-->

Tip:

Unlike updating from a snapshot to a Shared Image Gallery catalog, the custom data for each machine is not yet updated to reflect the new custom properties. Run the following command to see the original Shared Image Gallery custom properties: Get-ProvVm -ProvisioningSchemeName catalog-name. After the Set-ProvScheme command completes the image snapshot has not yet been created. Once the catalog is configured to not use the gallery, the next catalog update operation stores the published image as a snapshot. From that time, all existing non-persistent machines are reset using the snapshot and all newly provisioned machines are created from the snapshot. Power cycling the machines updates them, at which point the custom machine data is updated to reflect that UseSharedImageGallery is set to False. The old Shared Image Gallery assets (gallery, image, and version) are automatically cleaned up within a few hours.

Provision machines into specified availability zones

You can provision machines into specific Availability Zones in Azure environments. You can achieve that using the Full Configuration interface or PowerShell.

(If using the legacy console, you must use PowerShell.)

Note:

If no zones are specified, MCS lets Azure place the machines within the region. If more than one zone is specified, MCS randomly distributes the machines across them.

Configuring Availability Zones in the Full Configuration interface

When creating a machine catalog, you can specify Availability Zones into which you want to provision machines. On the Virtual Machines page, select one or more Availability Zones where you want to create machines.

There are two reasons that no Availability Zones are available: The region has no Availability Zones or the selected machine size is unavailable.

Configuring Availability Zones through PowerShell

Using PowerShell, you can view the service offering inventory items by using Get-Item. For example, to view the Eastern US region Standard_B1ls service offering:

$serviceOffering = Get-Item -path "XDHyp:\Connections\my-connection-name\East US.region\serviceoffering.folder\Standard_B1ls.serviceoffering"
<!--NeedCopy-->

To view the zones, use the AdditionalData parameter for the item:

$serviceOffering.AdditionalData

If Availability Zones are not specified, there is no change in how machines are provisioned.

To configure Availability Zones through PowerShell, use the Zones custom property available with the New-ProvScheme operation. The Zones property defines a list of Availability Zones to provision machines into. Those zones can include one or more Availability Zones. For example, <Property xsi:type="StringProperty" Name="Zones" Value="1, 3"/> for Zones 1 and 3.

Use the Set-ProvScheme command to update the zones for a provisioning scheme.

If an invalid zone is provided, the provisioning scheme is not updated, and an error message appears providing instructions on how to fix the invalid command.

Tip:

If you specify an invalid custom property, the provisioning scheme is not updated and a relevant error message appears.

Azure ephemeral disk

Azure ephemeral disks allow you to repurpose the cache disk to store the OS disk for an Azure-enabled virtual machine. This functionality is useful for Azure environments that require a higher performant SSD disk over a standard HDD disk.

Note:

Persistent catalogs do not support ephemeral OS disks.

Ephemeral OS disks require that your provisioning scheme use managed disks and a Shared Image Gallery. For more information, see Azure shared image gallery.

Using PowerShell to configure an ephemeral disk

To configure an Azure ephemeral OS disk for a catalog, use the UseEphemeralOsDisk parameter in Set-ProvScheme. Set the value of the UseEphemeralOsDisk parameter to true.

Note:

To use this feature, you must also enable the parameters UseManagedDisks and UseSharedImageGallery.

For example:

Set-ProvScheme -ProvisioningSchemeName catalog-name -CustomProperties <CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" />
<Property xsi:type="StringProperty" Name="UseSharedImageGallery" Value="true" />
<Property xsi:type="StringProperty" Name="UseEphemeralOsDisk" Value="true" />
</CustomProperties>'
<!--NeedCopy-->

Preserving a provisioned virtual machine when power cycling

Choose whether to preserve a provisioned virtual machine when power cycling. Use the PowerShell parameter New-ProvScheme CustomProperties. This parameter supports an extra property, PersistVm, used to determine if a provisioned virtual machine persists when power cycled. Set the PersistVm property to true to persist a virtual machine when powered off, or set the property to false to ensure that the virtual machine is not preserved when powered off.

Note:

The PersistVm property only applies to a provisioning scheme with the properties CleanOnBoot and UseWriteBackCache enabled. If the PersistVm property is not specified for non-persistent virtual machines, they are deleted from the Azure environment when powered off.

In the following example, the New-ProvScheme CustomProperties parameter sets the PersistVmproperty to true:

<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" />
<Property xsi:type="StringProperty" Name="StorageAccountType" Value="Standard_LRS" />
<Property xsi:type="StringProperty" Name="PersistWBC" Value="false" />
<Property xsi:type="StringProperty" Name="PersistOsDisk" Value="true" />
<Property xsi:type="StringProperty" Name="PersistVm" Value="true" />
<Property xsi:type="StringProperty" Name="ResourceGroups" Value="demo-resourcegroup" />
<Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client" />
</CustomProperties>
<!--NeedCopy-->

In the following example, the New-ProvScheme CustomProperties parameter preserves write back cache by setting PersistVM to true:

 New-ProvScheme
 -AzureAdJoinType "None"
 -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=`"UseManagedDisks`" Value=`"true`" /><Property xsi:type=`"StringProperty`" Name=`"StorageAccountType`" Value=`"Standard_LRS`" /><Property xsi:type=`"StringProperty`" Name=`"PersistWBC`" Value=`"false`" /><Property xsi:type=`"StringProperty`" Name=`"PersistOsDisk`" Value=`"true`" /><Property xsi:type=`"StringProperty`" Name=`"PersistVm`" Value=`"true`" /><Property xsi:type=`"StringProperty`" Name=`"ResourceGroups`" Value=`"demo-resourcegroup`" /><Property xsi:type=`"StringProperty`" Name=`"LicenseType`" Value=`"Windows_Client`" /></CustomProperties>"
 -HostingUnitName "demo"
 -IdentityPoolName "NonPersistent-MCSIO-PersistVM"
 -MasterImageVM "XDHyp:\HostingUnits\demo\image.folder\scale-test.resourcegroup\demo-snapshot.snapshot"
 -NetworkMapping @ {"0"="XDHyp:\HostingUnits\demo\\virtualprivatecloud.folder\East US.region\virtualprivatecloud.folder\ji-test.resourcegroup\jitest-vnet.virtualprivatecloud\default.network"}
-ProvisioningSchemeName "NonPersistent-MCSIO-PersistVM"
 -ServiceOffering "XDHyp:\HostingUnits\demo\serviceoffering.folder\Standard_B2ms.serviceoffering" -UseWriteBackCache
 -WriteBackCacheDiskSize 127
 -WriteBackCacheMemorySize 256
 <!--NeedCopy-->

Tip:

The PersistVm property determines whether to preserve a provisioned virtual machine. The PersistOsdisk property determines whether to persist the OS disk. To preserve a provisioned virtual machine, preserve the OS disk first. You cannot delete the OS disk without first deleting the virtual machine. You can use the PersistOsdisk property without using specifying the PersistVm parameter.

Storage types

Select different storage types for virtual machines in Azure environments that use MCS. For target VMs, MCS supports:

  • OS disk: premium SSD, SSD or HDD
  • Write back cache disk: premium SSD, SSD, or HDD

When using these storage types, consider the following:

  • Ensure that your VM supports the selected storage type.
  • If your configuration uses an Azure ephemeral disk, enabling write back cache always uses standard HDD storage. For implementations using write back cache, enable the WBCDiskStorageType parameter in CustomProperties. If you do not specify the WBCDiskStorageType parameter, the StorageAccountType uses the default value.

Tip:

StorageAccountType is configured for an OS type and storage account. WBCDiskStorageType is configured for write back cache storage type. For a normal catalog, StorageAccountType is required. If WBCDiskStorageType is not configured, the StorageAccountType is used as the default for WBCDiskStorageType.

WBCDiskStorageType is not configured, then StorageAccountType will be used as the default for WBCDiskStorageType

Configuring storage types

To configure storage types for VM, use the StorageAccountType parameter in New-ProvScheme. Set the value of the StorageAccountType parameter to one of the supported storage types.

The following is an example set of the CustomProperties parameter in a provisioning scheme:

Set-ProvScheme -ProvisioningSchemeName catalog-name -CustomProperties '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" />
<Property xsi:type="StringProperty" Name="StorageAccountType" Value="Premium_LRS" />
<Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client" />
</CustomProperties>'
<!--NeedCopy-->

You can display information for an Azure VM, including OS disk and type, snapshot and gallery image definition. This information is displayed for resources on the master image when a machine catalog is assigned. Use this functionality to view and select either a Linux or Windows image. A PowerShell property, TemplateIsWindowsTemplate, was added to the AdditionDatafield parameter. This field contains Azure-specific information: VM type, OS disk, gallery image information, and OS type information. Setting TemplateIsWindowsTemplate to True indicates that the OS type is Windows; setting TemplateIsWindowsTemplate to False indicates that the OS type is Linux.

Tip:

Information displayed by the TemplateIsWindowsTemplate PowerShell property is derived from the Azure API. In some cases, this field might be empty. For example, a snapshot from a data disk does not contain the TemplateIsWindowsTemplate field because the OS type cannot be retrieved from a snapshot.

For example, set the Azure VM AdditionData parameter to True for Windows OS type using PowerShell:

PS C:\Users\username> (get-item XDHyp:\HostingUnits\mynetwork\image.folder\username-dev-testing-rg.resourcegroup\username-dev-tsvda.vm).AdditionalData
Key Value
ServiceOfferingDescription Standard_B2ms
HardDiskSizeGB 127
ResourceGroupName FENGHUAJ-DEV-TESTING-RG
ServiceOfferingMemory 8192
ServiceOfferingCores 2
TemplateIsWindowsTemplate True
ServiceOfferingWithTemporaryDiskSizeInMb 16384
SupportedMachineGenerations Gen1,Gen2
<!--NeedCopy-->

Azure VMware Solution integration

Citrix Virtual Apps and Desktop service supports AVS. Azure VMware Solution (AVS) provides cloud infrastructure containing vSphere clusters created by Azure infrastructure. Leverage the Citrix Virtual Apps and Desktop Service to use AVS for provisioning your VDA workload in the same way that you would using vSphere in on-premises enviornments.

Setting up the AVS cluster

To enable the Citrix Virtual Apps and Desktop Service to use AVS, perform the following steps in Azure:

  • Request a host quota
  • Register the Microsoft.AVS resource provider
  • Network Checklist
  • Create an Azure VMware Solution private cloud
  • Access an Azure VMware Solution private cloud
  • Configure networking for your VMware private cloud in Azure
  • Configure DHCP for Azure VMware Solution
  • Add a network segment in Azure VMware Solution
  • Verify Azure VMware Solution environment

Request host quota for Azure Enterprise Agreement customers

In the Azure portal’s Help + Support page select New support request, and include the following information:

  • Issue type:Technical
  • Subscription:Select your subscription
  • Service:All services > Azure VMware Solution
  • Resource:General question
  • Summary:Need capacity
  • Problem type:Capacity Management Issues
  • Problem subtype:Customer Request for Additional Host Quota/Capacity

In the Description of the support ticket, incldue the following information in the Details tab:

  • POC or Production
  • Region Name
  • Number of hosts
  • Any other details

Note:

AVS requires a minimum of three hosts, and recommends that you use redundancy of N+1 hosts.

After specifying details for the support ticket, select Review + Create to submit the request to Azure.

Register the Microsoft.AVS resource provider

After requesting the host quota, register the resource provider:

  1. Sign in to the Azure portal.
  2. On the Azure portal menu, select All services.
  3. In the All services menu, enter the subscription, and select Subscriptions.
  4. Select the subscription from the subscription list.
  5. Select Resource providers and enter Microsoft.AVS in the search bar.
  6. If the resource provider is not registered, select Register.

Networking considerations

AVS offers networking services requiring specific network address ranges and firewall ports. See Networking planning checklist for Azure VMware Solution for more information.

Create an Azure VMware Solution private cloud

After conidering network requirements for your environment, create a ASV private cloud:

  1. Sign in to the Azure portal.
  2. Select Create a new resource.
  3. In the Search the Marketplace text box type, Azure VMware Solution, and select Azure VMware Solution from the list.

Azure ASV private cloud setup image

In the Azure VMware Solution window:

  1. Select Create.
  2. Click the Basics tab.
  3. Enter values for the fields, using the information in the table below:
Field Value
Subscription Select the subscription you plan to use for the deployment. All resources in an Azure subscription are billed together.
Resource group Select the resource group for your private cloud. An Azure resource group is a logical container into which Azure resources are deployed and managed. Alternatively, you can create a new resource group for your private cloud.
Location Select a location, such as east us. This is the region you defined during the planning phase.
Resource name Provide the name of your Azure VMware Solution private cloud.
SKU Select AV36.
Hosts Shows the number of hosts allocated for the private cloud cluster. The default value is 3, which can be raised or lowered after deployment.
Address block Provide an IP address block for the private cloud. The CIDR represents the private cloud management network and will be used for the cluster management services, such as vCenter Server and NSX-T Manager. Use /22 address space, for example, 10.175.0.0/22. The address should be unique and not overlap with other Azure Virtual Networks as well as with on-premises networks.
Virtual Network Leave this blank because the Azure VMware Solution ExpressRoute circuit is established as a post-deployment step.

In the Create a private cloud screen:

  1. In the Location field, select the region that has the AVS; the resource group region is the same as the AVS region.
  2. In the SKU field, select AV36 Node.
  3. Specify an IP address in the Address Block field. For example, 10.15.0.0/22.
  4. Select Review + Create.
  5. After reviewing the information, click Create.

Azure ASV create private cloud

Tip:

Creating a private cloud can take 3-4 hours. Adding a single host to cluster can take 30-45 minutes.

Verify that the deployment was successful. Navigate to the resource group you created and select your private cloud. Once the Status is Succeeded the deployment is complete.

Azure ASV verify connection

Access an Azure VMware Solution private cloud

Once you have created a private cloud, create a Windows VM and connect to the local vCenter of your private cloud.

Create a new Windows virtual machine
  1. In the resource group, select + Add then search and select Microsoft Windows 10/2016/2019.
  2. Click Create.
  3. Enter the required information, then select Review + Create.
  4. Once validation passes, select Create to start the virtual machine creation process.
Connect to the local vCenter of your private cloud
  1. Sign in to vSphere Client with VMware vCenter SSO as a cloud administrator.

    Azure ASV vSphere login

  2. In the Azure portal, select your private cloud, and then Manage> Identity.

The URLs and user credentials for private cloud vCenter and NSX-T Manager appear:

Azure ASV setup vCenter

After confirming URLs and user credentials:

  1. Navigate to the VM you created in the preceding step and connect to the virtual machine.

  2. In the Windows VM, open a browser and navigate to the vCenter and NSX-T Manger URLs in two browser tabs. In the vCenter tab, enter the cloudadmin@vmcp.local user credentials from the previous step.

Configure networking for your VMware private cloud in Azure

After accessing an ASV private cloud, configure networking by creating a virtual network and gateway.

Create a virtual network
  1. Sign in to the Azure portal.
  2. Navigate to the previously created resource group.
  3. Select + Add to define a new resource.
  4. In the Search the Marketplace text box, type virtual network. Find the virtual network resource and select it.
  5. On the Virtual Network page, select Create to set up the virtual network for your private cloud.
  6. On the Create Virtual Network page, enter the details for your virtual network.
  7. On the Basics tab, enter a name for the virtual network, select the appropriate region, and click Next : IP Addresses.
  8. On the IP Addresses tab, under IPv4 address space, enter the previously created address.

Important:

Use an address that does not overlap with the address space you used when you created your private cloud.

After entering the address space:

  1. Select + Add subnet.
  2. On the Add subnet page, give the subnet a name and appropriate address range.
  3. Click Add.
  4. Select Review + create.
  5. Verify the information and click Create. Once the deployment is complete, the virtual network appears in the resource group.
Create a virtual network gateway

After creating a virtual network, create a virtual network gateway.

  1. In your resource group, select + Add to add a new resource.
  2. In the Search the Marketplace text box, type virtual network gateway. Find the virtual network resource and select it.
  3. On the Virtual Network gateway page, click Create.
  4. On the Basics tab in the Create virtual network gateway page, provide values for the fields.
  5. Click Review + create.

Azure ASV setup vCenter

After reviewing the virtual network gateway configuration, click Create to deploy your virtual network gateway. Once the deployment completes, connect your ExpressRoute connection to the virtual network gateway containing your Azure AVS private cloud.

Connect ExpressRoute to the virtual network gateway

After deploying a virtual network gateway, add a connection between it and your Azure AVS private cloud:

  1. Request an ExpressRoute authorization key.
  2. In the Azure portal, navigate to the Azure VMware Solution private cloud. Select Manage> Connectivity > ExpressRoute and then select + Request an authorization key.

Azure ASV request authorization key

After requesting an authorization key:

  1. Enter a name for the key and click Create. It may take about 30 seconds to create the key. Once created, the new key appears in the list of authorization keys for the private cloud.
  2. Copy the authorization key and ExpressRoute ID. You’ll need them to complete the peering process. The authorization key disappears after some time, so copy it as soon as it appears.
  3. Navigate to the virtual network gateway you plan to use and select Connections> + Add.
  4. On the Add connection page, provide values for the fields, and select OK.

Azure ASV add connection

The connection is established between your ExpressRoute circuit and your virtual network:

Azure ASV successful connection

Configure DHCP for Azure VMware Solution

After connecting ExpressRoute to the virutal gateway, configure DHCP.

Use NSX-T to host your DHCP server

In NSX-T Manager:

  1. Select Networking> DHCP, and then select Add Server.
  2. Select DHCP for the Server Type, provide the server name and IP address.
  3. Click Save.
  4. Select Tier 1 Gateways, select the vertical ellipsis on the Tier-1 gateway, and then select Edit.
  5. Select No IP Allocation Set to add a subnet.
  6. Select DHCP Local Server for the Type.
  7. For the DHCP Server, select Default DHCP, and then click Save.
  8. Click Save again and then select Close Editing.

Azure ASV add NSX-T server

Add a network segment in Azure VMware Solution

After settnig up DHCP, add a network segment.

To add a network segment, in NSX-T Manager, select Networking> Segments, and then click Add Segment.

Azure ASV add NSX-T segment

In the Segments profile screen:

  1. Enter a name for the segment.
  2. Select the Tier-1 Gateway (TNTxx-T1) as the Connected Gateway and leave the Type as Flexible.
  3. Select the pre-configured overlay Transport Zone(TNTxx-OVERLAY-TZ).
  4. Click Set Subnets.

Azure ASV add NSX-T segment profiles

In the Subnets section:

  1. Enter the gateway IP address.
  2. Select Add.

Important:

This segment IP address must belong to the Azure gateway IP address, 10.15.0.0/22.

DHCP range should be belong to segment IP address:

Azure ASV add NSX-T segment DHCP range

Select No to decline the option to continue configuring the segment:

Azure ASV add NSX-T finish setup

In vCenter, select Networking > SDDC-Datacenter:

Azure ASV add NSX-T vCenter

Verify the Azure AVS environment

Setup a direct connection and connector in the Azure resource group:

Azure ASV ASV verify connection

Verify the connection with vCenter credentials:

Azure ASV add NSX-T vCenter

Requirements

  • If you want the Citrix Virtual Apps and Desktops service to create resource groups for each MCS catalog, the Azure service principal associated with the host connection must have permission to create and delete resource groups. If you want the Citrix Virtual Apps and Desktops service to use existing empty resource groups, the Azure service principal associated with the host connection must have Contributor permission on those empty resource groups.
  • When you create a host connection using the Create new option, the created service principal has subscription scope contribute permissions. Alternatively, you can use the Use existing option to create the connection, and provide the details of an existing subscription scope service principal. If you use the Create new option and create the Service Principal in the Full Configuration interface, it has the needed permissions to create and delete new resource groups or provision into existing empty resource groups.
  • Narrow scope service principals must be created using PowerShell. Also, when using a narrow scope service principal, you must use PowerShell or the Azure portal to create empty resource groups in the same region as your host connection for each catalog where MCS provisions VMs. For instructions, see the blog post https://www.citrix.com/blogs/2016/11/09/azure-role-based-access-control-in-xenapp-xendesktop/.)

If you are using a narrow scope service principal for the host connection and don’t see your image resource group on the Master Image page of the catalog creation wizard, it is probably because the narrow scope service principal you are using doesn’t have the permission Microsoft.Resources/subscriptions/resourceGroups/read to list the image resource group. Close the wizard, update the service principal with the permission (see the blog post for instructions), and then restart the wizard. The update in Azure can take up to 10 minutes to appear in the Full Configuration interface.

Tip:

The Azure service principal requires contributor rights. The contributor right can either be a full (subscription) scope-wide contributor where MCS automatically creates an Azure Resource Group for a machine catalog. Or, the contributor right can be narrow scope, where an empty Azure Resource Group must be created in advance and contributor rights granted accordingly.

Configure resource groups for a machine catalog in the Full Configuration interface

The Resource Groups page in the catalog creation wizard allows you to choose whether to create resource groups or use existing groups. See Create a machine catalog using an Azure Resource Manager image.

What happens to resource groups when you delete a machine catalog. If you let the Citrix Virtual Apps and Desktops service create resource groups when you create the machine catalog, and then later delete the catalog, those resource groups, and other resources in those resource groups are also deleted.

If you use existing resource groups when you create the machine catalog, and then later delete the catalog, all resources in those resource groups are deleted, but the resource groups are not deleted.

Considerations and limitations

When you use existing resource groups, the list of available resource groups on the Resource Groups page in the catalog creation wizard does not auto-refresh. So, if you have that wizard page open and create or add permissions to resource groups in Azure, the changes are not reflected in the wizard’s list. To see the latest changes, go back to the Machine Management page in the wizard and reselect the resources associated with the host connection. Or, close and restart the wizard. It can take up to 10 minutes for changes made in Azure to appear in the Full Configuration interface.

If your connection uses a service principal that can access empty resource groups in various regions, they appear in the available list. Be sure to choose resource groups in the same region where you’re creating the machine catalog.

Troubleshooting

  • Resource groups don’t appear in the list on the Resource Groups page of the catalog creation wizard.

    The service principal must have appropriate permissions applied to the resource groups you want to appear in the list. See Requirements.

More information