Product documentation
Citrix Virtual Apps and Desktops
Service Current Release 2407 2402 LTSR 2311 2308 2305 2303 2212 2209 2206 2203 LTSR 1912 LTSR
View PDF

Manage a Microsoft Azure catalog

November 19, 2024
Contributed by: 
C C

Note:

Since July 2023, Microsoft has renamed Azure Active Directory (Azure AD) to Microsoft Entra ID. In this document, any reference to Azure Active Directory, Azure AD, or AAD now refers to Microsoft Entra ID.

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

Note:

Before managing a Microsoft Azure catalog, you need to finish creating a Microsoft Azure catalog. See Create a Microsoft Azure catalog.

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.

  1. Add the custom property StorageTypeAtShutdown, set the value to Standard_LRS (HDD), and create a catalog using New-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 precedence over the property defined in MachineProfile.

  2. Shut down the VM and check the storage type of the VM in the Azure portal. The storage type of the disk changes to a lower tier, as specified in the StorageTypeAtShutdown custom property.
  3. 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 in CustomProperties. Otherwise, it switches back to the storage type mentioned in StorageType.

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

Change the storage type of existing VMs to a lower tier on shutdown

Before proceeding with the steps, see the Requirements and Restriction.

You can save storage costs by changing the storage type of existing VMs to a lower tier when the VMs are shut down. To do this, use the StorageTypeAtShutdown custom property.

To change the Storage type of existing machines in a catalog to a lower tier when the VMs are shut down:

  1. Open a PowerShell window.
  2. Run asnp citrix* to load the Citrix-specific PowerShell modules.
  3. Run Get-Provscheme -ProvisioningSchemeName $CatalogName.

  4. Change the custom properties string.

    $customProperties = '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="StorageTypeAtShutdown" Value="Standard_LRS" />
</CustomProperties>'
<!--NeedCopy-->

  5. Update the provisioning scheme of the existing catalog. The update applies to new VMs added after running Set-ProvScheme.

    Set-ProvScheme -ProvisioningSchemeName $CatalogName -CustomProperties $customProperties
<!--NeedCopy-->

  6. Update the existing VMs to enable StorageTypeAtShutdown.

    Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName $CatalogName -StartsNow -DurationInMinutes -1
<!--NeedCopy-->
  7. When you power on the machines next time, the StorageTypeAtShutdown property of the machines is updated. The storage type changes at the next shutdown.

  8. Run the following command to view the StorageTypeAtShutdown value for each VM in a catalog:

    Get-ProvVM -ProvisioningSchemeName <catalog-name> | foreach { $vmName = $_.VMName; $storageTypeAtShutdown = ($_.CustomVmData | ConvertFrom-Json).StorageTypeAtShutdown.DiskStorageAccountType; return New-Object psobject -Property @{ "VMName" = $vmName; "StorageTypeAtShutdown" = $storageTypeAtShutdown } }
<!--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 Set-ProvVMUpdateTimeWindow, you can apply the current provisioning scheme to an existing persistent or non-persistent machine or set of machines. You can also schedule a time slot for the configuration updates of the existing MCS provisioned machines. Any power on or restart during the scheduled time slot applies a scheduled provisioning scheme update to a machine. 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, and IdentityDiskStorageType custom properties for a catalog using managed disk in Azure environments.
  • If you run Set-ProvVMUpdateTimeWindow twice, then the most recent command takes effect.

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.

Before updating the existing VMs:

  1. Check the configuration of the existing machines. For example,

    Get-ProvScheme | select ProvisioningSchemeName, ProvisioningSchemeVersion
<!--NeedCopy-->

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

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

To request updates for existing machines to apply at the next restart:

  1. Run the following commands to update existing machines and have the updates apply at the next restart.

    • To update all the existing machines. For example,

       Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName my-catalog -StartsNow -DurationInMinutes -1
 <!--NeedCopy-->

    • To update a list of specific machines. For example,

       Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName my-catalog -VMName <List-Of-Vm-Names> -StartsNow -DurationInMinutes -1
 <!--NeedCopy-->

    • To update machines based on the output of Get-ProvVM. For example,

       Get-ProvVM -ProvisioningSchemeName "my-catalog" | Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName my-catalog -StartsNow -DurationInMinutes -1
 <!--NeedCopy-->

    Note:

    • StartsNow indicates that the scheduled start time is the current time.
    • DurationInMinutes with a negative number (for example, –1) indicates no upper bound on the schedule’s time window.

  2. Find machines with an update scheduled. For example,

    Get-ProvVM -Filter "ProvisioningSchemeUpdateAfter" | select VMName, ProvisioningSchemeUpdateAfter
<!--NeedCopy-->

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

To schedule a VM to update to the latest provisioning settings next time it starts in the scheduled time window:

  1. Run the following commands:

    • To schedule an update with start time as the current time

       Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName my-catalog -VMName vm1 -StartsNow -DurationInMinutes 120
 <!--NeedCopy-->

    • To schedule an update on a weekend

       Set-ProvVMUpdateTimeWindow -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, use StartsNow 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 the schedule’s time window.

  2. Check the update status.

    Get-ProvVM | select VMName, ProvisioningSchemeUpdateRequested, ProvisioningSchemeUpdateUntil, ProvisioningSchemeVersion
<!--NeedCopy-->

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

To cancel the configuration update:

You can also cancel a configuration update of a single VM, multiple VMs, or an entire catalog. To cancel a configuration update:

  1. Run Clear-ProvVMUpdateTimeWindow. For example:

    • To cancel the configuration update scheduled for a single VM:

        Clear-ProvVMUpdateTimeWindow -ProvisioningSchemeName “ my-catalog “ -VMName “vm1”
  <!--NeedCopy-->

    • To cancel the configuration update scheduled for multiple VMs:

       Clear-ProvVMUpdateTimeWindow -ProvisioningSchemeName "my-catalog" -VMName "vm1","vm2"
 <!--NeedCopy-->

      Note:

      The VMs must be from the same catalog.

Update properties of individual VMs

You can update properties of individual VMs in a persistent MCS machine catalog using the PowerShell command Set-ProvVM. However, the updates are not applied immediately. You must set the time window using the PowerShell command Set-ProvVMUpdateTimeWindow for the updates to apply.

This implementation helps you to manage individual VMs efficiently without updating the entire machine catalog. Currently, this feature is applicable only to the Azure environment.

Currently, the properties that you can update are:

  • CustomProperties
  • ServiceOffering
  • MachineProfile

Using this feature, you can:

Before updating properties of a VM:

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

  3. Check the configuration of the existing machine catalog. For example:

    Get-ProvScheme -ProvisioningSchemeName AzureCatalog
<!--NeedCopy-->

  4. Check the configuration of the VM on which you want to apply the updates. For example:

    Get-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1
<!--NeedCopy-->

Update properties of a VM

Do the following to update the properties on a VM:

  1. Turn off the VM on which you want to apply the updates.

  2. Update the properties of the VM. For example, if you want to update storage type (StorageType) custom property of the VM, run the following:

    Set-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1 -CustomProperties "...<Property Name='StorageType' Value='Premium_LRS' />..."
<!--NeedCopy-->

    You can update properties of two VMs in a machine catalog simultaneously. For example:

    Set-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1 -CustomProperties "...<Property Name='StorageType' Value='Premium_LRS' />..."
<!--NeedCopy-->

    Set-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine2 -CustomProperties "...<Property Name='StorageType' Value='StandardSSD_LRS' />..."
<!--NeedCopy-->

    Note:

    The updates are not applied immediately.

  3. Get the list of properties that are specified to be updated and the configuration version. For example:

    Get-ProvVMConfiguration -ProvisioningSchemeName AzureCatalog -VMName machine1
<!--NeedCopy-->

    Check the property value of Version and the properties to be updated (in this case, StorageType).

  4. Check the configuration version. For example:

    Get-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1
<!--NeedCopy-->

    Check the property value of ProvVMConfigurationVersion. The update is not yet applied. The VM is still in the old configuration.

  5. Request scheduled update. For example:

     Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName AzureCatalog -StartsNow -DurationInMinutes -1
 <!--NeedCopy-->

    For more information on scheduled updates, see Update provisioned machines to current provisioning scheme state.

    Note:

    Any pending provisioning scheme update is also applied.

  6. Restart the VM. For example:

    New-BrokerHostingPowerAction -MachineName machine1 -Action TurnOn
<!--NeedCopy-->

  7. Check the configuration version. For example:

    Get-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1
<!--NeedCopy-->

    Check the property value of ProvVMConfigurationVersion. The update is now applied. The VM now has the new configuration.

  8. To apply further configuration updates on the VM, turn off the VM, and repeat the steps.

Retain the properties updated on a VM after the machine catalog is updated

Do the following to retain the properties updated on a VM:

  1. Turn off the VM on which you want to apply the updates.

  2. Update the machine catalog. For example, if you want to change the VM size (ServiceOffering) and storage type (StorageType), run the following:

    Set-ProvScheme -ProvisioningSchemeName AzureCatalog -ServiceOffering Standard_E4_v3 -CustomProperties "...<Property Name='StorageType' Value='StandardSSD_LRS' />..."
<!--NeedCopy-->

  3. Get the configuration details of the machine catalog. For example:

    Get-ProvScheme -ProvisioningSchemeName AzureCatalog
<!--NeedCopy-->

    The ProvisioningSchemeVersion is now incremented by one. The VM size and storage type are also updated.

  4. Update the properties of the VM. For example, provide a machine profile to the VM.

    Set-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1 -MachineProfile "XDHyp:\HostingUnits\<hosting-unit>\machineprofile.folder\<resource-group>.resourcegroup\<template-spec>.templatespec\<template-spec-version>.templatespecversion"
<!--NeedCopy-->

    Note:

    The machine profile input has a tag and a different VM size (ServiceOffering) specified.

  5. Get the list of properties that the VM will have after merging the configuration updates on the VM with the machine catalog updates. For example:

    Get-ProvVMConfigurationResultantSet -ProvisioningSchemeName AzureCatalog -VMName machine1
<!--NeedCopy-->

    Note:

    Any updates on the VM will override the updates done on the machine catalog.

  6. Request scheduled update for the VM. For example:

    Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName AzureCatalog -VMName machine1 -StartsNow -DurationInMinutes -1
<!--NeedCopy-->

  7. Restart the VM. For example:

    New-BrokerHostingPowerAction -MachineName machine1 -Action TurnOn
<!--NeedCopy-->

    The VM keeps its updated VM size as derived from the machine profile. The tag values as specified in the machine profile are also applied to the VM. However, the storage type is derived from the latest provisioning scheme.

  8. Get the configuration version of the VM. For example:

    Get-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1
<!--NeedCopy-->

    The ProvisioningSchemeVersion and ProvVMConfigurationVersion now shows the latest version.

Revert the configuration updates applied to a VM

  1. After applying the updates to a VM, turn off the VM.

  2. Run the following command to remove the updates that are applied on the VM. For example:

    Set-ProvVM -RevertToProvSchemeConfiguration -ProvisioningSchemeName AzureCatalog -VMName machine1
<!--NeedCopy-->

  3. Request scheduled update for the VM. For example:

    Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName AzureCatalog -VMName machine1 -StartsNow -DurationInMinutes -1
<!--NeedCopy-->

  4. Restart the VM. For example:

    New-BrokerHostingPowerAction -MachineName machine1 -Action TurnOn
<!--NeedCopy-->

  5. Check the configuration version of the VM. For example:

    Get-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1
<!--NeedCopy-->

    The ProvVMConfigurationVersion value is now the configuration version of the machine catalog.

Change disk encryption

You can change the disk encryption in Azure virtualization environments and do the following:

  • Create an MCS machine catalog with disk encryption set (DES) that is different from the master image DES using the New-ProvScheme command. For example:

     $customProperties = @"
 <CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <Property xsi:type="DiskEncryptionSetId" Name="Zones" Value="/subscriptions/XXXXXXXXXXXXXXXXXXXXXXXXXXXXX/resourceGroups/testrsg/providers/Microsoft.Compute/diskEncryptionSets/test-diskEncryptionSet"/>
 </CustomProperties>
 "@
 New-ProvScheme -CleanOnBoot `
 -ProvisioningSchemeName $provisioningSchemeName `
 -HostingUnitName $hostingUnitName `
 -IdentityPoolName $identityPoolName `
 -InitialBatchSizeHint $numberOfVms `
 -masterImagePath $masterImagePath `
 -NetworkMapping $networkMapping `
 -CustomProperties $customProperties
 <!--NeedCopy-->

  • Change the disk encryption type from one DES key to another DES key of an existing MCS machine catalog and existing VMs using Set-ProvScheme and Set-ProvVMUpdateTimeWindow commands. After you restart the VMs, you can see the updated DES key. For example:

     $customProperties = '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <Property xsi:type="StringProperty" Name="DiskEncryptionSetId" Value="/subscriptions/456c683e2ed7/resourceGroups/testrg/providers/Microsoft.Compute/diskEncryptionSets/diskEncryptionSet1" />
 </CustomProperties>'
 Set-ProvScheme -ProvisioningSchemeName azure-catalog -CustomProperties $customProperties
 Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName azure-catalog -VMName azu01, azu02 -StartsNow -DurationInMinutes -1
 <!--NeedCopy-->

  • Update an MCS machine catalog and VM that was not previously CMEK enabled to have customer-managed encryption key (CMEK) encryption (DES), disk encryption at host, or double encryption using Set-ProvScheme and Set-ProvVMUpdateTimeWindow commands. For information on different encryption types, see Azure server side encryption, Azure disk encryption at host, and Double encryption on managed disk.

  • Update an existing MCS machine catalog and VMs to be non-encrypted that was previously encrypted using Set-ProvScheme and Set-ProvVMUpdateTimeWindow commands. For example:

     $customProperties = '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <Property xsi:type="StringProperty" Name="DiskEncryptionSetId" Value="" />
 </CustomProperties>'
 Set-ProvScheme -ProvisioningSchemeName azure-catalog -CustomProperties $customProperties
 Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName azure-catalog -VMName azu01, azu02 -StartsNow -DurationInMinutes -1
 <!--NeedCopy-->

  • Enable disk encryption with private endpoint (an MCS machine catalog that used a host connection enabled with ProxyHypervisorTrafficThroughConnector). For information on how to enable disk encryption with private endpoints, see Enable disk encryption with private endpoint.

Enable disk encryption with private endpoint

As per the Azure limitation, currently, you can’t have server-side encryption with customer-managed keys for private endpoints. However, you can update an existing MCS machine catalog and VMs with private endpoints to be encrypted with the DES key.

Update an existing machine catalog with private endpoints

The detailed steps to update an existing machine catalog with private endpoints are as follows:

  1. Create a catalog without disk encryption through ProxyHypervisorTrafficThroughConnector.

  2. Run Set-ProvScheme to update the catalog with DiskEncryptionSetId.

    Note:

    DiskEcryptionSetId can be configured through CustomProperties or MachineProfile. When it is defined in both CustomProperties and MachineProfile, the properties defined in CustomProperties are applied.

    Example when using CustomProperties:

    $customProperties = '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="DiskEncryptionSetId" Value="/subscriptions/456c683e2ed7/resourceGroups/testrg/providers/Microsoft.Compute/diskEncryptionSets/diskEncryptionSet1"/>
</CustomProperties>'
Set-ProvScheme -ProvisioningSchemeName azure-catalog -CustomProperties $customProperties
<!--NeedCopy-->

    Example when using MachineProfile: Use a VM that has disk encryption enabled or a template spec with disk encryption settings:

    Set-ProvScheme -ProvisioningSchemeName azure-catalog -MachineProfile "XDHyp:\HostingUnits\azureunit\machineprofile.folder\testrg.resourcegroup\new-template.vm"
<!--NeedCopy-->

    Alternatively, you can update a machine profile using Web Studio.

  3. Run Set-ProvVMUpdateTimeWindow to update existing catalog VMs. For example:

    Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName azure-catalog -VMName azu01, azu02 -StartsNow -DurationInMinutes -1
<!--NeedCopy-->
  4. After you restart the VMs, you can see the updated disk encryption on the VM’s disks in Azure portal.

  5. Run Set-ProvScheme to unset the disk encryption before adding new catalog VMs.

    Note:

    This step is required because you are updating a private endpoint catalog. If you do not do this step, then you will get errors while trying to add new VMs to the catalog.

    For example:

    $customProperties = '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="DiskEncryptionSetId" Value="" />
</CustomProperties>'
Set-ProvScheme -ProvisioningSchemeName azure-catalog -CustomProperties $customProperties
<!--NeedCopy-->
  6. Add new VMs to the catalog.

Update individual catalog VMs

The detailed steps to update individual catalog VMs are as follows:

  1. Create a catalog without disk encryption through ProxyHypervisorTrafficThroughConnector.

  2. Run Set-ProvVM to update catalog VM with DiskEncryptionSetId.

    Note:

    The DiskEcryptionSetId can be configured through either CustomProperties or MachineProfile.

    Example when using CustomProperties:

    $customProperties = '<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="DiskEncryptionSetId" Value="/subscriptions/456c683e2ed7/resourceGroups/testrg/providers/Microsoft.Compute/diskEncryptionSets/diskEncryptionSet1" />
</CustomProperties>'
Set-ProvVM -ProvisioningSchemeName azure-catalog  -VMName azu01 -CustomProperties $customProperties
<!--NeedCopy-->

    Example when using MachineProfile:

    Set-ProvVM -ProvisioningSchemeName azure-catalog  -VMName azu01 -MachineProfile "XDHyp:\HostingUnits\azureunit\machineprofile.folder\testrg.resourcegroup\new-template.vm"
<!--NeedCopy-->

  3. Run Set-ProvVMUpdateTimeWindow to update existing catalog VMs. For example:

    Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName azure-catalog -VMName azu01 -StartsNow -DurationInMinutes -1
<!--NeedCopy-->
  4. After you restart the VMs, you can see the updated disk encryption on the VMs disks in Azure portal.
  5. Add new VMs to the catalog.

Use temporary disk as WBC disk for existing catalogs

You can use Azure temporary disk as write-back cache disk (WBC) disk for existing MCS machine catalogs. Use the Set-ProvScheme PowerShell command to update existing catalogs and VMs.

Prerequisites

The existing catalog must satisfy the following conditions:

Note:

If the existing catalog doesn’t meet the following requirements, the WBC disk is not placed inside the temporary disk.

  • MCSIO is enabled: The custom properties WriteBackCacheMemorySize, WriteBackCacheDiskSize, and UseWriteBackCache are enabled.
  • Ephemeral OS disk is not enabled.
  • WBC is non-persistent: PersistWBC is false.
  • UseTempDiskForWBC is null or false.
  • The 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).

Important:

Changing a service offering from one with a temporary disk to one without, or the reverse, is not allowed.

Update existing catalogs

To update an existing catalog, run the following commands:

  1. Run Set-ProvScheme on the existing catalog to update the UseTempDiskForWBC to true. For example:

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

  2. Add new machines to the catalog and power on. The new VMs have a WBC disk inside the temporary disk.

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. Sometimes, this field might be empty. For example, a snapshot from a data disk does not contain the TemplateIsWindowsTemplate field because the OS type cannot be retrieved from a snapshot.

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

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

Identify resources created by MCS

Following are the tags that MCS adds to the resources. The tags in the table are represented as “key”:”value”.

Resource name Tag
ID disk “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
Image “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
NIC “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
OS disk “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
PrepVM “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
Published snapshot “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
Resource group “CitrixResource” : “Internal”
  CitrixSchemaVersion: 2.0
  “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
Storage account “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
VM in catalog “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
WBC disk “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”

Note:

A VM is not visible in the Citrix inventory if a CitrixResource tag is added to identify it as a resource created by MCS. You can remove or rename the tag to make it visible.

Remove tags

When you create a catalog or a VM, tags are created on the following resources:

  • Resource group
  • Virtual machine
  • OS disk
  • Identity disk
  • Network interface
  • Storage account

You can remove VMs and machine catalogs from Citrix database and remove tags. You can use:

  • Remove-ProvVM with ForgetVM parameter to remove VMs and tags from a single VM or a list of VMs from a machine catalog.
  • Remove-ProvScheme with ForgetVM parameter to remove a machine catalog from the Citrix database and tags from an entire machine catalog.

This feature is only applicable to persistent VMs.

To do this:

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

  3. Run Remove-ProvVM to delete VMs from Citrix database and tags from VMs. For example:

    Remove-ProvVM -ProvisioningSchemeName “ProvisioningSchemeName” -VMName “vmname” -ForgetVM
<!--NeedCopy-->

  4. Run Remove-ProvScheme to delete machine catalog from Citrix database and tags from machine catalogs. For example:

    Remove-ProvScheme -ProvisioningSchemeName “ProvisioningSchemeName” -ForgetVM
<!--NeedCopy-->

    Note:

    After you use ForgetVM parameter in Remove-ProvScheme, MCS deletes all snapshots including base disk snapshot if the provisioning scheme is present in either bring your own resource group (BYORG) or Citrix managed resource group.

More information

Manage a Microsoft Azure catalog
November 19, 2024
Contributed by: 
C C
November 19, 2024
Contributed by: 
C C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.