Microsoft Azure Resource Manager cloud environments
Follow the guidance in this article when using the Microsoft Azure Resource Manager to provision virtual machines in your Citrix Virtual Apps and Desktops deployment.
We assume you are familiar with the following:
- Azure Active Directory: https://docs.microsoft.com/en-in/azure/active-directory/fundamentals/active-directory-whatis/
- Consent framework: https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/plan-an-application-integration
- Service principal: https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals/
Azure on-demand provisioning
With Azure on-demand provisioning, VMs are created only when Citrix Virtual Apps and Desktops initiates a power-on action, after the provisioning completes.
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
When you create an MCS catalog, the Azure portal displays the network security group, network interfaces, base images, and identity disks in the resource groups.
The Azure portal does not show a VM until Citrix Virtual Apps and Desktops initiates a power-on action for it. There are two types of machines with the following differences:
- For a pooled machine, the operating system disk and write-back cache exist only when the VM exists. When you shut down a pooled machine in the console, the VM is not visible in the Azure portal. There is a significant storage cost saving 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. The VM in the Azure portal remains in storage until the machine identity is deleted. When you shut down a dedicated machine in the console, the VM is still visible in the Azure portal.
Connection to Azure Resource Manager
Connections and resources article describes the wizards that create a connection. The following information covers details specific to Azure Resource Manager connections.
Considerations:
- Citrix recommends using Service Principal with contributor role. However, see Minimum permissions section to get the list of minimum permissions.
- 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 the 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 that you want to use for provisioning resources.
- You have global administrator, application administrator, or application developer permissions for authentication. These permissions can be revoked after you create host connection. For more information about roles, see Azure AD built-in roles.
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. The registered application uses the client secret to authenticate to Azure AD. Be sure to change the client secret before it expires. You receive an alert on the console before the secret key expires.
To authenticate to Azure to create a service principal, complete the following steps in the Add Connection and Resources wizard:
-
On the Connection page, select Create a new connection, the Microsoft Azure connection type, and your Azure environment.
-
Select which tools to use to create the virtual machines and then select Next.
-
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
\/;:#.*?=<>|[]{}"'()'
. -
Select Create new and then enter the Azure Active Directory account user name and password.
-
Select Sign in.
-
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.
-
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.
-
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.
-
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.
- 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
-
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. - ActiveDirectoryID: Tenant ID of the application that you registered with Azure AD.
- ApplicationName: Name for the application to be created in Azure AD.
To create a service principal:
-
Connect to your Azure Resource Manager subscription.
Connect-AzAccount
-
Select the Azure Resource Manager subscription where you want to create the service principal.
Get-AzSubscription -SubscriptionId $subscriptionId | Select-AzSubscription
-
Create the application in your AD tenant.
$AzureADApplication = New-AzADApplication -DisplayName $ApplicationName
-
Create a service principal.
New-AzADServicePrincipal -ApplicationId $AzureADApplication.AppId
-
Assign a role to the service principal.
New-AzRoleAssignment -RoleDefinitionName Contributor -ServicePrincipalName $AzureADApplication.AppId –scope /subscriptions/$SubscriptionId
-
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:
-
On the Connection page, select Create a new connection, the Microsoft Azure connection type, and your Azure environment.
-
Select which tools to use to create the virtual machines and then select Next.
-
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
\/;:#.*?=<>|[]{}"'()'
. -
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 that you registered with Azure AD.
- Application ID. Enter the Application (client) ID of the application that 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.
-
Secret expiration date. Enter the date after which the application secret expires. You receive an alert on the console before the secret key expires. However, if the secret key expires, you receive errors.
Note:
For security purposes, the expiration period cannot be more than two years from now.
- 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.
Access to the following endpoints is required for creating an MCS catalog in Azure. Access to these endpoints optimizes connectivity between your network and the Azure portal and its services.
- Authentication URL: https://login.microsoftonline.com/
- Management URL: https://management.azure.com/. This is a request URL for Azure Resource Manager provider APIs. The endpoint for management depends on the environment. For example, for Azure Global, it is https://management.azure.com/, and for Azure US Government, it is https://management.usgovcloudapi.net/.
- Storage suffix: https://*.core.windows.net./. This (*) is a wildcard character for storage suffix. For example, https://demo.table.core.windows.net/.
-
After selecting Save, you return to the Connection Details page. Select Next to continue to the next page.
-
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.
- 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
-
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
An image can be a disk, snapshot, or an image version of an image definition inside Azure Compute Gallery 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.
Using a machine profile with trusted launch as Security Type is mandatory when you select an image or snapshot that has trusted launch enabled. You can then enable or disable SecureBoot and vTPM by specifying their values in the Machine Profile. For information about Azure trusted launch, see Trusted launch for Azure virtual machines.
The machine catalog uses the following properties that are defined in the custom properties:
- Availability zone
- Dedicated Host Group Id
- Disk Encryption Set Id
- OS type
- License type
- Storage type
If these custom properties are not defined explicitly, then the property values are set from the ARM template spec or VM, whichever is used as the machine profile. In addition, if ServiceOffering
is not specified, then it is set from the machine profile.
Note:
If some of the properties are missing from the machine profile and not defined in the custom properties, then the default values of the properties take place wherever applicable.
The following section describes some scenarios at New-ProvScheme
and Set-ProvScheme
when CustomProperties
either have all the properties defined or values are derived from the MachineProfile.
New-ProvScheme Scenarios
-
MachineProfile has all the properties and CustomProperties are not defined. Example:
New-ProvScheme -MachineProfile "XDHyp:\HostingUnits\azureunit\machineprofile.folder\azure.resourcegroup\mpA.vm"
The following values are set as custom properties for the catalog:
Get-ProvScheme | select 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="<mpA-value>"/> <Property xsi:type="StringProperty" Name="OSType" Value="<mpA-value>"/> <Property xsi:type="StringProperty" Name="LicenseType" Value="<mpA-value>"/> <Property xsi:type="StringProperty" Name="DiskEncryptionSetId" Value="<mpA-value>"/> <Property xsi:type="StringProperty" Name="DedicatedHostGroupId" Value="<mpA-value>"/> <Property xsi:type="StringProperty" Name="Zones" Value="<mpA-value>"/> </CustomProperties> <!--NeedCopy-->
-
MachineProfile has some properties and CustomProperties are not defined. Example: MachineProfile only has LicenseType and OsType.
New-ProvScheme -MachineProfile "XDHyp:\HostingUnits\azureunit\machineprofile.folder\azure.resourcegroup\mpA.vm"
The following values are set as custom properties for the catalog:
Get-ProvScheme | select CustomProperties <CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Property xsi:type="StringProperty" Name="OSType" Value="<mpA-value>"/> <Property xsi:type="StringProperty" Name="LicenseType" Value="<mpA-value>"/> </CustomProperties> <!--NeedCopy-->
-
Both MachineProfile and CustomProperties define all properties. Example:
New-ProvScheme -MachineProfile "XDHyp:\HostingUnits\azureunit\machineprofile.folder\azure.resourcegroup\mpA.vm" -CustomProperties $CustomPropertiesA
Custom properties take priority. The following values are set as custom properties for the catalog:
Get-ProvScheme | select 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="<CustomPropertiesA-value>"/> <Property xsi:type="StringProperty" Name="OSType" Value="<CustomPropertiesA-value>"/> <Property xsi:type="StringProperty" Name="LicenseType" Value="<CustomPropertiesA-value>"/> <Property xsi:type="StringProperty" Name="DiskEncryptionSetId" Value="<CustomPropertiesA-value>"/> <Property xsi:type="StringProperty" Name="DedicatedHostGroupId" Value="<CustomPropertiesA-value>"/> <Property xsi:type="StringProperty" Name="Zones" Value="<CustomPropertiesA-value>"/> </CustomProperties> <!--NeedCopy-->
- Some properties are defined in MachineProfile and some properties are defined in CustomProperties. Example:
- CustomProperties define LicenseType and StorageAccountType
- MachineProfile define LicenseType, OsType, and Zones
New-ProvScheme -MachineProfile "XDHyp:\HostingUnits\azureunit\machineprofile.folder\azure.resourcegroup\mpA.vm" -CustomProperties $CustomPropertiesA
The following values are set as custom properties for the catalog:
Get-ProvScheme | select 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="<CustomPropertiesA-value>"/> <Property xsi:type="StringProperty" Name="OSType" Value="<mpA-value>"/> <Property xsi:type="StringProperty" Name="LicenseType" Value="<CustomPropertiesA-value>"/> <Property xsi:type="StringProperty" Name="Zones" Value="<mpA-value>"/> </CustomProperties> <!--NeedCopy-->
-
Some properties are defined in MachineProfile and some properties are defined in CustomProperties. In addition, ServiceOffering is not defined. Example:
- CustomProperties define StorageType
- MachineProfile define LicenseType
New-ProvScheme -MachineProfile "XDHyp:\HostingUnits\azureunit\machineprofile.folder\azure.resourcegroup\mp.vm" -ServiceOffering "XDHyp:\HostingUnits\azureunit\serviceoffering.folder\<explicit-machine-size>.serviceoffering" <!--NeedCopy-->
The following values are set as custom properties for the catalog:
Get-ProvScheme | select ServiceOffering serviceoffering.folder\<explicit-machine-size>.serviceoffering Get-ProvScheme | select 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="explicit-storage-type"/> <Property xsi:type="StringProperty" Name="LicenseType" Value="value-from-machineprofile"/> </CustomProperties> <!--NeedCopy-->
- If the OsType is in neither in the CustomProperties nor in the MachineProfile, then:
- The value is read from the master image.
- If the master image is an unmanaged disk, the OsType is set to Windows.
Example:
New-ProvScheme -MachineProfile "XDHyp:\HostingUnits\azureunit\machineprofile.folder\azure.resourcegroup\mpA.vm" -MasterImageVM "XDHyp:\HostingUnits\azureunit\image.folder\linux-master-image.manageddisk"
The value from the master image is written to the custom properties, in this case Linux.
Get-ProvScheme | select CustomProperties <CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Property xsi:type="StringProperty" Name="OSType" Value="Linux"/> </CustomProperties> <!--NeedCopy-->
Set-ProvScheme Scenarios
- An existing catalog with:
- CustomProperties for
StorageAccountType
and OsType - MachineProfile
mpA.vm
that defines zones
Updates:
- MachineProfile mpB.vm that defines StorageAccountType
- A new set of custom properties $CustomPropertiesB that defines LicenseType and OsType
Set-ProvScheme -MachineProfile "XDHyp:\HostingUnits\azureunit\machineprofile.folder\azure.resourcegroup\mpB.vm" -CustomProperties $CustomPropertiesB
The following values are set as custom properties for the catalog:
Get-ProvScheme | select 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="<mpB-value>"/> <Property xsi:type="StringProperty" Name="OSType" Value="<CustomPropertiesB-value>"/> <Property xsi:type="StringProperty" Name="LicenseType" Value="<CustomPropertiesB-value>"/> </CustomProperties> <!--NeedCopy-->
- CustomProperties for
- An existing catalog with:
- CustomProperties for S
torageAccountType
and OsType - MachineProfile
mpA.vm
that defines StorageAccountType and LicenseType
Updates:
- A new set of custom properties $CustomPropertiesB that defines StorageAccountType and OsType.
Set-ProvScheme -CustomProperties $CustomPropertiesB
The following values are set as custom properties for the catalog:
Get-ProvScheme | select 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="<CustomPropertiesB-value>"/> <Property xsi:type="StringProperty" Name="OSType" Value="<CustomPropertiesB-value>"/> <Property xsi:type="StringProperty" Name="LicenseType" Value="<mp-A-value>"/> </CustomProperties> <!--NeedCopy-->
- CustomProperties for S
- An existing catalog with:
- CustomProperties for
StorageAccountType
and OsType - MachineProfile
mpA.vm
that defines Zones
Updates:
- A MachineProfile mpB.vm that defines StorageAccountType and LicenseType
-
ServiceOffering
is not specified
Set-ProvScheme -MachineProfile "XDHyp:\HostingUnits\azureunit\machineprofile.folder\azure.resourcegroup\mpB.vm"
The following values are set as custom properties for the catalog:
Get-ProvScheme | select ServiceOffering serviceoffering.folder\<value-from-machineprofile>.serviceoffering Get-ProvScheme | select 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="<mpB-value>"/> <Property xsi:type="StringProperty" Name="OSType" Value="<prior-CustomProperties-value>"/> <Property xsi:type="StringProperty" Name="LicenseType" Value="<mpB-value>"/> </CustomProperties> <!--NeedCopy-->
- CustomProperties for
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, you can 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
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, consider:
- Default value of
MaximumConcurrentProvisioningOperations
is 500. - Configure the
MaximumConcurrentProvisioningOperations
parameter using the PowerShell commandSet-item
.
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 or temporary 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": "StorageType",
"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 provision ephemeral OS disks using New-ProvScheme
, consider the following constraints:
- The VM size used for the catalog must support ephemeral OS disks.
- The size of the cache or temporary disk associated with the VM size must be greater than or equal to the size of the OS disk.
- The temporary disk size must be greater than the cache disk size.
Also consider these issues when:
- Creating the provisioning scheme.
- Modifying the provisioning scheme.
- Updating the image.
Azure ephemeral disk and Machine Creation Services (MCS) storage optimization (MCS I/O)
Azure ephemeral OS disk and MCS I/O cannot be enabled at the same time.
The important considerations are as follows:
-
You cannot create a machine catalog with both ephemeral OS disk and MCS I/O enabled at the same time.
- The PowerShell parameters (
UseWriteBackCache
andUseEphemeralOsDisk
) fail with proper error messages if you set them to true inNew-ProvScheme
orSet-ProvScheme
. - For existing machine catalogs created with both features enabled, you can still:
- update a machine catalog.
- add or delete VMs.
- delete a machine catalog.
Azure server side encryption
Citrix Virtual Apps and Desktops and Citrix DaaS 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 thatDiskEncryptionSet
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 that 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.
-
Refer to the Microsoft site for limitations on disk encryption sets per region.
Note:
See Quickstart: Create a Key Vault using the Azure portal for information on configuring Azure server side encryption.
Azure Customer-managed encryption key
When creating a machine catalog, you can choose whether to encrypt data on the machines provisioned in the catalog. Server-side encryption with a customer-managed encryption key lets you manage encryption at a managed disk level and protect data on the machines in the catalog. A Disk Encryption Set (DES) represents a customer-managed key. To use this feature, you must first create your DES in Azure. A DES is in the following format:
/subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/Sample-RG/providers/Microsoft.Compute/diskEncryptionSets/SampleEncryptionSet
Select a DES from the list. The DES you select must be in the same subscription and region as your resources. If your image is encrypted with a DES, use the same DES when creating the machine catalog. You cannot change the DES after you create the catalog.
If you create a catalog with an encryption key and later disable the corresponding DES in Azure, you can no longer power on the machines in the catalog or add machines to it.
Azure dedicated hosts
You can use MCS to provision VMs on Azure dedicated hosts. Before provisioning VMs on Azure dedicated hosts:
- Create a host group.
- Create hosts in that host group.
- Ensure that there is sufficient host capacity reserved for creating catalogs and virtual machines.
You can create a catalog of machines with host tenancy defined through the following PowerShell script:
New-ProvScheme <otherParameters> -CustomProperties '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="HostGroupId" Value="myResourceGroup/myHostGroup" />
...other Custom Properties...
</CustomProperties>
<!--NeedCopy-->
When using MCS to provision virtual machines on Azure dedicated hosts, consider:
- A Dedicated host is a catalog property and cannot be changed once the catalog is created. Dedicated tenancy is currently not supported on Azure.
- A pre-configured Azure host group, in the region of the hosting unit, is required when using the
HostGroupId
parameter. - Azure auto-placement is required. This functionality makes a request to onboard the subscription associated with the host group. For more information, see VM Scale Set on Azure Dedicated Hosts - Public Preview. If auto-placement is not enabled, MCS throws an error during catalog creation.
Azure Shared Image Gallery
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 start 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.
Note:
Shared Image Gallery functionality is only compatible with managed disks. It is not available for legacy machine catalogs.
For more information, see Azure shared image gallery overview.
Configure Shared Image Gallery
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.
Use case: Updating the Shared Image Gallery replica ratio and replica max
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="StorageType" 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-->
Use Case: Converting a snapshot catalog to a Shared Image Gallery catalog
For this use case:
- Run
Set-ProvScheme
with theUseSharedImageGallery
flag set to True. Optionally include theSharedImageGalleryReplicaRatio
andSharedImageGalleryReplicaMaximum
properties. - Update the catalog.
- 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="StorageType" 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
andSharedImageGalleryReplicaMaximum
are not required. After theSet-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.
Use Case: Converting a Shared Image Gallery Catalog to a snapshot catalog
For this use case:
- Run
Set-ProvScheme
with theUseSharedImageGallery
flag set to False or not defined. - Update the catalog.
- 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="StorageType" 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 theSet-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 thatUseSharedImageGallery
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 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 through PowerShell
Using PowerShell, you can view the 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 or temporary 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 uses 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
andUseSharedImageGallery
.
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-->
Storing an ephemeral OS temporary disk
You have the option of storing an ephemeral OS disk on the VM temp disk or a resource disk. This functionality enables you to use an ephemeral OS disk with a VM that either doesn’t have a cache, or has insufficient cache. Such VMs have a temp or resource disk to store an ephemeral OS disk, such as Ddv4
.
Consider the following:
- An ephemeral disk is stored either in the VM cache disk, or the VM’s temporary (resource) disk. The cache disk is preferred over the temporary disk, unless the cache disk is not large enough to hold the contents of the OS disk.
- For updates, a new image that is larger than the cache disk but smaller than the temp disk results in replacing the ephemeral OS disk with the VM’s temp disk.
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 propertiesCleanOnBoot
andUseWriteBackCache
enabled. If thePersistVm
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 PersistVm
property 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="StorageType" 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=`"StorageType`" 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. ThePersistOsdisk
property determines whether to persist the OS disk. To preserve a provisioned virtual machine, preserve the OS disk first. Do not delete the OS disk without first deleting the virtual machine. You can use thePersistOsdisk
property without using specifying thePersistVm
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, you do not get the option for write-back cache disk setting.
Tip:
StorageType
is configured for an OS type and storage account.WBCDiskStorageType
is configured for write-back cache storage type. For a normal catalog,StorageType
is required. IfWBCDiskStorageType
is not configured, theStorageType
is used as the default forWBCDiskStorageType
.
If WBCDiskStorageType is not configured, then StorageType is used as the default for WBCDiskStorageType
Configuring storage types
To configure storage types for VM, use the StorageType
parameter in New-ProvScheme
. Set the value of the StorageType
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="StorageType" Value="Premium_LRS" />
<Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client" />
</CustomProperties>'
<!--NeedCopy-->
Change the storage type to a lower tier when a VM is shut down
You can save storage costs by switching the storage type of a managed disk to a lower tier when you shut down a VM. To do this, use the StorageTypeAtShutdown
custom property.
The storage type of the disk changes to a lower tier (as specified in the StorageTypeAtShutdown
custom property) when you shut down the VM. After you power on the VM, the storage type changes back to the original (as specified in StorageType
custom property or WBCDiskStorageType
custom property).
Important:
The disk does not exist until the VM is powered on at least once. Therefore, you cannot change the storage type when you first power on the VM.
Requirements
- Applicable to a managed disk. This implies that you set the custom property
UseManagedDisks
to true. - Applicable to a persistent and non-persistent catalog with a persistent OS disk. This implies that you set the custom property
persistOsDisk
to true. - Applicable to a non-persistent catalog with a persistent WBC disk. This implies that you set the custom property
persistWBC
to true.
Restriction
- As per Microsoft, you can only change the disk type twice per day. See the Microsoft document. As per Citrix, the
StorageType
update happens whenever there is a Start or Deallocate action for the VM. Therefore, limit the number of power actions per VM to twice per day. For example, one power action in the morning to start the VM and one in the evening to deallocate the VM.
Change the storage type to a lower tier
Before proceeding with the steps, see the Requirements and Restriction.
-
Add the custom property
StorageTypeAtShutdown
, set the value to Standard_LRS (HDD), and create a catalog usingNew-ProvScheme
. For information on creating a catalog using PowerShell, see https://developer-docs.citrix.com/projects/citrix-virtual-apps-desktops-sdk/en/latest/creating-a-catalog/.Note:
If
StorageTypeAtShutdown
has any value other than empty or Standard_LRS (HDD), the operation fails.Example of setting custom properties while creating a persistent catalog:
$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="StorageType" Value="Premium_LRS“ /> <Property xsi:type="StringProperty" Name="ResourceGroups" Value="" /> <Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client" /> <Property xsi:type="StringProperty" Name="SchemaVersion" Value="2" /> <Property xsi:type="StringProperty" Name="OsType" Value="Windows" /> <Property xsi:type="StringProperty" Name="StorageTypeAtShutdown" Value="Standard_LRS" /> </CustomProperties>’ <!--NeedCopy-->
Example of setting custom properties while creating a non-persistent catalog:
$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="StorageType" Value="Premium_LRS" /> <Property xsi:type="StringProperty" Name="WbcDiskStorageType" Value="Standard_SSD_LRS" /> <Property xsi:type="StringProperty" Name="ResourceGroups" Value="" /> <Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client" /> <Property xsi:type="StringProperty" Name="SchemaVersion" Value="2" /> <Property xsi:type="StringProperty" Name="OsType" Value="Windows" /> <Property xsi:type="BooleanProperty" Name="persistWBC" Value=true /> <Property xsi:type="BooleanProperty" Name="persistOsDisk" Value=true /> <Property xsi:type="StringProperty" Name="StorageTypeAtShutdown" Value="Standard_LRS" /> </CustomProperties>’ <!--NeedCopy-->
Note:
When you use a machine profile, the custom property takes precendence over the property defined in
MachineProfile
. - Shut down the VM and check the storage type of the VM in Azure portal. The storage type of the disk changes to a lower tier, as specified in the
StorageTypeAtShutdown
custom property. - Turn on the VM. The storage type of the disk switches back to the storage type mentioned in:
-
StorageType
custom property for OS disk -
WBCDiskStorageType
custom property for WBC disk only if you specify it inCustomProperties
. Otherwise, it switches back to the storage type mentioned inStorageType
.
-
Apply StorageTypeAtShutdown
to an existing catalog
Before proceeding with the steps, see the Requirements and Restriction.
Use Set-ProvScheme
to add a VM to an existing catalog. The feature applies to new VMs added after running Set-ProvScheme
. The existing machines are not affected.
Example of setting custom properties while adding a VM to an existing catalog:
$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="StorageType" Value="Premium_LRS" />
<Property xsi:type="StringProperty" Name="WbcDiskStorageType" Value="Standard_SSD_LRS" />
<Property xsi:type="StringProperty" Name="ResourceGroups" Value="" />
<Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client" />
<Property xsi:type="StringProperty" Name="SchemaVersion" Value="2" />
<Property xsi:type="StringProperty" Name="OsType" Value="Windows" />
<Property xsi:type="BooleanProperty" Name="persistWBC" Value=true />
<Property xsi:type="BooleanProperty" Name="persistOsDisk" Value=true />
<Property xsi:type="StringProperty" Name="StorageTypeAtShutdown" Value="Standard_LRS" />
</CustomProperties>’
$ProvScheme = Get-Provscheme -ProvisioningSchemeName $CatalogName
Set-ProvScheme -ProvisioningSchemeName $ProvScheme.ProvisioningSchemeName -CustomProperties $customProperties
<!--NeedCopy-->
Update provisioned machines to current provisioning scheme state
The Set-ProvScheme
command changes the provisioning scheme. However, it does not affect existing machines. Using the PowerShell command Request-ProvVMUpdate
, you can apply the current provisioning scheme to an existing persistent or non-persistent machine or set of machines. Currently, in Azure, you can update ServiceOffering
, MachineProfile
and the following custom properties:
StorageType
WBCDiskStorageType
IdentityDiskStorageType
LicenseType
DedicatedHostGroupId
PersistWBC
PersistOsDisk
PersistVm
Note:
You can only update
StorageType
,WBCDiskStorageType
, andIdentityDiskStorageType
custom properties for a catalog using managed disk in Azure environments. You can update:
- A single VM
- A list of specific VMs or all existing VMs associated with a provisioning scheme ID
- A list of specific VMs or all existing VMs associated with a provisioning scheme name (machine catalog name)
After you make the following changes to the provisioning scheme, VM instance gets recreated for persistent catalogs in Azure:
- Change the
MachineProfile
- Remove
LicenseType
- Remove
DedicatedHostGroupId
Note:
The OS disk of existing machines along with all its data remains as is and a new VM is attached to the disk. To update the existing VMs:
-
Check the configuration of the existing machines. For example,
Get-ProvScheme | select ProvisioningSchemeName, ProvisioningSchemeVersion <!--NeedCopy-->
-
Update the provisioning scheme. For example,
-
With VM as a machine profile input:
Set-ProvScheme -ProvisioningSchemeName "my-catalog" -MachineProfile "XDHyp:\HostingUnits\<hosting-unit>\machineprofile.folder\<resource-group>.resourcegroup\<virtual-machine>.vm" <!--NeedCopy-->
-
With template spec as a machine profile input:
Set-ProvScheme -ProvisioningSchemeName "my-catalog" -MachineProfile "XDHyp:\HostingUnits\<hosting-unit>\machineprofile.folder\<resource-group>.resourcegroup\<template-spec>.templatespec\<template-spec-version>.templatespecversion" -ServiceOffering "XDHyp:\HostingUnits\<hosting-unit>\serviceoffering.folder\<service-offering>.serviceoffering" <!--NeedCopy-->
-
With just service offering:
Set-ProvScheme -ProvisioningSchemeName "my-catalog" -ServiceOffering "XDHyp:\HostingUnits\<hosting-unit>\serviceoffering.folder\<service-offering>.serviceoffering" <!--NeedCopy-->
-
-
Check if the current property of the VM matches the current provisioning scheme, and if there is any pending update action on the VM. For example,
Get-ProvVM | select VMName, ProvisioningSchemeUpdateRequested, ProvisioningSchemeVersion <!--NeedCopy-->
You can also find machines with a particular version. For example,
Get-ProvVM -Filter "ProvisioningSchemeVersion -eq 1" | select VMName, ProvisioningSchemeVersion <!--NeedCopy-->
-
Update existing machines.
-
To update all the existing machines. For example,
Request-ProvVMUpdate –ProvisioningSchemeName “my-catalog” <!--NeedCopy-->
-
To update a list of specific machines. For example,
Request-ProvVMUpdate -ProvisioningSchemeName "my-catalog" -VMName "vm1","vm2" <!--NeedCopy-->
-
To update machines based on the output of Get-ProvVM. For example,
Get-ProvVM -ProvisioningSchemeName "my-catalog" | Request-ProvVMUpdate <!--NeedCopy-->
-
-
Find machines with an update scheduled. For example,
Get-ProvVM -Filter "ProvisioningSchemeUpdateAfter" | select VMName, ProvisioningSchemeUpdateAfter <!--NeedCopy-->
-
Restart the machines. At the next power up, property changes are applied to the existing machines. You can check the updated status using the following command. For example,
Get-ProvVM | select VMName, ProvisioningSchemeUpdateRequested, ProvisioningSchemeVersion <!--NeedCopy-->
Schedule configuration updates
You can schedule a time slot for the configuration updates of the existing MCS provisioned machines using the PowerShell command Schedule-ProvVMUpdate
. Any power on or restart during the scheduled time slot applies a scheduled provisioning scheme update to a machine.
If you run both Request-ProvVMUpdate
and Schedule-ProvVMUpdate
command, then the most recent command takes effect.
Note:
Schedule-ProvVMUpdate
has all the functionalities ofRequest-ProvVMUpdate
and more. Eventually,Schedule-ProvVMUpdate
will replaceRequest-ProvVMUpdate
.
You can also cancel the configuration update before the scheduled time using Cancel-ProvVMUpdate
.
You can schedule configuration update of:
- A single VM
- Multiple VMs associated with a provisioning scheme ID or a provisioning scheme name
- An entire catalog associated with a provisioning scheme ID or a provisioning scheme name
To schedule configuration update:
- Create a catalog using the Full Configuration interface or PowerShell.
- Open a PowerShell window.
- Run
asnp citrix*
to load Citrix-specific PowerShell modules. -
Check the configuration of the existing machines. For example,
Get-ProvScheme | select ProvisioningSchemeName, ProvisioningSchemeVersion <!--NeedCopy-->
-
Update the provisioning scheme to update a custom property, machine profile, or service offering. For example,
Set-ProvScheme –ProvisioningSchemeName “my-catalog” – MachineProfile“XDHyp:\HostingUnits\<hosting-unit>\machineprofileinstance.vm” <!--NeedCopy-->
-
Check if:
- the current property of the VM matches the current provisioning scheme, and
- there is any pending update action on the VM.
For example,
Get-ProvVM | select VMName, ProvisioningSchemeUpdateRequested, ProvisioningSchemeUpdateUntil, ProvisioningSchemeVersion <!--NeedCopy-->
-
Run
Schedule-ProvVMUpdate
to schedule a VM to update to the latest provisioning settings next time it starts in the scheduled time window. For example,-
To schedule an update with start time as the current time
Schedule-ProvVMUpdate -ProvisioningSchemeName " my-catalog " -VMName "vm1" -StartsNow -DurationInMinutes 120 <!--NeedCopy-->
-
To schedule an update on a weekend
Schedule-ProvVMUpdate -ProvisioningSchemeName " my-catalog " -VMName "vm1" -StartTimeInUTC "10/15/2022 9:00am" -DurationInMinutes (New –TimeSpan –Days 2).TotalMinutes <!--NeedCopy-->
Note:
-
VMName
is optional. If not specified, the update is scheduled for the entire catalog. - Instead of
StartTimeInUTC
, useStartsNow
to indicate that the schedule start time is the current time. -
DurationInMinutes
is optional. Default is 120 minutes. A negative number (for example, –1) indicates no upper bound on schedule’s time window.
-
-
Check the update status.
Get-ProvVM | select VMName, ProvisioningSchemeUpdateRequested, ProvisioningSchemeUpdateUntil, ProvisioningSchemeVersion <!--NeedCopy-->
-
Power on the VM. If you power on the machine after the scheduled time slot, configuration update is not applied. If you power on the machine within the scheduled time slot,
-
If the machine is powered off, and
- you do not power on the machine, configuration update is not applied
- you power on the machine, configuration update is applied
-
If the machine is powered on, and
- you do not restart the machine, configuration update is not applied
- you restart the machine, configuration update is applied
-
You can also cancel a configuration update of a single VM, multiple VMs, or an entire catalog. To cancel a configuration update:
-
Run
Cancel-ProvVMUpdate
. For example,-
To cancel the configuration update scheduled for a single VM:
Cancel-ProvVMUpdate -ProvisioningSchemeName " my-catalog " -VMName "vm1" <!--NeedCopy-->
-
To cancel the configuration update scheduled for multiple VMs.
Cancel-ProvVMUpdate -ProvisioningSchemeName "my-catalog" -VMName "vm1","vm2" <!--NeedCopy-->
Note:
The VMs must be from the same catalog.
-
Retrieve information for Azure VMs, snapshots, OS disk, and gallery image definition
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 theTemplateIsWindowsTemplate
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-->
Machine catalogs with Trusted launch
To successfully create a machine catalog with Trusted launch, use:
- A machine profile with Trusted launch
- A VM size that supports Trusted launch
- A Windows VM version that supports Trusted launch. Currently, Windows 10, Windows Server 2016, 2019, and 2022 support trusted launch.
Important:
Trusted launch requires the creation of new VMs. You cannot enable Trusted launch on existing VMs that were initially created without it.
To view the Citrix DaaS offering inventory items, and to determine whether the VM size supports Trusted launch, run the following command:
- Open a PowerShell window.
- Run asnp citrix* to load the Citrix-specific PowerShell modules.
-
Run the following command:
$s = (ls XDHyp:\HostingUnits\<name of hosting unit>\serviceoffering.folder\“<VM size>.serviceoffering) <!--NeedCopy-->
- Run
$s | select -ExpandProperty Additionaldata
-
Check the value of the
SupportsTrustedLaunch
attribute.- If
SupportsTrustedLaunch
is True, the VM size supports Trusted launch. - If
SupportsTrustedLaunch
is False, the VM size does not support Trusted launch.
- If
As per Azure’s PowerShell, you can use the following command to determine the VM sizes that support Trusted launch:
(Get-AzComputeResourceSku | where {$_.Locations.Contains($region) -and ($_.Name -eq “<VM size>”) })[0].Capabilities
<!--NeedCopy-->
Following are examples that describe whether the VM size supports Trusted launch after you run the Azure PowerShell command.
-
Example 1: If the Azure VM supports only Generation 1, that VM does not support trusted launch. Therefore, the
TrustedLaunchDisabled
capability is not displayed after you run the Azure PowerShell command. -
Example 2: If the Azure VM supports only Generation 2 and the
TrustedLaunchDisabled
capability is True, the Generation 2 VM size is not supported for Trusted launch. -
Example 3: If the Azure VM supports only Generation 2 and the
TrustedLaunchDisabled
capability is not displayed after you run the PowerShell command, the Generation 2 VM size is supported for Trusted launch.
For more information on Trusted launch for Azure virtual machines, see the Microsoft document Trusted launch for Azure virtual machines.
Errors while creating machine catalogs with Trusted launch
You get appropriate errors in the following scenarios while creating a machine catalog with trusted launch:
Scenario | Error |
---|---|
If you select a machine profile while creating an unmanaged catalog | MachineProfileNotSupportedForUnmanagedCatalog |
If you select a machine profile that supports Trusted launch while creating a catalog with unmanaged disk as the master image | SecurityTypeNotSupportedForUnmanagedDisk |
If you do not select a machine profile while creating a managed catalog with a master image source with Trusted launch as the security type | MachineProfileNotFoundForTrustedLaunchMasterImage |
If you select a machine profile with a security type different from the security type of the master image | SecurityTypeConflictBetweenMasterImageAndMachineProfile |
If you select a VM size that does not support Trusted launch but use a master image that supports Trusted launch while creating a catalog | MachineSizeNotSupportTrustedLaunch |
Azure Marketplace
Citrix Virtual Apps and Desktops and Citrix DaaS supports using a master image on Azure that contains plan information to create a machine catalog. For more information, see Microsoft Azure Marketplace.
Tip:
Some images found on the Azure Marketplace, like the standard Windows Server image, do not append plan information. Citrix DaaS feature is for paid images.
Ensure that the image created in Shared Image Gallery contains Azure plan information
Use the procedure in this section to view Shared Image Gallery images in Citrix Studio. These images can optionally be used for a master image. To put the image into a Shared Image Gallery, create an image definition in a gallery.
In the Publishing options page, verify the purchase plan information.
The purchase plan information fields are initially empty. Populate those fields with the purchase plan information used for the image. Failure to populate purchase plan information can cause the machine catalog process to fail.
After verifying the purchase plan information, create an image version within the definition. This is used as the master image. Click Add version:
In the Version details section, select the image snapshot or managed disk as the source:
About Azure permissions
This section contains the minimum and general permissions required for Azure .
Minimum permissions
Minimum permissions give better security control. However, new features that require additional permissions will fail because of using only minimum permissions.
Creating a host connection
Add a new host connection using the information obtained from Azure.
"Microsoft.Network/virtualNetworks/read",
"Microsoft.Compute/virtualMachines/read",
"Microsoft.Compute/disks/read",
<!--NeedCopy-->
Power management of VMs
Power on or off the machine instances.
"Microsoft.Compute/virtualMachines/read",
"Microsoft.Resources/subscriptions/resourceGroups/read",
"Microsoft.Compute/virtualMachines/deallocate/action",
"Microsoft.Compute/virtualMachines/start/action",
"Microsoft.Compute/virtualMachines/restart/action",
<!--NeedCopy-->
Creating, updating, or deleting VMs
Create a machine catalog, then add, delete, update machines, and delete the machine catalog.
Following is the list of minimum permissions required when the master image is managed disk or snapshots are located in the same region as the hosting connection.
"Microsoft.Resources/subscriptions/resourceGroups/read",
"Microsoft.Resources/deployments/validate/action",
"Microsoft.Compute/virtualMachines/read",
"Microsoft.Compute/virtualMachines/write",
"Microsoft.Compute/virtualMachines/delete",
"Microsoft.Compute/virtualMachines/deallocate/action",
"Microsoft.Compute/snapshots/read",
"Microsoft.Compute/snapshots/write",
"Microsoft.Compute/snapshots/delete",
"Microsoft.Compute/snapshots/beginGetAccess/action",
"Microsoft.Compute/snapshots/endGetAccess/action",
"Microsoft.Compute/disks/read",
"Microsoft.Compute/disks/write",
"Microsoft.Compute/disks/delete",
"Microsoft.Compute/disks/beginGetAccess/action",
"Microsoft.Compute/disks/endGetAccess/action",
"Microsoft.Network/virtualNetworks/read",
"Microsoft.Network/virtualNetworks/subnets/join/action",
"Microsoft.Network/virtualNetworks/subnets/read",
"Microsoft.Network/networkSecurityGroups/read",
"Microsoft.Network/networkSecurityGroups/write",
"Microsoft.Network/networkSecurityGroups/delete",
"Microsoft.Network/networkSecurityGroups/join/action",
"Microsoft.Network/networkInterfaces/read",
"Microsoft.Network/networkInterfaces/write",
"Microsoft.Network/networkInterfaces/delete",
"Microsoft.Network/networkInterfaces/join/action",
<!--NeedCopy-->
You need the following extra permissions based on minimal permissions for the following features:
-
If the master image is a VHD in a storage account located in the same region as the hosting connection:
"Microsoft.Storage/storageAccounts/read", "Microsoft.Storage/storageAccounts/listKeys/action", <!--NeedCopy-->
-
If the master image is an ImageVersion from the Shared Image Gallery:
"Microsoft.Compute/galleries/read", "Microsoft.Compute/galleries/images/read", "Microsoft.Compute/galleries/images/versions/read", <!--NeedCopy-->
-
If the master image is a managed disk. Snapshots, or VHD is in a region different from the region of hosting connection:
"Microsoft.Storage/storageAccounts/read", "Microsoft.Storage/storageAccounts/listKeys/action", "Microsoft.Storage/storageAccounts/write", "Microsoft.Storage/storageAccounts/delete", <!--NeedCopy-->
-
If you use Citrix-managed resource group:
"Microsoft.Resources/subscriptions/resourceGroups/write", "Microsoft.Resources/subscriptions/resourceGroups/delete", <!--NeedCopy-->
-
If you put the master image in Shared Image Gallery:
"Microsoft.Compute/galleries/write", "Microsoft.Compute/galleries/images/write", "Microsoft.Compute/galleries/images/versions/write", "Microsoft.Compute/galleries/read", "Microsoft.Compute/galleries/images/read", "Microsoft.Compute/galleries/images/versions/read", "Microsoft.Compute/galleries/delete", "Microsoft.Compute/galleries/images/delete", "Microsoft.Compute/galleries/images/versions/delete", <!--NeedCopy-->
-
If you use Azure dedicated host support:
"Microsoft.Compute/hostGroups/read", "Microsoft.Compute/hostGroups/write", "Microsoft.Compute/hostGroups/hosts/read", <!--NeedCopy-->
-
If you use Server Side Encryption (SSE) with Customer Managed Keys (CMK):
"Microsoft.Compute/diskEncryptionSets/read", <!--NeedCopy-->
-
If you deploy VMs using ARM templates (machine profile):
"Microsoft.Resources/deployments/write", "Microsoft.Resources/deployments/operationstatuses/read", "Microsoft.Resources/deployments/read", "Microsoft.Resources/deployments/delete", <!--NeedCopy-->
-
If you use Azure template spec as a machine profile:
"Microsoft.Resources/templateSpecs/read", "Microsoft.Resources/templateSpecs/versions/read", <!--NeedCopy-->
Creating, updating, and deleting machines with unmanaged disk
Following is the list of minimum permissions required when the master image is VHD and use resource group as provided by admin:
"Microsoft.Resources/subscriptions/resourceGroups/read",
"Microsoft.Storage/storageAccounts/delete",
"Microsoft.Storage/storageAccounts/listKeys/action",
"Microsoft.Storage/storageAccounts/read",
"Microsoft.Storage/storageAccounts/write",
"Microsoft.Compute/virtualMachines/deallocate/action",
"Microsoft.Compute/virtualMachines/delete",
"Microsoft.Compute/virtualMachines/read",
"Microsoft.Compute/virtualMachines/write",
"Microsoft.Resources/deployments/validate/action",
"Microsoft.Network/networkInterfaces/delete",
"Microsoft.Network/networkInterfaces/join/action",
"Microsoft.Network/networkInterfaces/read",
"Microsoft.Network/networkInterfaces/write",
"Microsoft.Network/networkSecurityGroups/delete",
"Microsoft.Network/networkSecurityGroups/join/action",
"Microsoft.Network/networkSecurityGroups/read",
"Microsoft.Network/networkSecurityGroups/write",
"Microsoft.Network/virtualNetworks/subnets/read",
"Microsoft.Network/virtualNetworks/read",
"Microsoft.Network/virtualNetworks/subnets/join/action"
<!--NeedCopy-->
General permission
Contributor role has full access to manage all resources. This set of permissions does not block you from getting new features.
The following set of permissions provides the best compatibility going forward although it does include more permissions than needed with the current feature set:
"Microsoft.Compute/diskEncryptionSets/read",
"Microsoft.Compute/disks/beginGetAccess/action",
"Microsoft.Compute/disks/delete",
"Microsoft.Compute/disks/endGetAccess/action",
"Microsoft.Compute/disks/read",
"Microsoft.Compute/disks/write",
"Microsoft.Compute/galleries/delete",
"Microsoft.Compute/galleries/images/delete",
"Microsoft.Compute/galleries/images/read",
"Microsoft.Compute/galleries/images/versions/delete",
"Microsoft.Compute/galleries/images/versions/read",
"Microsoft.Compute/galleries/images/versions/write",
"Microsoft.Compute/galleries/images/write",
"Microsoft.Compute/galleries/read",
"Microsoft.Compute/galleries/write",
"Microsoft.Compute/hostGroups/hosts/read",
"Microsoft.Compute/hostGroups/read",
"Microsoft.Compute/hostGroups/write",
"Microsoft.Compute/snapshots/beginGetAccess/action",
"Microsoft.Compute/snapshots/delete",
"Microsoft.Compute/snapshots/endGetAccess/action",
"Microsoft.Compute/snapshots/read",
"Microsoft.Compute/snapshots/write",
"Microsoft.Compute/virtualMachines/deallocate/action",
"Microsoft.Compute/virtualMachines/delete",
"Microsoft.Compute/virtualMachines/read",
"Microsoft.Compute/virtualMachines/restart/action",
"Microsoft.Compute/virtualMachines/start/action",
"Microsoft.Compute/virtualMachines/write",
"Microsoft.Network/networkInterfaces/delete",
"Microsoft.Network/networkInterfaces/join/action",
"Microsoft.Network/networkInterfaces/read",
"Microsoft.Network/networkInterfaces/write",
"Microsoft.Network/networkSecurityGroups/delete",
"Microsoft.Network/networkSecurityGroups/join/action",
"Microsoft.Network/networkSecurityGroups/read",
"Microsoft.Network/networkSecurityGroups/write",
"Microsoft.Network/virtualNetworks/subnets/read",
"Microsoft.Network/virtualNetworks/read",
"Microsoft.Network/virtualNetworks/subnets/join/action",
"Microsoft.Resources/deployments/operationstatuses/read",
"Microsoft.Resources/deployments/read",
"Microsoft.Resources/deployments/validate/action",
"Microsoft.Resources/deployments/write",
"Microsoft.Resources/deployments/delete",
"Microsoft.Resources/subscriptions/resourceGroups/read",
"Microsoft.Resources/subscriptions/resourceGroups/write",
"Microsoft.Resources/subscriptions/resourceGroups/delete",
"Microsoft.Storage/storageAccounts/delete",
"Microsoft.Storage/storageAccounts/listKeys/action",
"Microsoft.Storage/storageAccounts/read",
"Microsoft.Storage/storageAccounts/write",
"Microsoft.Resources/templateSpecs/read",
"Microsoft.Resources/templateSpecs/versions/read",
<!--NeedCopy-->
More information
- Connections and resources
- Create machine catalogs
- CTX219211: Set up a Microsoft Azure Active Directory account
- CTX219243: Grant XenApp and XenDesktop access to your Azure subscription
- CTX219271: Deploy hybrid cloud using site-to-site VPN
In this article
- Azure on-demand provisioning
- Connection to Azure Resource Manager
- Create a machine catalog using an Azure Resource Manager image
- Azure throttling
- Azure resource groups
- Azure server side encryption
- Azure dedicated hosts
- Azure Shared Image Gallery
- Provision machines into specified Availability Zones
- Azure ephemeral disk
- Preserving a provisioned virtual machine when power cycling
- Storage types
- Update provisioned machines to current provisioning scheme state
- Schedule configuration updates
- Retrieve information for Azure VMs, snapshots, OS disk, and gallery image definition
- Machine catalogs with Trusted launch
- Azure Marketplace
- About Azure permissions
- More information