Citrix DaaS

Create a Microsoft Azure catalog

Create machine catalogs describes the wizards that create a machine catalog. The following information covers details specific to Microsoft Azure Resource Manager cloud environments.

Note:

Before creating a Microsoft Azure catalog, you need to finish creating a connection to Microsoft Azure. See Connection to Microsoft Azure.

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. Then, the VM’s status in the Full Configuration interface changes to On. 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.

Create a machine catalog using an Azure Resource Manager image

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

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

Tip:

Use of unmanaged disk to provision VM is deprecated.

In the machine catalog creation wizard:

  • The Machine Type 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 an image that you want to use as the master image for all machines in the catalog. The Select an image wizard appears. Select a subscription where the image resides, select a resource group, and then navigate to the Azure VHD, or the Azure Compute Gallery (formerly Shared Image Gallery), or the Azure image version.

    When selecting an image, consider the following:

    • Verify that a Citrix VDA is installed on the image.
    • If you select a VHD attached to a VM, you must shut down the VM before proceeding to the next step.

    Note:

    • The subscription corresponding to the connection (host) that created the machines in the catalog is denoted with a green dot. The other subscriptions are those that have the Azure Compute Gallery shared with that subscription. In those subscriptions, only shared galleries are shown.
    • 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. Trusted Launch is not supported for Shared Image Gallery. For information about Azure trusted launch, see https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch.
    • You can create a provisioning scheme using ephemeral OS disk on Windows with trusted launch. When you select an image with trusted launch, then you must select a machine profile with trusted launch that is enabled with vTPM. To create machine catalogs using ephemeral OS disk, see How to create machines using ephemeral OS disks.
    • When image replication is in progress, you can proceed and select the image as the master image and complete the setup. However, catalog creation might take longer to complete while the image is being replicated. MCS requires the replication to complete within an hour starting from catalog creation. If the replication times out, catalog creation fails. You can verify the replication status in Azure. Try again if the replication is still pending or after the replication completes.
    • When you select a master image for machine catalogs in Azure, MCS identifies the OS type based on the master image and machine profile you select. If MCS can’t identify it, select the OS type that matches the master image.

    Choose whether you want VMs in the catalog to inherit configurations from a machine profile. By default, the Use a machine profile (mandatory for Azure Active Directory) check box is selected. Click Select a machine profile to browse to a VM or an ARM template spec from a list of resource groups.

    Validate the ARM template spec to make sure whether it can be used as a machine profile to create a machine catalog. There are two ways to validate the ARM template spec:

    • After you select the ARM template spec from the resource group list, click Next. Error messages appear if the ARM template spec has errors.
    • Run one of the following PowerShell commands:
      • Test-ProvInventoryItem -HostingUnitName <string> -InventoryPath <string>
      • Test-ProvInventoryItem -HostingUnitUid <Guid> -InventoryPath <string>

    Examples of configurations that VMs can inherit from a machine profile include:

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

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

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

    Important:

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

    Storage and License Types page

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

    • Premium SSD. Offers a high-performance, low-latency disk storage option suitable for VMs with I/O-intensive workloads.
    • Standard SSD. Offers a cost-effective storage option that is suitable for workloads that require consistent performance at lower IOPS levels.
    • Standard HDD. Offers a reliable, low-cost disk storage option suitable for VMs that run latency-insensitive workloads.
    • Azure ephemeral OS disk. Offers a cost-effective storage option that reuses the local disk of the VMs to host the operating system disk. Alternatively, you can use PowerShell to create machines that use ephemeral OS disks. For more information, see Azure ephemeral disks. Be aware of the following considerations when using an ephemeral OS disk:
      • Azure ephemeral OS disk and MCS I/O cannot be enabled at the same time.
      • To update machines that use ephemeral OS disks, you must select an image whose size does not exceed the size of the VM’s cache disk or temporary disk.
      • You cannot use the Retain system disk during power cycles option offered later in the wizard.

    Note:

    The identity disk is always created using Standard SSD irrespective of the storage type you choose.

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

    Select whether to use existing Windows licenses or Linux licenses.

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

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

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

    Note:

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

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

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

    • Linux licenses: With bring-your-own-subscription (BYOS) Linux licenses, you do not have to pay for the software. The BYOS charge only includes the compute hardware fee. There are two types of licenses:

      • RHEL_BYOS: To use RHEL_BYOS type successfully, enable Red Hat Cloud Access on your Azure subscription.
      • SLES_BYOS: The BYOS versions of SLES include support from SUSE.

      You can set the LicenseType value to Linux options at New-ProvScheme and Set-ProvScheme.

      Example of setting LicenseType to RHEL_BYOS at New-ProvScheme:

      New-ProvScheme -CleanOnBoot -ProvisioningSchemeName "azureCatalog" -RunAsynchronously -Scope @() -SecurityGroup @() -CustomProperties '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" /><Property xsi:type="StringProperty" Name="StorageAccountType" Value="StandardSSD_LRS" /><Property xsi:type="StringProperty" Name="ResourceGroups" Value="hu-dev-mcs" /><Property xsi:type="StringProperty" Name="OsType" Value="Linux" /><Property xsi:type="StringProperty" Name="LicenseType" Value="RHEL_BYOS" /></CustomProperties>'
      <!--NeedCopy-->
      

      Example of setting LicenseType to SLES_BYOS at Set-ProvScheme:

      Set-ProvScheme -ProvisioningSchemeName "azureCatalog" -CustomProperties '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" /><Property xsi:type="StringProperty" Name="StorageAccountType" Value="StandardSSD_LRS" /><Property xsi:type="StringProperty" Name="ResourceGroups" Value="hu-dev-mcs" /><Property xsi:type="StringProperty" Name="OsType" Value="Linux" /><Property xsi:type="StringProperty" Name="LicenseType" Value="SLES_BYOS" /></CustomProperties>'
      <!--NeedCopy-->
      

      Note:

      If LicenseType value is empty, then the default values are Azure Windows Server License or Azure Linux License, depending on OsType value.

      Example of setting LicenseType to empty:

      Set-ProvScheme -ProvisioningSchemeName "azureCatalog" -CustomProperties '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" /><Property xsi:type="StringProperty" Name="StorageAccountType" Value="StandardSSD_LRS" /><Property xsi:type="StringProperty" Name="ResourceGroups" Value="hu-dev-mcs" /><Property xsi:type="StringProperty" Name="OsType" Value="Linux" /></CustomProperties>'
      <!--NeedCopy-->
      

    See the following documents to understand License types and their benefits:

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

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

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

  • On the Virtual Machines page, indicate how many VMs you want to create. You must specify at least one and select a machine size. After catalog creation, you can change the machine size by editing the catalog.

  • The NICs page does not contain Azure-specific information. Follow the guidance in the Create machine catalogs article.

  • On the Disk Settings page, choose whether to enable write-back cache. With the MCS storage optimization feature enabled, you can configure the following settings when creating a catalog. These settings apply to both Azure and GCP environments.

    Machine catalog setup

    After enabling write-back cache, you can do the following:

    • Configure the size of the disk and RAM used for caching temporary data. For more information, see Configure cache for temporary data.

    • Select the storage type for the write-back cache disk. The following storage options are available to use for the write-back cache disk:

      • Premium SSD
      • Standard SSD
      • Standard HDD
    • Choose whether you want the write-back cache disk to persist for the provisioned VMs. Select Enable write-back cache to make the options available. By default, Use non-persistent write-back cache disk is selected.

    • https://docs.microsoft.com/en-us/azure/storage/common/storage-introduction/
    • https://docs.microsoft.com/en-us/azure/virtual-machines/premium-storage-performance/
    • https://docs.microsoft.com/en-us/azure/storage/common/storage-redundancy/

    • Select the type for the write-back cache disk.

      • Use non-persistent write-back cache disk. If selected, the write-back cache disk is deleted during power cycles. Any data redirected to it will be lost. If the VM’s temporary disk has sufficient space, it is used to host the write-back cache disk to reduce your costs. After catalog creation, you can check whether the provisioned machines use the temporary disk. To do so, click the catalog and verify the information on the Template Properties tab. If the temporary disk is used, you see Non-persistent Write-back Cache Disk and its value is Yes (using VM’s temporary disk). If not, you see Non-persistent Write-back Cache Disk and its value is No (not using VM’s temporary disk).
      • Use persistent write-back cache disk. If selected, the write-back cache disk persists for the provisioned VMs. Enabling the option increases your storage costs.
    • Choose whether to retain system disks for VDAs during power cycles.

      • Retain system disk during power cycles. By default, the system disk is deleted on shutdown and recreated on startup. This ensures that the disk is always in a clean state but results in longer VM restart times. If system writes are redirected to the RAM cache and overflow to the cache disk, the system disk remains unchanged. Enabling this option increases your storage costs but reduces VM restart times. Select Enable write-back cache to make this option available.
        • Retain VMs across power cycles. Select this option to retain your VM customization and to enable the VMs to be started through the Azure portal.
    • Choose whether to enable storage cost savings. If enabled, save storage costs by downgrading the storage disk to Standard HDD when the VM shuts down. The VM switches to its original settings on restart. The option applies to both storage and write-back cache disks. Alternatively, you can also use PowerShell. See Change the storage type to a lower tier when a VM is shut down.

    • 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. For more information, see Azure server side encryption.
  • On the Resource Group page, choose whether to create resource groups or use existing groups.

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

    For more information, see Azure resource groups.

  • The Machine Identities, Domain Credentials, and Summary pages do not contain Azure-specific information. Follow the guidance in the Create Machine Catalogs article.

Complete the wizard.

Conditions for Azure temporary disk to be eligible for write-back cache disk

You can use the Azure temporary disk as write-back cache disk only if all the following conditions are satisfied:

  • The write-back cache disk must non-persist as the Azure temporary disk is not appropriate for persistent data.

  • The chosen Azure VM size must include a temporary disk.

  • The ephemeral OS disk is not required to be enabled.

  • Accept to place the write-back cache file on Azure temporary disk.

  • The Azure temporary disk size must be greater than the total size of (write-back cache disk size + reserved space for paging file + 1 GB buffer space).

Using PowerShell to create a catalog with non-persistent write-back cache disk

To configure a catalog with non-persistent write-back cache disk, use the PowerShell parameter New-ProvScheme CustomProperties. The custom properties are:

  • UseTempDiskForWBC. This property indicates whether you are accepting to use the Azure temporary storage to store the write-back cache file. This must be configured to true when running New-ProvScheme if you want to use the temporary disk as write-back cache disk. If this property is not specified, the parameter is set to False by default.

For example, using the CustomProperties parameter to set UseTempDiskForWBC to true:

    -CustomProperties '<CustomProperties xmlns=" http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance"> `
    <Property xsi:type="StringProperty" Name="PersistWBC" Value="false"/> `
    <Property xsi:type="StringProperty" Name="PersistOsDisk" Value="false"/> `
    <Property xsi:type="StringProperty" Name="PersistVm" Value="false"/> `
    <Property xsi:type="StringProperty" Name="StorageAccountType" Value="Premium_LRS"/> `
    <Property xsi:type="StringProperty" Name="WBCDiskStorageType" Value="Premium_LRS"/> `
    <Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client"/> `
    <Property xsi:type="StringProperty" Name="UseTempDiskForWBC" Value="true"/> `
    </CustomProperties>'
<!--NeedCopy-->

Note:

After you commit the machine catalog to use Azure local temporary storage for write-back cache file, it cannot be changed to use VHD later.

Non-persistent write-back cache disk scenarios

The following table describes three different scenarios when temporary disk is used for write-back cache while creating machine catalog.

Scenario Outcome
All conditions to use temporary disk for write-back cache are satisfied. The WBC file mcsdif.vhdx is placed on the temporary disk.
Temporary disk has insufficient space for write-back cache usage. A VHD disk ‘MCSWCDisk’ is created and WBC file mcsdif.vhdx is placed on this disk.
Temporary disk has sufficient space for write-back cache usage but UseTempDiskForWBC is set to false. A VHD disk ‘MCSWCDisk’ is created and WBC file mcsdif.vhdx is placed on this disk.

Using PowerShell to create a catalog with persistent write-back cache disk

To configure a catalog with persistent write-back cache disk, use the PowerShell parameter New-ProvScheme CustomProperties.

Tip:

Use the PowerShell parameter New-ProvScheme CustomProperties only for cloud-based hosting connections. If you want to provision machines using a persistent write-back cache disk for an on-premises solution (for example, Citrix Hypervisor) PowerShell is not needed because the disk persists automatically.

This parameter supports an extra property, PersistWBC, used to determine how the write-back cache disk persists for MCS provisioned machines. The PersistWBC property is only used when the UseWriteBackCache parameter is specified, and when the WriteBackCacheDiskSize parameter is set to indicate that a disk is created.

Note:

This behavior applies to both Azure and GCP where the default MCSIO write-back cache disk is deleted and re-created when power cycling. You can choose to persist the disk to avoid the deletion and recreation of MCSIO write-back cache disk.

Examples of properties found in the CustomProperties parameter before supporting PersistWBC include:

<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" />
<Property xsi:type="StringProperty" Name="StorageAccountType" Value="Premium_LRS" />
<Property xsi:type="StringProperty" Name="ResourceGroups" Value="benvaldev5RG3" />
</CustomProperties>
<!--NeedCopy-->

Note:

This example only applies to Azure. The properties are different in GCP environment.

When using these properties, consider that they contain default values if the properties are omitted from the CustomProperties parameter. The PersistWBC property has two possible values: true or false.

Setting the PersistWBC property to true does not delete the write-back cache disk when the Citrix Virtual Apps and Desktops administrator shuts down the machine from the management interface.

Setting the PersistWBC property to false deletes the write-back cache disk when the Citrix Virtual Apps and Desktops administrator shuts down the machine from the management interface.

Note:

If the PersistWBC property is omitted, the property defaults to false and the write-back cache is deleted when the machine is shut down from the management interface.

For example, using the CustomProperties parameter to set PersistWBC to true:

<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" />
<Property xsi:type="StringProperty" Name="StorageAccountType" Value="Premium_LRS" />
<Property xsi:type="StringProperty" Name="ResourceGroups" Value="benvaldev5RG3" />
<Property xsi:type="StringProperty" Name="PersistWBC" Value="true" />
</CustomProperties>
<!--NeedCopy-->

Important:

The PersistWBC property can only be set using the New-ProvScheme PowerShell cmdlet. Attempting to alter the CustomProperties of a provisioning scheme after creation has no impact on the machine catalog and the persistence of the write-back cache disk when a machine is shut down.

For example, set New-ProvSchemeto use the write-back cache while setting the PersistWBC property to true:

New-ProvScheme
-CleanOnBoot
-CustomProperties "<CustomProperties xmlns=`"http://schemas.citrix.com/2014/xd/machinecreation`" xmlns:xsi=`"http://www.w3.org/2001/XMLSchema-instance`"><Property xsi:type=`"StringProperty`" Name=`"UseManagedDisks`" Value=`"true`" /><Property xsi:type=`"StringProperty`" Name=`"StorageAccountType`" Value=`"Premium_LRS`" /><Property xsi:type=`"StringProperty`" Name=`"ResourceGroups`" Value=`"benvaldev5RG3`" /><Property xsi:type=`"StringProperty`" Name=`"PersistWBC`" Value=`"true`" /></CustomProperties>"
-HostingUnitName "adSubnetScale1"
-IdentityPoolName "BV-WBC1-CAT1"
-MasterImageVM "XDHyp:\HostingUnits\adSubnetScale1\image.folder\GoldImages.resourcegroup\W10MCSIO-01_OsDisk_1_a940e6f5bab349019d57ccef65d2c7e3.manageddisk"
-NetworkMapping @{"0"="XDHyp:\HostingUnits\adSubnetScale1\\virtualprivatecloud.folder\CloudScale02.resourcegroup\adVNET.virtualprivatecloud\adSubnetScale1.network"}
-ProvisioningSchemeName "BV-WBC1-CAT1"
-ServiceOffering "XDHyp:\HostingUnits\adSubnetScale1\serviceoffering.folder\Standard_D2s_v3.serviceoffering"
-UseWriteBackCache
-WriteBackCacheDiskSize 127
-WriteBackCacheMemorySize 256
<!--NeedCopy-->

Improve boot performance with MCSIO

You can improve boot performance for Azure and GCP managed disks when MCSIO is enabled. Use the PowerShell PersistOSDisk custom property in the New-ProvScheme command to configure this feature. Options associated with New-ProvScheme include:

<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" />
<Property xsi:type="StringProperty" Name="StorageAccountType" Value="Premium_LRS" />
<Property xsi:type="StringProperty" Name="Resource<!--NeedCopy-->
``````<!--NeedCopy-->
````````Groups" Value="benvaldev5RG3" />
<Property xsi:type="StringProperty" Name="PersistOsDisk" Value="true" />
</CustomProperties>
<!--NeedCopy-->

To enable this feature, set thePersistOSDisk custom property to true. For example:

New-ProvScheme
-CleanOnBoot
-CustomProperties "<CustomProperties xmlns=`"http://schemas.citrix.com/2014/xd/machinecreation`" xmlns:xsi=`"http://www.w3.org/2001/XMLSchema-instance`"><Property xsi:type=`"StringProperty`" Name=`"UseManagedDisks`" Value=`"true`" /><Property xsi:type=`"StringProperty`" Name=`"StorageAccountType`" Value=`"Premium_LRS`" /><Property xsi:type=`"StringProperty`" Name=`"ResourceGroups`" Value=`"benvaldev5RG3`" /><Property xsi:type=`"StringProperty`" Name=`"PersistOsDisk`" Value=`"true`" /></CustomProperties>"
-HostingUnitName "adSubnetScale1"
-IdentityPoolName "BV-WBC1-CAT1"
-MasterImageVM "XDHyp:\HostingUnits\adSubnetScale1\image.folder\GoldImages.resourcegroup\W10MCSIO-01_OsDisk_1_a940e6f5bab349019d57ccef65d2c7e3.manageddisk"
-NetworkMapping @{"0"="XDHyp:\HostingUnits\adSubnetScale1\\virtualprivatecloud.folder\CloudScale02.resourcegroup\adVNET.virtualprivatecloud\adSubnetScale1.network"}
-ProvisioningSchemeName "BV-WBC1-CAT1"
-ServiceOffering "XDHyp:\HostingUnits\adSubnetScale1\serviceoffering.folder\Standard_D2s_v3.serviceoffering"
-UseWriteBackCache
-WriteBackCacheDiskSize 127
-WriteBackCacheMemorySize 256
<!--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, 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:

  1. Open a PowerShell window.
  2. Run asnp citrix* to load the Citrix-specific PowerShell modules.
  3. Run the following command:

    $s = (ls XDHyp:\HostingUnits\<name of hosting unit>\serviceoffering.folder\"<VM size>.serviceoffering)
    <!--NeedCopy-->
    
  4. Run $s | select -ExpandProperty Additionaldata
  5. 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.

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

Use machine profile property values

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 will be 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-->
      
    • An existing catalog with:
      • CustomProperties for StorageAccountType 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-->
      
    • 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-->
      

Use PowerShell to enable Azure VM extensions

After you select the ARM template spec, run the following PowerShell commands to work with Azure VM extensions:

  • To view the list of supported Azure VM extensions: Get-ProvMetadataConfiguration
  • To add additional VM extensions: Add-ProvMetadataConfiguration. For example, Add-ProvMetadataConfiguration -PluginType "AzureRM" -ConfigurationName "Extension" -ConfigurationValue "CustomScriptExtension"

    If you try to add any of the following, the command fails with an error message:

    • Citrix defined extension.
    • Existing user defined extension.
    • Unsupported configuration keys. Currently, the supported configuration key is Extension.
  • To remove extensions from the list: Remove-ProvMetadataConfiguration. You can remove the extensions that you added.

Page File Location

In Azure environments, the page file location is set up when you first create a VM. The format of the page file setting is: page file location [min size] [max size] (the size in MB). For more information, see How to determine the appropriate page file size.

During image preparation, when you create the provisioning scheme, MCS determines the page file location based on certain rules. After you create the provisioning scheme, you cannot:

  • Change the VM size
  • Update the machine profile
  • Change the EOS and MCS I/O properties

Page file location determination

Features like EOS and MCS I/O have their own expected page file location and are exclusive to each other. The following table shows the expected page file location for each feature:

Feature Expected page file location
EOS OS disk
MCS I/O Azure temporary disk first, otherwise write-back cache disk

Note:

Even if you decouple image preparation from provisioning scheme creation, MCS correctly determines the page file location. The default page file location is on the OS disk.

Page file setting scenarios

The following table describes some of the possible scenarios of page file setting during image preparation and provisioning scheme update:

During Scenario Outcome
Image preparation You set the source image page file on the temporary disk, while the VM size that you specify in the provisioning scheme has no temporary disk The page file is placed on the OS
Image preparation You set the source image page file on the OS disk, while the VM size that you specify in the provisioning scheme has a temporary disk The page file is placed on the temporary disk
Image preparation You set the source image page file on the temporary disk and enable the ephemeral OS disk in the provisioning scheme The page file is placed on the OS disk
Provisioning scheme update You attempt to update the provisioning scheme. The original VM size has a temporary disk whereas the target VM has no temporary disk Rejects the change with an error message
Provisioning scheme update You attempt to update the provisioning scheme. The original VM size has no temporary disk whereas the target VM has a temporary disk Rejects the change with an error message

Update page file setting

Using PowerShell commands, you can specify page file settings, including the location and size. This overrides the page file settings determined by MCS. You can do this by running the following New-ProvScheme command during machine catalog creation:

New-ProvScheme -CleanOnBoot `
    -HostingUnitName "zijinnet" `
    -IdentityPoolName "PageFileSettingExample" `
    -ProvisioningSchemeName "PageFileSettingExample" `
    -InitialBatchSizeHint 1 `
    -MasterImageVM "XDHyp:\HostingUnits\zijinnet\image.folder\neal-zijincloud-resources.resourcegroup\CustomWin10VDA_OsDisk_1_9473d7c8a6174b2c8284c7d3efeea88f.manageddisk" `
    -NetworkMapping @{"0"="XDHyp:\\HostingUnits\\zijinnet\\virtualprivatecloud.folder\\East US.region\\virtualprivatecloud.folder\\neal-zijincloud-resources.resourcegroup\\neal-zijincloud-resources-vnet.virtualprivatecloud\\default.network"} `
    -ServiceOffering "XDHyp:\\HostingUnits\\zijinnet\\serviceoffering.folder\\Standard_B2ms.serviceoffering" `
    -CustomProperties '<CustomProperties xmlns=" http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance"> `
    <Property xsi:type="StringProperty" Name="PersistOsDisk" Value="false"/> `
    <Property xsi:type="StringProperty" Name="PersistVm" Value="false"/> `
    <Property xsi:type="StringProperty" Name="PageFileDiskDriveLetterOverride" Value="d"/> `
    <Property xsi:type="StringProperty" Name="InitialPageFileSizeInMB" Value="2048"/> `
    <Property xsi:type="StringProperty" Name="MaxPageFileSizeInMB" Value="8196"/> `
    <Property xsi:type="StringProperty" Name="StorageAccountType" Value="Premium_LRS"/> `
    <Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client"/> `
    </CustomProperties>'
<!--NeedCopy-->

For information on how to create a catalog using the Remote PowerShell SDK, see Creating a catalog using PowerShell.

Constraints:

  • You can update the page file setting only when you create the provisioning scheme by running the New-ProvScheme command. You cannot change the page file setting later.
  • You must provide all the custom properties (‘PageFileDiskDriveLetterOverride’, ‘InitialPageFileSizeInMB’, and ‘MaxPageFileSizeInMB’) in the New-ProvScheme command or none of them.
  • This feature is not supported through Citrix Studio.
  • The initial page file size must be between 16 MB and 16777216 MB.
  • The maximum page file size must be greater than or equal to the initial page file size and less than 16777216 MB.
  • You can set both the initial page file size and maximum page file size to zero at the same time.

Azure throttling

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

Tip:

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

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

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

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

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

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

Azure throttling

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

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

  • Default value of MaximumConcurrentProvisioningOperations is 500.
  • Configure the MaximumConcurrentProvisioningOperations parameter using the PowerShell command Set-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.
  • In the Machine Catalog Setup wizard, if you select Azure ephemeral OS disk on the Storage and License Types page, you do not get the option for write-back cache disk settings on the Disk Settings page.

    Azure ephemeral OS disk selected

    Write-back cache disk settings not available

  • The PowerShell parameters (UseWriteBackCache and UseEphemeralOsDisk) set to true in New-ProvScheme or Set-ProvScheme fails with proper error message.
  • 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 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 that DiskEncryptionSet change to be encrypted with the new key.

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

Important considerations when using customer-managed encryption keys

Consider the following when using this feature:

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

  • Once you have enabled the customer-managed encryption key 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.

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. Citrix DaaS creates one Standard_LRS image version (version 1.0.0) for each image with the appropriate number of replicas in the catalog’s region, based on the number of machines in the catalog, the configured replica ratio, and the configured replica maximum.

Note:

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

For more information, see Azure shared image gallery overview.

When selecting an image to use for creating a machine catalog, you can select images you created in the Azure Shared Image Gallery. These images appear in the list of images in the Master Image screen of the Machine Catalog Setup wizard.

For these images to appear, you must:

  1. Configure a Citrix Virtual Apps and Desktops site.
  2. Connect to the Azure Resource Manager.
  3. In the Azure portal, create a resource group. For details, see Create an Azure Shared Image Gallery using the portal.
  4. In the resource group, create a Shared Image Gallery.
  5. In the Shared Image Gallery, create an image definition.
  6. In the image definition, create an image version.

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

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

UseSharedImageGallery

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

SharedImageGalleryReplicaRatio

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

SharedImageGalleryReplicaMaximum

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

Tip:

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

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

Set-ProvScheme -ProvisioningSchemeName catalog-name -CustomProperties '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Property xsi:type="StringProperty" Name="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-->

For this use case:

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

For example:

Set-ProvScheme -ProvisioningSchemeName catalog-name -CustomProperties '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Property xsi:type="StringProperty" Name="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 and SharedImageGalleryReplicaMaximum are not required. After the Set-ProvScheme command completes the Shared Image Gallery image has not yet been created. Once the catalog is configured to use the gallery, the next catalog update operation stores the published image in the gallery. The catalog update command creates the gallery, the gallery image, and the image version. Power cycling the machines updates them, at which point the replica count is updated, if appropriate. From that time, all existing non-persistent machines are reset using the Shared Image Gallery image and all newly provisioned machines are created using the image. The old snapshot is cleaned up automatically within a few hours.

For this use case:

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

For example:

Set-ProvScheme -ProvisioningSchemeName catalog-name -CustomProperties '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Property xsi:type="StringProperty" Name="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 the Set-ProvScheme command completes the image snapshot has not yet been created. Once the catalog is configured to not use the gallery, the next catalog update operation stores the published image as a snapshot. From that time, all existing non-persistent machines are reset using the snapshot and all newly provisioned machines are created from the snapshot. Power cycling the machines updates them, at which point the custom machine data is updated to reflect that UseSharedImageGallery is set to False. The old Shared Image Gallery assets (gallery, image, and version) are automatically cleaned up within a few hours.

Image sharing with another service principal in the same tenant

To select an image in Azure Compute Gallery that belongs to a different subscription, the image must be shared with the service principal (SPN) of that subscription.

For example, if there is a service principal (SPN 1), which is configured in Studio as:

Service principal: SPN 1

Subscription: subscription 1

Tenant: tenant 1

The image is in different subscription, which is configured in Studio as:

Subscription: subscription 2

Tenant: tenant 1

If you want to share the image in subscription 2 with subscription 1 (SPN 1), go to subscription 2, and share the resource group with SPN1.

The image must be shared with another SPN using Azure role-based access control (RBAC). Azure RBAC is the authorization system used to manage access to Azure resources. For more information on Azure RBAC, see the Microsoft document What is Azure role-based access control (Azure RBAC). To grant access, you assign roles to service principals at resource group scope with Contributor role. To assign Azure roles, you must have Microsoft.Authorization/roleAssignments/write permission, such as User Access Administrator or Owner. For more information on sharing images with another SPN, see the Microsoft document Assign Azure roles using the Azure portal.

Using PowerShell to select an image from a different subscription

You can select an image in Azure Compute Gallery that belongs to a different shared subscription in the same Azure tenant to create and update MCS catalogs using PowerShell commands.

  1. In the hosting unit root folder, Citrix creates a new shared subscription folder called sharedsubscription.
  2. List all shared subscriptions in a tenant.

    Get-ChildItem -Path "XDhyp:\HostingUnits\azres\sharedsubscription.folder"
    <!--NeedCopy-->
    
  3. Select one shared subscription, and then list all shared resource groups of that shared subscription.

    Get-ChildItem -Path "XDhyp:\HostingUnits\azres\image.folder\abc123.sharedsubscription"
    <!--NeedCopy-->
    
  4. Select a resource group, and then list all galleries of that resource group.

    Get-ChildItem -Path "XDhyp:\HostingUnits\azres\image.folder\abc123.sharedsubscription\ xyz.resourcegroup"
    <!--NeedCopy-->
    
  5. Select a gallery, and then list all image definitions of that gallery.

    Get-ChildItem -Path "XDhyp:\HostingUnits\azres\image.folder\abc123.sharedsubscription\xyz.resourcegroup\testgallery.gallery"
    <!--NeedCopy-->
    
  6. Select one image definition, and then list all image versions of that image definition.

    Get-ChildItem -Path "XDhyp:\HostingUnits\azres\image.folder\abc123.sharedsubscription\xyz.resourcegroup\sigtestdef.imagedefinition"
    <!--NeedCopy-->
    
  7. Create and update an MCS catalog using the following elements:

    • Resource group
    • Gallery
    • Gallery image definition
    • Gallery image version

    For information on how to create a catalog using the Remote PowerShell SDK, see https://developer-docs.citrix.com/projects/citrix-virtual-apps-desktops-sdk/en/latest/creating-a-catalog/.

Provision machines into specified Availability Zones

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

Note:

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

Configuring Availability Zones in the Full Configuration interface

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

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

Configuring Availability Zones through PowerShell

Using PowerShell, you can view the Citrix DaaS 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.

Using host groups and Azure availability zones at the same time

There is a pre-flight check to assess whether the creation of a machine catalog will be successful based on the availability zone specified in the custom property and the host group’s zone. Catalog creation fails if the availability zone custom property does not match the host group’s zone.

For information on configuring availability zones through PowerShell, see Configuring Availability Zones through PowerShell.

For information on Azure dedicated hosts, see Azure dedicated hosts.

The following table describes the various combinations of availability zone and host group zone and which ones result in successful or failed creation of a machine catalog.

Host group zone Availability zone in custom property Machine catalog creation outcome
Specified. For example, host group is in Zone 1 Not specified Successful. Machines are created in the host group’s zone
Specified. For example, host group is in Zone 1 Same zone as host group zone. For example, zone in the custom property is set to 1 Successful. Machines are created in Zone 1
Specified. For example, host group is in Zone 1 Different from the host group zone. For example, zone in the custom property is set to 2 As the specified availability zone and the host group’s zone do not match, catalog creation fails with a relevant error during pre-flight checks
Specified. For example, host group is in Zone 1 Multiple zones specified. For example, zones in the custom properties are set to 1,2 or 2,3 As the specified availability zone and the host group’s zone do not match, catalog creation fails with a relevant error during pre-flight checks
Not specified. For example, zone of the host group is None Not specified As the specified availability zone and the host group’s zone match (that is, no zone), catalog creation is successful. Machines are not created in any zone
Not specified. For example, zone of the host group is None Specified. For example, zones in the custom property are set to one or multiple zones Because the specified availability zone and the host group’s zone do not match, catalog creation fails with a relevant error during pre-flight checks

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 use managed disks and a Shared Image Gallery. For more information, see Azure shared image gallery.

Using PowerShell to configure an ephemeral disk

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

Note:

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

For example:

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

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

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. If WBCDiskStorageType is not configured, the StorageType is used as the default for WBCDiskStorageType.

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

Enable zone-redundant storage

You can select zone-redundant storage during catalog creation. It synchronously replicates your Azure managed disk across multiple availability zones, which allows you to recover from a failure in one zone by utilizing the redundancy in others.

You can specify Premium_ZRS and StandardSSD_ZRS in the storage type custom properties. ZRS storage can be set using existing custom properties or through the MachineProfile template. ZRS storage is also supported with Request-ProvVMUpdate, and you can change existing machine from LRS to ZRS storage.

Limitations:

  • Supported only for managed disks
  • Supported only with premium and standard solid-state drives (SSD)
  • Not supported with StorageTypeAtShutdown
  • Available only in certain regions.
  • Performance of Azure drops when creating ZRS disks at scale. Therefore, for the first power on, turn on the machines in smaller batches (less than 300 machines at a time)

Set zone-redundant storage as the disk storage type

You can select zone-redundant storage during the initial catalog creation, or you can update your storage type in an existing catalog.

Select zone-redundant storage using PowerShell commands

When creating a new catalog in Azure using the New-ProvScheme Powershell command, use Standard_ZRS as the value in the StorageAccountType. For example:

<Property xsi:type="StringProperty" Name="StorageAccountType" Value="StandardSSD_ZRS" />
<!--NeedCopy-->

When setting this value, it is validated by a dynamic API that determines if it can be used properly. The following exceptions can occur if the use of ZRS is not valid for your catalog:

  • StorageTypeAtShutdownNotSupportedForZrsDisks: The StorageTypeAtShutdown custom property cannot be used with ZRS storage.
  • StorageAccountTypeNotSupportedInRegion: This exception occurs if you try to use ZRS Storage in an Azure Region that does not support ZRS
  • ZrsRequiresManagedDisks: You can use zone-redundant storage only with managed disks.

You can set the disk storage type using the following custom properties:

  • StorageType
  • WBCDiskStorageType
  • IdentityDiskStorageType

Note:

During catalog creation, the machine profile’s OS disk StorageType is used if the custom properties are not set.

Azure Marketplace

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.

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.

Azure Marketplace Shared Image 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.

Azure Marketplace verifies VDA publishing options

After verifying the purchase plan information, create an image version within the definition. This is used as the master image. Click Add version:

Azure Marketplace add VDA version

In the Version details section, select the image snapshot or managed disk as the source:

Azure Marketplace select VDA options

Where to go next

More information