Product Documentation

Microsoft Azure Resource Manager virtualization environments

Sep 27, 2017

Follow the guidance below when using Microsoft Azure Resource Manager to provision virtual machines in your XenApp or XenDesktop deployment.

You should be familiar with the following:

Azure Disk Encryption is not supported when using Machine Creation Services.

Azure on-demand provisioning

When you use MCS to create machine catalogs in 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 the administrator, on-demand provisioning introduces no differences in the Studio 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 Azure on-demand provisioning was used with XenApp and XenDesktop, when MCS created a catalog, the VMs were created in Azure during the provisioning process. 

With Azure on-demand provisioning, VMs are created only when XenApp and XenDesktop initiates a power-on action, after the provisioning completes. A VM is visible in the Azure portal only when it is running. (In Studio, VMs are visible, whether or not 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 XenApp and XenDesktop initiates a power-on action for it. (At that time, the VM's status in Studio changes to On.)

  • For a pooled machine, the operating system disk and write back cache exist only when the VM exists. This 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 is deleted.

When XenApp and XenDesktop initiates a power-off action for a VM, that VM is deleted in Azure and it no longer appears in the Azure portal. (In Studio, the VM's status changes to Off.)

Catalogs created before on-demand provisioning

If you have machine catalogs that were created before XenApp and XenDesktop supported the Azure on-demand provisioning feature (mid-2017), VMs in those catalogs are visible in the Azure portal whether or not they're running. You cannot convert those VMs to on-demand machines.

To take advantage of the performance enhancements and storage cost benefits of on-demand provisioning, create new catalogs using MCS.

Create a connection to Azure Resource Manager

The Connections and resources article contains information about 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 canuse 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 may have a placeholder entry in the directory that does not grant them the necessary permissions, and an error is returned. One way to rectify this is to remove the resources from the directory and add them back explicitly. However, exercise this option carefully, because it may have 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. This typically occurs with older established directory accounts. Workaround: add a new account to the directory, which will take the proper membership value.
  • Resource groups are simply containers for resources, and they may contain resources from regions other than their own region. This can potentially be confusing if you expect all of the resources displayed in a resource group's region to be available.
  • Ensure your network and subnet are large enough to host the number of machines you require. This may require some foresight, but Microsoft helps you specify the right values, with guidance about the address space capacity.

There are two ways to establish a host connection to Azure Resource Manager:

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

Authenticate to Azure Resource Manager to create a new service principal

Before you start, make sure:

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

In the Add Connection and Resources wizard:

  1. On the Connection page, select the Microsoft Azure connection type and your Azure environment.
  2. On the Connection Details page, enter your Azure subscription ID and a name for the connection. The connection name can contain 1-64 characters, and cannot contain only blank spaces or the characters \/;:#.*?=<>|[]{}"'()'). After you enter the subscription ID and connection name, the Create new button is enabled.
  3. Enter the Azure Active Directory account username and password.
  4. Click Sign in.
  5. Click Accept to give XenApp or XenDesktop the listed permissions. XenApp or XenDesktop creates a service principal that allows it to manage Azure Resource Manager resources on behalf of the specified user.
  6. After you click Accept, you are returned to the Connection page in Studio. Notice that when you successfully authenticate to Azure, the Create new and Use existing buttons are replaced with Connected, and a green check mark indicates the successful connection to your Azure subscription.
  7. Indicate which tools to use to create the virtual machines, and then click Next. (You cannot progress beyond this page in the wizard until you successfully authenticate with Azure and accept giving the required permissions.

Resources comprise the region and the network.

  • On the Region page, select a region.
  • On the Network page,
    • Type a 1-64 character resources name to help identify the region and network combination in Studio. A resource name cannot contain only blank spaces, and cannot contain the characters \/;:#.*?=<>|[]{}"'()'.
    • Select a virtual network and resource group pair. (Since you can have more than one virtual network with the same name, pairing the network name with the resource group provides unique combinations.) If you selected a region on the previous page that does not have any virtual networks, you will need to return to that page and select a region that has virtual networks.

Complete the wizard.

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

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

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 will use this password as the application secret when creating the host connection.

To create a service principal:

Step 1: Connect to your Azure Resource Manager subscription.

Login-AzureRmAccount.

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

Select-AzureRmSubscription -SubscriptionID $SubscriptionId;

Step 3: Create the application in your AD tenant.

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

Step 4: Create a service principal.

New-AzureRmADServicePrincipal -ApplicationId $AzureADApplication.ApplicationId

Step 5: Assign a role to the service principal.

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

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

In the Add Connection and Resources wizard:

  1. On the Connection page, select the Microsoft Azure connection type and your Azure environment.
  2. On the Connection Details page, enter your Azure subscription ID and a name for the connection. (The connection name can contain 1-64 characters, and cannot contain only blank spaces or the characters \/;:#.*?=<>|[]{}"'()').
  3. Click Use existing. Provide the subscription ID, subscription name, authentication URL, management URL, storage suffix, Active Directory ID or tenant ID, application ID, and application secret for the existing service principal. After you enter the details, the OK button is enabled. Click OK.
  4. Indicate which tools to use to create the virtual machines, and then click Next. The service principal details you provided will be used to connect to your Azure subscription. (You cannot progress beyond this page in the wizard until you provide valid details for the Use existing option.)

Resources comprise the region and the network.

  • On the Region page, select a region.
  • On the Network page:
    • Type a 1-64 character resources name to help identify the region and network combination in Studio. A resource name cannot contain only blank spaces, and cannot contain the characters \/;:#.*?=<>|[]{}"'()'.
    • Select a virtual network and resource group pair. (Since you can have more than one virtual network with the same name, pairing the network name with the resource group provides unique combinations.) If you selected a region on the previous page that does not have any virtual networks, you will need to return to that page and select a region that has virtual networks.

Complete the wizard.

Create a machine catalog using an Azure Resource Manager master image

This information is a supplement to the guidance in the Create Machine Catalogs article.

A master image is the template that will be used to create the VMs in a Machine Catalog. Before creating the machine catalog, create a master image in Azure Resource Manager. For general information about master images, see the Create Machine Catalogs article.

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) thorugh the containers to the Azure VHD you want to use as the master image. The VHD must have a Citrix VDA installed on it. If the VHD is attached to a VM, the VM must be stopped.
  • The Storage and License Types page appears only when using an Azure Resource Manager master image.

Select a storage type: standard or premium. The storage type affects which machine sizes are offered on the Virtual Machines page of the wizard. Both storage types make multiple synchronous copies of your data within a single data center. For details about Azure storage types and storage replication, see the following:

https://azure.microsoft.com/en-us/documentation/articles/storage-introduction/

https://azure.microsoft.com/en-us/documentation/articles/storage-premium-storage/

https://azure.microsoft.com/en-us/documentation/articles/storage-redundancy/

Select whether or not to use existing on-premises Windows Server licenses. Doing so in conjunction with using existing on-premises Windows Server images utilizes Azure Hybrid Use Benefits (HUB). More details are available at https://azure.microsoft.com/pricing/hybrid-use-benefit/

HUB reduces the cost of running VMs in Azure to the base compute rate since it waives the price of additional Windows Server licenses from the Azure gallery. You need to bring your on-premises Windows Servers images to Azure to use HUB. Azure gallery images are not supported. On-premises Windows Client licenses are currently not supported. See https://blogs.msdn.microsoft.com/azureedu/2016/04/13/how-can-i-use-the-hybrid-use-benefit-in-azure/%23comment-145

To check if the provisioned Virtual Machines are successfully utilizing HUB, run the powershell command

Get-AzureRmVM -ResourceGroup MyResourceGroup -Name MyVM

and check that the license type is Windows_Server. Additional instructions are available at https://azure.microsoft.com/en-us/documentation/articles/virtual-machines-windows-hybrid-use-benefit-licensing/

PREVIEW ONLY: You can use Azure Managed Disks instead of storage accounts. See the Preview: Azure Managed Disks section below.

  • 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 Machine Catalog, you cannot change the machine size. If you later want a different size, delete the catalog and then create a new catalog that uses the same master 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 new resource groups or use existing groups.
    • If you choose to create new resource groups, click Next.
    • If you choose to use existing resource groups, select groups from the Available Provisioning Resource Groups list. Remember:  You must select enough groups to accommodate the machines you're creating in the catalog. Studio displays a message 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 the Azure resource groups section later in this article.

  • 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 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 in Studio, or have new resource groups created for you. 

For information about Azure resource groups, see Azure Resource Manager Overview.

Requirements

  • Each resource group can hold up to 240 VMs. There must be sufficient available empty resource groups in the region where you're creating the catalog. If you want to use existing resource groups when you create a machine catalog, you must select enough available groups to accommodate the number of machines that will be created in the catalog. For example, if you specify 500 machines in the catalog creation wizard, select at least three available provisioning resource groups.  

You cannot add resource groups to a machine catalog after the catalog is created. So, consider adding enough resource groups to accommodate machines you might add to the catalog later.

  • Create empty resource groups in the same region as your host connection.
  • If you want the XenApp and XenDesktop Service to create new 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 XenApp and XenDesktop 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 in Studio 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 Studio, 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. Additionally, when using a narrow scope service principal, you must use PowerShell or the Azure portal to create empty resource groups for each catalog where MCS will provision 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 narrow scope service principal for the host connection and don't see your master 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 master 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 Studio.)

Configure resource groups for a machine catalog in Studio

The Resource Groups page in the catalog creation wizard allows you to choose whether to create new resource gorups or use existing groups. See the section earlier in this article: Create a machine catalog using an Azure Resource Manager master image.

What happens to resource groups when you delete a machine catalog

If you let the XenApp and XenDesktop Service create new resource groups when you create the machine catalog, and then later delete the catalog, those resource groups and all of the 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, limitations, and troubleshooting

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, either 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 Studio.

A resource group should be used in only one machine catalog. However, this is not enforced. For example, you select 10 resource groups when creating a catalog, but create only one machine in the catalog. Nine of the selected resource groups remain empty after the catalog is created. You might intend to use them to expand your capacity in the future, so they remain associated with that catalog. You can't add resource groups to a catalog after the catalog is created, so planning for future growth is sound practice. However, if another catalog is created, those nine resource groups will appear in the available list. XenApp and XenDesktop does not currently keep track of which resource groups are allocated to which catalogs. It's up to you to monitor that.

If your connection uses a service principal that can access empty resource groups in various regions, they will all 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 the Requirements section above.

When adding machines to a previously-created machine catalog, not all machines are provisioned.

After creating a catalog, and later adding more machines to the catalog, do not exceed the machine capacity of the resource groups originally selected for the catalog (240 per group). You cannot add resource groups after the catalog is created. If you attempt to add more machines than the existing resource groups can accommodate, the provisioning fails. 

For example, you create a machine catalog with 300 VMs and 2 resource groups. The resource groups can accommodate up to 480 VMs (240 * 2). If you later try to add 200 VMs to the catalog, that exceeds the capacity of the resource groups (300 current VMs + 200 new VMs = 500, but the resource groups can hold only 480).

Preview: Azure Managed Disks

Using Azure Managed Disks:

  • Simplifies disk management for Azure virtual machines (VMs) by managing the storage accounts associated with the VM disks.
  • Improves machine catalog creation and update time if the master image is in the same Azure region where the machine catalog is created. It also ensures high availability of disks.
  • Allows users to create Machine Creation Service (MCS) catalogs backed by Azure Managed Disks instead of traditional storage accounts.

For more information from Microsoft, see Azure Managed Disks.

Limitations and requirements of this Azure Managed Disks preview

  • This preview is provided "as-is" and is not covered by Citrix Customer Support.
  • This preview should not be used for production workloads.
  • Machine catalogs created using this preview may stop working when the preview is terminated.
  • The master image must be a VHD in a traditional storage account. Azure Managed Disks master images are not currently supported.
  • The Azure region you are provisioning must be Azure Global.  Managed Disks is not currently supported in other Azure regions.
  • The master image VHD selected on the Master Image page of the catalog creation wizard must be in the same Azure region where the catalog is provisioned (for example, West US).

Create an MCS machine catalog

To use this preview feature, there is only one difference in the machine catalog creation wizard.

On the Storage and License Types page, select the check box Use Azure Managed Disks [Preview Only]

If the host connection you are using for the catalog is to a region other than Azure Global, this check box is disabled (because Managed Disks are supported only in the Azure Global region). 

XenApp and XenDesktop automatically prepends the catalog name with Azure-Managed-Disks-Preview-. This helps differentiate Managed Disks catalogs from other types of catalogs.

More information