Product documentation
Citrix DaaS
View PDF

Manage a Microsoft Azure catalog

December 21, 2022
Contributed by: 
C

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.

Preserving a provisioned virtual machine when power cycling

Choose whether to preserve a provisioned virtual machine when power cycling. Use the PowerShell parameter New-ProvScheme CustomProperties. This parameter supports an extra property, PersistVm, used to determine if a provisioned virtual machine persists when power cycled. Set the PersistVm property to true to persist a virtual machine when powered off, or set the property to false to ensure that the virtual machine is not preserved when powered off.

Note:

The PersistVm property only applies to a provisioning scheme with the properties CleanOnBoot and UseWriteBackCache enabled. If the PersistVm property is not specified for non-persistent virtual machines, they are deleted from the Azure environment when powered off.

In the following example, the New-ProvScheme CustomProperties parameter sets the PersistVmproperty to true:

<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" />
<Property xsi:type="StringProperty" Name="StorageType" Value="Standard_LRS" />
<Property xsi:type="StringProperty" Name="PersistWBC" Value="false" />
<Property xsi:type="StringProperty" Name="PersistOsDisk" Value="true" />
<Property xsi:type="StringProperty" Name="PersistVm" Value="true" />
<Property xsi:type="StringProperty" Name="ResourceGroups" Value="demo-resourcegroup" />
<Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client" />
</CustomProperties>
<!--NeedCopy-->

In the following example, the New-ProvScheme CustomProperties parameter preserves write back cache by setting PersistVM to true:

 New-ProvScheme
 -AzureAdJoinType "None"
 -CleanOnBoot
 -CustomProperties "<CustomProperties xmlns=`"http://schemas.citrix.com/2014/xd/machinecreation`" xmlns:xsi=`"http://www.w3.org/2001/XMLSchema-instance`"><Property xsi:type=`"StringProperty`" Name=`"UseManagedDisks`" Value=`"true`" /><Property xsi:type=`"StringProperty`" Name=`"StorageType`" Value=`"Standard_LRS`" /><Property xsi:type=`"StringProperty`" Name=`"PersistWBC`" Value=`"false`" /><Property xsi:type=`"StringProperty`" Name=`"PersistOsDisk`" Value=`"true`" /><Property xsi:type=`"StringProperty`" Name=`"PersistVm`" Value=`"true`" /><Property xsi:type=`"StringProperty`" Name=`"ResourceGroups`" Value=`"demo-resourcegroup`" /><Property xsi:type=`"StringProperty`" Name=`"LicenseType`" Value=`"Windows_Client`" /></CustomProperties>"
 -HostingUnitName "demo"
 -IdentityPoolName "NonPersistent-MCSIO-PersistVM"
 -MasterImageVM "XDHyp:\HostingUnits\demo\image.folder\scale-test.resourcegroup\demo-snapshot.snapshot"
 -NetworkMapping @ {"0"="XDHyp:\HostingUnits\demo\\virtualprivatecloud.folder\East US.region\virtualprivatecloud.folder\ji-test.resourcegroup\jitest-vnet.virtualprivatecloud\default.network"}
-ProvisioningSchemeName "NonPersistent-MCSIO-PersistVM"
 -ServiceOffering "XDHyp:\HostingUnits\demo\serviceoffering.folder\Standard_B2ms.serviceoffering" -UseWriteBackCache
 -WriteBackCacheDiskSize 127
 -WriteBackCacheMemorySize 256
 <!--NeedCopy-->

Tip:

The PersistVm property determines whether to preserve a provisioned virtual machine. The PersistOsdisk property determines whether to persist the OS disk. To preserve a provisioned virtual machine, preserve the OS disk first. You cannot delete the OS disk without first deleting the virtual machine. You can use the PersistOsdisk property without using specifying the PersistVm parameter.

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.

To change the storage type to a lower tier:

  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 precendence over the property defined in MachineProfile.

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

To apply StorageTypeAtShutdown to an existing catalog:

Use Set-ProvScheme to add a VM to an existing catalog. The feature applies to new VMs added after running Set-ProvScheme. The existing machines are not affected.

Example of setting custom properties while adding a VM to an existing catalog:

$customProperties='<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" />
<Property xsi:type="StringProperty" Name="StorageType" Value="Premium_LRS" />
<Property xsi:type="StringProperty" Name="WbcDiskStorageType" Value="Standard_SSD_LRS" />
<Property xsi:type="StringProperty" Name="ResourceGroups" Value="" />
<Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client" />
<Property xsi:type="StringProperty" Name="SchemaVersion" Value="2" />
<Property xsi:type="StringProperty" Name="OsType" Value="Windows" />
<Property xsi:type="BooleanProperty" Name="persistWBC" Value=true />
<Property xsi:type="BooleanProperty" Name="persistOsDisk" Value=true />
<Property xsi:type="StringProperty" Name="StorageTypeAtShutdown" Value="Standard_LRS" />
</CustomProperties>’

$ProvScheme = Get-Provscheme -ProvisioningSchemeName $CatalogName

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

Update provisioned machines to current provisioning scheme state

The Set-ProvScheme command changes the provisioning scheme. However, it does not affect existing machines. Using the PowerShell command Request-ProvVMUpdate, you can apply the current provisioning scheme to an existing persistent or non-persistent machine or set of machines. Currently, in Azure, you can update ServiceOffering, MachineProfile and the following custom properties:

  • StorageType
  • WBCDiskStorageType
  • IdentityDiskStorageType
  • LicenseType
  • DedicatedHostGroupId
  • PersistWBC
  • PersistOsDisk
  • PersistVm

Note:

You can only update StorageType, WBCDiskStorageType, and IdentityDiskStorageType custom properties for a catalog using managed disk in Azure environments.

You can update:

  • A single VM
  • A list of specific VMs or all existing VMs associated with a provisioning scheme ID
  • A list of specific VMs or all existing VMs associated with a provisioning scheme name (machine catalog name)

After you make the following changes to the provisioning scheme, VM instance gets recreated for persistent catalogs in Azure:

  • Change the MachineProfile
  • Remove LicenseType
  • Remove DedicatedHostGroupId

Note:

The OS disk of existing machines along with all its data remains as is and a new VM is attached to the disk.

To update the existing VMs:

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

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

  2. Update the provisioning scheme. For example,

    Set-ProvScheme –ProvisioningSchemeName “my-catalog” – ServiceOffering“XDHyp:\HostingUnits\<hosting-unit>\machineprofileinstance.vm”
<!--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-->

  4. Update existing machines.

    • To update all the existing machines. For example,

       Request-ProvVMUpdate –ProvisioningSchemeName “my-catalog”
 <!--NeedCopy-->

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

       Request-ProvVMUpdate -ProvisioningSchemeName "my-catalog" -VMName "vm1","vm2"
 <!--NeedCopy-->

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

       Get-ProvVM -ProvisioningSchemeName "my-catalog" | Request-ProvVMUpdate
 <!--NeedCopy-->

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

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

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

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

Retrieve region name information for Azure VMs, managed disks, snapshots, Azure VHD, and ARM templates

You can display region name information for an Azure VM, managed disks, snapshots, Azure VHD, and ARM templates. This information is displayed for the resources on the master image when a machine catalog is assigned. A PowerShell property called RegionName displays the region name information when you run the PowerShell command with the AdditionalData parameter.

For example, use the following PowerShell command to get a VM information in Azure.

PS C:\Windows\system32> (get-item XDHyp:\HostingUnits\myAzureNetwork\image.folder\hu-dev-testing-rg.resourcegroup\hu-dev-tsvda.vm).AdditionalData
Key Value
HardDiskSizeGB 127
ResourceGroupName HU-DEV-TESTING-RG
RegionName East US
TemplateIsWindowsTemplate True
LicenseType
ServiceOfferingDescription Standard_B2ms
ServiceOfferingMemory 8192
ServiceOfferingCores 2
SupportedMachineGenerations Gen1,Gen2
ServiceOfferingWithTemporaryDiskSizeInMb 16384
SecurityType
SecureBootEnabled
VTpmEnabled
<!--NeedCopy-->

Identify resources created by MCS

Following are the tags that MCS adds to the resources on Azure platform. 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.

More information

Manage a Microsoft Azure catalog
December 21, 2022
Contributed by: 
C
December 21, 2022
Contributed by: 
C

In this article

Site feedback | Privacy and legal terms | Cookie preferences | Consent settings
© 1999- Cloud Software Group, Inc. All rights reserved.