Manage a Microsoft Azure catalog
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.
-
Add the custom property
StorageTypeAtShutdown
, set the value to Standard_LRS (HDD), and create a catalog usingNew-ProvScheme
. For information on creating a catalog using PowerShell, see https://developer-docs.citrix.com/projects/citrix-virtual-apps-desktops-sdk/en/latest/creating-a-catalog/.Note:
If
StorageTypeAtShutdown
has any value other than empty or Standard_LRS (HDD), the operation fails.Example of setting custom properties while creating a persistent catalog:
$customProperties='<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" /> <Property xsi:type="StringProperty" Name="StorageType" Value="Premium_LRS" /> <Property xsi:type="StringProperty" Name="ResourceGroups" Value="" /> <Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client" /> <Property xsi:type="StringProperty" Name="SchemaVersion" Value="2" /> <Property xsi:type="StringProperty" Name="OsType" Value="Windows" /> <Property xsi:type="StringProperty" Name="StorageTypeAtShutdown" Value="Standard_LRS" /> </CustomProperties>' <!--NeedCopy-->
Example of setting custom properties while creating a non-persistent catalog:
$customProperties='<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" /> <Property xsi:type="StringProperty" Name="StorageType" Value="Premium_LRS" /> <Property xsi:type="StringProperty" Name="WbcDiskStorageType" Value="Standard_SSD_LRS" /> <Property xsi:type="StringProperty" Name="ResourceGroups" Value="" /> <Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client" /> <Property xsi:type="StringProperty" Name="SchemaVersion" Value="2" /> <Property xsi:type="StringProperty" Name="OsType" Value="Windows" /> <Property xsi:type="BooleanProperty" Name="persistWBC" Value=true /> <Property xsi:type="BooleanProperty" Name="persistOsDisk" Value=true /> <Property xsi:type="StringProperty" Name="StorageTypeAtShutdown" Value="Standard_LRS" /> </CustomProperties>' <!--NeedCopy-->
Note:
When you use a machine profile, the custom property takes precedence over the property defined in
MachineProfile
. - 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. - Turn on the VM. The storage type of the disk switches back to the storage type mentioned in:
-
StorageType
custom property for OS disk -
WBCDiskStorageType
custom property for WBC disk only if you specify it inCustomProperties
. Otherwise, it switches back to the storage type mentioned inStorageType
.
-
Apply StorageTypeAtShutdown
to an existing catalog
Before proceeding with the steps, see the Requirements and Restriction.
Use Set-ProvScheme
to add a VM to an existing catalog. The feature applies to new VMs added after running Set-ProvScheme
. The existing machines are not affected.
Example of setting custom properties while adding a VM to an existing catalog:
$customProperties='<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" />
<Property xsi:type="StringProperty" Name="StorageType" Value="Premium_LRS" />
<Property xsi:type="StringProperty" Name="WbcDiskStorageType" Value="Standard_SSD_LRS" />
<Property xsi:type="StringProperty" Name="ResourceGroups" Value="" />
<Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client" />
<Property xsi:type="StringProperty" Name="SchemaVersion" Value="2" />
<Property xsi:type="StringProperty" Name="OsType" Value="Windows" />
<Property xsi:type="BooleanProperty" Name="persistWBC" Value=true />
<Property xsi:type="BooleanProperty" Name="persistOsDisk" Value=true />
<Property xsi:type="StringProperty" Name="StorageTypeAtShutdown" Value="Standard_LRS" />
</CustomProperties>'
$ProvScheme = Get-Provscheme -ProvisioningSchemeName $CatalogName
Set-ProvScheme -ProvisioningSchemeName $ProvScheme.ProvisioningSchemeName -CustomProperties $customProperties
<!--NeedCopy-->
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:
- Open a PowerShell window.
- Run
asnp citrix*
to load the Citrix-specific PowerShell modules. - Run
Get-Provscheme -ProvisioningSchemeName $CatalogName
. -
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-->
-
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-->
-
Update the existing VMs to enable
StorageTypeAtShutdown
.Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName $CatalogName -StartsNow -DurationInMinutes -1 <!--NeedCopy-->
- When you power on the machines next time, the
StorageTypeAtShutdown
property of the machines is updated. The storage type changes at the next shutdown. -
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
, andIdentityDiskStorageType
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:
-
Check the configuration of the existing machines. For example,
Get-ProvScheme | select ProvisioningSchemeName, ProvisioningSchemeVersion <!--NeedCopy-->
-
Update the provisioning scheme. For example,
-
With VM as a machine profile input:
Set-ProvScheme -ProvisioningSchemeName "my-catalog" -MachineProfile "XDHyp:\HostingUnits\<hosting-unit>\machineprofile.folder\<resource-group>.resourcegroup\<virtual-machine>.vm" <!--NeedCopy-->
-
With template spec as a machine profile input:
Set-ProvScheme -ProvisioningSchemeName "my-catalog" -MachineProfile "XDHyp:\HostingUnits\<hosting-unit>\machineprofile.folder\<resource-group>.resourcegroup\<template-spec>.templatespec\<template-spec-version>.templatespecversion" -ServiceOffering "XDHyp:\HostingUnits\<hosting-unit>\serviceoffering.folder\<service-offering>.serviceoffering" <!--NeedCopy-->
-
With just service offering:
Set-ProvScheme -ProvisioningSchemeName "my-catalog" -ServiceOffering "XDHyp:\HostingUnits\<hosting-unit>\serviceoffering.folder\<service-offering>.serviceoffering" <!--NeedCopy-->
-
-
Check if the current property of the VM matches the current provisioning scheme, and if there is any pending update action on the VM. For example,
Get-ProvVM | select VMName, ProvisioningSchemeUpdateRequested, ProvisioningSchemeVersion <!--NeedCopy-->
You can also find machines with a particular version. For example,
Get-ProvVM -Filter "ProvisioningSchemeVersion -eq 1" | select VMName, ProvisioningSchemeVersion <!--NeedCopy-->
To request updates for existing machines to apply at the next restart:
-
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.
-
-
Find machines with an update scheduled. For example,
Get-ProvVM -Filter "ProvisioningSchemeUpdateAfter" | select VMName, ProvisioningSchemeUpdateAfter <!--NeedCopy-->
-
Restart the machines. At the next power-up, property changes are applied to the existing machines. You can check the updated status using the following command. For example,
Get-ProvVM | select VMName, ProvisioningSchemeUpdateRequested, ProvisioningSchemeVersion <!--NeedCopy-->
To schedule a VM to update to the latest provisioning settings next time it starts in the scheduled time window:
-
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
, useStartsNow
to indicate that the schedule start time is the current time. -
DurationInMinutes
is optional. Default is 120 minutes. A negative number (for example, –1) indicates no upper bound on the schedule’s time window.
-
-
Check the update status.
Get-ProvVM | select VMName, ProvisioningSchemeUpdateRequested, ProvisioningSchemeUpdateUntil, ProvisioningSchemeVersion <!--NeedCopy-->
-
Power on the VM. If you power on the machine after the scheduled time slot, configuration update is not applied. If you power on the machine within the scheduled time slot,
-
If the machine is powered off, and
- you do not power on the machine, configuration update is not applied
- you power on the machine, configuration update is applied
-
If the machine is powered on, and
- you do not restart the machine, configuration update is not applied
- you restart the machine, configuration update is applied
-
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:
-
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:
- Update the properties of a VM
- Retain the properties updated on a VM after the machine catalog is updated
- Revert the configuration updates applied to a VM
Before updating properties of a VM:
- Open a PowerShell window.
- Run
asnp citrix*
to load the Citrix-specific PowerShell modules. -
Check the configuration of the existing machine catalog. For example:
Get-ProvScheme -ProvisioningSchemeName AzureCatalog <!--NeedCopy-->
-
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:
- Turn off the VM on which you want to apply the updates.
-
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.
-
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
). -
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. -
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.
-
Restart the VM. For example:
New-BrokerHostingPowerAction -MachineName machine1 -Action TurnOn <!--NeedCopy-->
-
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. - 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:
- Turn off the VM on which you want to apply the updates.
-
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-->
-
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. -
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. -
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.
-
Request scheduled update for the VM. For example:
Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName AzureCatalog -VMName machine1 -StartsNow -DurationInMinutes -1 <!--NeedCopy-->
-
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.
-
Get the configuration version of the VM. For example:
Get-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1 <!--NeedCopy-->
The
ProvisioningSchemeVersion
andProvVMConfigurationVersion
now shows the latest version.
Revert the configuration updates applied to a VM
- After applying the updates to a VM, turn off the VM.
-
Run the following command to remove the updates that are applied on the VM. For example:
Set-ProvVM -RevertToProvSchemeConfiguration -ProvisioningSchemeName AzureCatalog -VMName machine1 <!--NeedCopy-->
-
Request scheduled update for the VM. For example:
Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName AzureCatalog -VMName machine1 -StartsNow -DurationInMinutes -1 <!--NeedCopy-->
-
Restart the VM. For example:
New-BrokerHostingPowerAction -MachineName machine1 -Action TurnOn <!--NeedCopy-->
-
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
andSet-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
andSet-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
andSet-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:
- Create a catalog without disk encryption through
ProxyHypervisorTrafficThroughConnector
. -
Run
Set-ProvScheme
to update the catalog withDiskEncryptionSetId
.Note:
DiskEcryptionSetId
can be configured throughCustomProperties
orMachineProfile
. When it is defined in bothCustomProperties
andMachineProfile
, the properties defined inCustomProperties
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 the Full Configuration interface.
-
Run
Set-ProvVMUpdateTimeWindow
to update existing catalog VMs. For example:Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName azure-catalog -VMName azu01, azu02 -StartsNow -DurationInMinutes -1 <!--NeedCopy-->
- After you restart the VMs, you can see the updated disk encryption on the VM’s disks in Azure portal.
-
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-->
- Add new VMs to the catalog.
Update individual catalog VMs
The detailed steps to update individual catalog VMs are as follows:
- Create a catalog without disk encryption through
ProxyHypervisorTrafficThroughConnector
. -
Run
Set-ProvVM
to update catalog VM withDiskEncryptionSetId
.Note:
The
DiskEcryptionSetId
can be configured through eitherCustomProperties
orMachineProfile
.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-->
-
Run
Set-ProvVMUpdateTimeWindow
to update existing catalog VMs. For example:Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName azure-catalog -VMName azu01 -StartsNow -DurationInMinutes -1 <!--NeedCopy-->
- After you restart the VMs, you can see the updated disk encryption on the VMs disks in Azure portal.
- Add new VMs to the catalog.
Retrieve information for Azure VMs, snapshots, OS disk, and gallery image definition
You can display information for an Azure VM, including OS disk and type, snapshot and gallery image definition. This information is displayed for resources on the master image when a machine catalog is assigned. Use this functionality to view and select either a Linux or Windows image. A PowerShell property, TemplateIsWindowsTemplate
, was added to the AdditionDatafield
parameter. This field contains Azure-specific information: VM type, OS disk, gallery image information, and OS type information. Setting TemplateIsWindowsTemplate
to True indicates that the OS type is Windows; setting TemplateIsWindowsTemplate
to False indicates that the OS type is Linux.
Tip:
Information displayed by the
TemplateIsWindowsTemplate
PowerShell property is derived from the Azure API. Sometimes, this field might be empty. For example, a snapshot from a data disk does not contain theTemplateIsWindowsTemplate
field because the OS type cannot be retrieved from a snapshot.
For example, set the Azure VM AdditionData
parameter to True for Windows OS type using PowerShell:
PS C:\Users\username> (get-item XDHyp:\HostingUnits\mynetwork\image.folder\username-dev-testing-rg.resourcegroup\username-dev-tsvda.vm).AdditionalData
Key Value
ServiceOfferingDescription Standard_B2ms
HardDiskSizeGB 127
ResourceGroupName FENGHUAJ-DEV-TESTING-RG
ServiceOfferingMemory 8192
ServiceOfferingCores 2
TemplateIsWindowsTemplate True
ServiceOfferingWithTemporaryDiskSizeInMb 16384
SupportedMachineGenerations Gen1,Gen2
<!--NeedCopy-->
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
withForgetVM
parameter to remove VMs and tags from a single VM or a list of VMs from a machine catalog. -
Remove-ProvScheme
withForgetVM
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:
- Open a PowerShell window.
- Run asnp citrix* to load the Citrix-specific PowerShell modules.
-
Run
Remove-ProvVM
to delete VMs from Citrix database and tags from VMs. For example:Remove-ProvVM -ProvisioningSchemeName “ProvisioningSchemeName” -VMName “vmname” -ForgetVM <!--NeedCopy-->
-
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 inRemove-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
In this article
- Change the storage type to a lower tier when a VM is shut down
- Update provisioned machines to current provisioning scheme state
- Update properties of individual VMs
- Change disk encryption
- Retrieve information for Azure VMs, snapshots, OS disk, and gallery image definition
- Identify resources created by MCS
- Remove tags
- More information