Today I am pleased to announce support in Citrix Studio for provisioning XenApp and XenDesktop workloads into existing Azure resource groups. Until now, this popular “bring your own resource groups (BYO RG)” capability was available only via PowerShell as was described in Ole Larsen’s blog post.

While several of our customers found this “BYO” capability extremely valuable, especially for production deployments with well-defined and segmented Azure security boundaries (and personnel managing those boundaries), they also provided feedback about wanting this capability in the UI rather than just PoSH scripting, since the latter can be complicated and error prone. What we are announcing now, summarized in the table below, is our response to that feedback.

Service Principal associated with a XenDesktop Host Connection Approach to creating MCS Catalog Create new resource groups BYO existing/pre-created Azure resource groups
So far Going forward
Subscription scoped service principal Citrix Studio Yes No Yes
PowerShell Yes Yes Yes
Narrow scoped service principal Citrix Studio Not possible No Yes
PowerShell Not possible Yes Yes

Before you read the rest of this blog, here is some recommended background readings:

  1. Connecting to Azure Resource Manager in XenApp & XenDesktop
  2. Using XenApp & XenDesktop in Azure Resource Manager
  3. Azure Role Based Access Control in XenApp & XenDesktop
  4. Provisioning XenDesktop on Azure Just Got a Lot Faster


To use your existing resource groups to provision VDAs, make sure you meet the following requirements:

  • You have your resource groups available preferably in the same Azure region as that of your Azure host connection.  At the time of this writing, these existing resource groups are required to be empty.
  • You have a service principal that has contribute permissions on the custom resource groups. The service principle can be either subscription scope service principal or narrow scope service principal. If your Azure host connection is associated with a subscription scope service principal then it already has required permissions. If your Azure host connection is associated with a narrow scope service principal, please make sure you have the necessary permissions as explained earlier. You can either use the “Add Connection and Resources” wizard in Citrix Studio to create a new service principal or use an existing service principal created by PowerShell.
  • If you are using a narrow scope service principal, it should have “read” permission for the resource group holding the master image. Otherwise, the resource group for the master image will not be listed in the Master Image page of the Machine Creation Wizard. You may update your existing narrow scope service principal with the missing “read” permission by following the steps below.
    1. Steps to update existing narrow scope service principal
      Step -1 : In this article, please add the permission “Microsoft.Resources/subscriptions/resourceGroups/read” in the actions of the JSON file, “citrix-custom-reader.json”.
      Step – 2 : Run PowerShell command “Set-AzureRmRoleDefinition -InputFile citrix-custom-reader.json” to update your service principal.
    2. Steps to create new narrow scope service principal
      Step -1 : In this article, please add the permission “Microsoft.Resources/subscriptions/resourceGroups/read” in the actions of the JSON file, “citrix-custom-reader.json”.
      Step -2 : Run PowerShell command “New-AzureRmRoleDefinition -InputFile citrix-custom-reader.json” to make sure your service principal has the “read” permission.
    3. If you have not followed the method recommended in this article, please update your service principal with “Microsoft.Resources/subscriptions/resourceGroups/read” permission on the master image resource group.

Create Catalog Using Existing Resource Groups

Step1 – Create Microsoft Azure host connection either using the “Create new” option or by selecting the “Use existing” option and provide details of existing subscription scope service principal OR create a Microsoft Azure host connection using the “Use existing” option and providing the details of existing Narrow Scope service principal that has contribute permissions on already created existing empty Azure resource groups.

Step 2 – Launch the Machine Catalog Creation wizard from Citrix Studio by navigating to “Machine Catalogs” option “Machine Catalogs” and then selecting option “Create Machine Catalog” from the Actions pane.

On the “Machine Management” page, select the hosting connection you have just created from the “Resource” drop-down list. Proceed in the catalog creation wizard up to “Write Back Cache” page by providing necessary details on each page. To accomplish this task please refer the existing blog Using XenApp & XenDesktop in Azure Resource Manager.


Notice that there is new page “Resource Groups” introduced in this wizard. It is this page which enables allocating pre-created custom Azure resource groups for MCS catalog creation. The“Resource Groups” page provides you the following two options:

  1. Create new resource groups to provision machines – Using the “Create new resource groups to provision machines” option will create the required number of resource groups for the number of machines you want to provision. This is the way XenDesktop traditionally provisions VDAs. If you want to use this option, make sure that the Azure service principal you specified in the hosting connection has the appropriate permission to create and delete resource groups.
  2. Use existing resource groups to provision machines – This is the new option that Citrix Studio supports.  The “Available Provisioning Resource Groups” list displays all the existing empty resource groups based on the permissions specified by your service principal. Use this option when you want to provision VDAs in existing Azure resource groups.



Before you select the existing resource groups for provisioning, you should consider following aspects.

  1. Estimate for existing and future VDA capacity required. Because number of resource groups you will allocate for the catalog depends on you capacity estimates. Due to a limitation in the Machine Creation Services that drives the ARM Plugin, it is not possible to add resource groups once a machine catalog has been created. So you need to allocate the resource groups for your current and future capacity.
  2. For Citrix VDA workloads one resource group can hold a maximum of 240 machines.
    You can use the following formula to calculate the number of resource groups you will need:number of resource groups = ceiling (number of virtual machines / 240)Citrix Studio helps you to do the validation, too. If the resource groups you selected do not have sufficient quota to hold the number of virtual machines you want to provision, an error will appear when you click “Next” button on the “Resource Groups” page.image2017-6-22_11-30-29
  3. Recommended practice is to allocate the empty resource groups for the catalog from the same Azure region as that of the host connection.
  4. You also need to keep in mind whether an empty resource group has already been assigned to some other machine catalog. At the time of this writing, Citrix Studio only checks whether or not the existing resource group is empty; it doesn’t check for other machine catalog assignments. Citrix recommends you should not allocate one resource group to more than one catalog.

Proceed in the machine creation wizard by providing necessary details on each of the following page. After you click “Finish” on the Summary page, the catalog provision begins. If you observe the empty resource groups you allocated for this catalog from the Azure portal, you will notice that those resource groups are getting populated with various resources  such as NICs, storage accounts etc. required for the catalog. Wait for the provisioning operation to finish. Once the provisioning is over you have all the necessary resource groups provisioned in the custom Azure resource groups.

Add machines to the catalog created with existing resource groups

There is no UI or process difference between adding machines to a catalog using Citrix-created resource groups and to a catalog using existing resource groups. However, since XenDesktop does not have permissions to create new resource groups, it is your responsibility to make sure the total number of machines in this catalog does not exceed the quota of the total resource groups allocated during the initial catalog creation.

Delete catalog created with existing resource groups

There is no UI or process difference between deleting a catalog using Citrix-created resource groups and using existing resource groups. However, if the catalog is created with existing resource groups, the resource groups are not deleted when the catalog is deleted. If the catalog is created with Citrix-created resource groups, the resource groups are deleted when the catalog is deleted.

Things to be aware of:

  • When selecting resource groups, if you switch between the “Create new resource groups to provision machines” and “Use existing resource groups to provision machines” options, any resource groups you previously selected will be discarded. You will need to re-select resource groups if you choose to use existing resource groups.
  • The list of “Available Provisioning Resource Groups” does not auto-refresh. If you are on the “Resource Groups” page and create or add permission to some new empty resource group, the list will not present the changes you made on the fly. You can either go back to the “Machine Management” page to re-select the resources associated with your host connection or close and re-open the wizard to get your latest changes on your resource groups. Note the changes you made in Azure usually takes more than 5 minutes to populate in Citrix Studio.
  • At the time of writing, the following pre-flight validations are not considered part of this feature.
    • Validate that the service principal has the necessary permissions on the specified resource groups.
  • XenDesktop in its current version can not detect and/or prevent that the same resource group is used in multiple catalogs. Customers can allocate more than required resource groups  to a catalog during creation time. For example you can allocate 10 resource groups to a catalog but can create only 1 machine in the catalog. So 9 of your resource groups will be still empty after the initial catalog is created. You can use these additional resource groups to expand your capacity in future, but these empty resource groups will show up as available for provisioning new catalog. XenDesktop can’t keep track of which resource groups are allocated to which catalogs, it is the your responsibility to make sure you are selecting empty resource groups such that they are not shared between the catalogs.
  • Make sure your service principal has the contributor permissions:
    1. The resource group showing up as available for provisioning does not mean the service principal has the contributor permissions to perform the provisioning into that resource group. If there is an empty resource group but the Service Principal has only read access on that resource group, the resource group will show up as available for provisioning in the resource group page, but provisioning will fail because the Service Principal doesn’t have contributor permissions on that resource group.
    2. If you select option “Create new resource groups to provision machines” and click “Next” button on the “Resource Groups” page, a warning message pops-up telling you to confirm whether the service principal associated with the host connection used for this catalog creation has permissions to create/delete resource groups, since that is the requirement to use this option as we discussed earlier. But in case the host connection associated with this catalog creation is a narrow scope service principal and you choose to ignore this warning message and decide to proceed using the option “Create new resource groups to provision machines”, the catalog creation will fail since the narrow service principal doesn’t have permissions to create a new resource groups.

    In both cases, you will get the error message “… does not have authorization to perform action “Microsoft.Storage/storageAccounts/write” over scope…”.image2017-8-16_16-2-14-1