about_Prov_CustomProperties

March 28, 2024

Contributed by:

C C

Topic

Citrix Machine Creation Service SDK - Custom Properties

Short Description

Overview of custom properties settings of the provisioning scheme.

Long Description

Custom properties are the properties of the provisioning scheme that are specific to the target hosting infrastructure. Custom properties can be used to control or tune behaviors of the provisioning scheme.

Custom Properties For Azure

The following custom properties are specific to hosting infrastructure targets using the AzureRM plugin.

StorageAccountType: Deprecated. This property will be removed in the future, use property StorageType instead.
StorageType: Storage type used for provisioned virtual machine disks. Storage types include: Standard_LRS, StandardSSD_ZRS, Premium_ZRS, StandardSSD_LRS and Premium_LRS. If this property is not specified, Standard_LRS is used by default.
IdentityDiskStorageType: Storage type used for the provisioned virtual machine identity disk. If this property is not specified, StandardSSD_LRS is used by default.
WBCDiskStorageType: Storage type for the provisioned virtual machine write back cache disk. This property only applies to a provisioning scheme with UseWriteBackCache enabled. If this property is not specified, the value specified in the StorageType property is used for WBCDiskStorageType.
StorageTypeAtShutdown: Storage type for the provisioned virtual machine disks when it’s powered down. It applies to OS disk and write back cache disk only if the provisioning scheme has UseWriteBackCache enabled. When the machine is powered back on, its storage type will be switched back to StorageType property for OS disk and WBCDiskStorageType for write back cache disk. If WBCDiskStorageType is not specified, it will default to StorageType. Default value for this property is empty. Standard_LRS will result in storage type change at shutdown. Any other value will result in an error. Also, when StorageType is selected as either StandardSSD_ZRS or Premium_ZRS, setting StorageTypeAtShutdown to Standard_LRS will result in an error too as this feature is not compatible with ZRS.
ResourceGroups: Resource groups used to contain provisioned virtual machines. If this property is not specified, Citrix managed resource groups are created. Once the provisioning scheme is created, this property cannot be changed from Citrix managed resource groups to user created resource groups, and vice versa. It can be changed only from one user created resource groups set to another.
LicenseType: The license type used for provisioned virtual machines. The valid values include Windows_Server, Windows_Client, RHEL_BYOS, and SLES_BYOS. Windows_Server and Windows_Client are for Windows OS. RHEL_BYOS and SLES_BYOS are for Linux OS. If LicenseType is not provided or a null value, Azure will charge the license.
OsType: Operating system type used for the provisioned virtual machine. OS types include either Windows or Linux. If an OS type is not specified, Windows is used by default.
UseManagedDisks: Indicate whether to use Azure managed disks for the provisioned virtual machine. Specify either True or False. If this property is not specified, the default value is determined upon the SchemaVersion custom property value (See SchemaVersion). Once the provisioning scheme is created, this property cannot be changed.
PersistWBC: Persist the write back cache disk for the non-persistent provisioned virtual machine between power cycles. Specify either True or False. This property only applies to a provisioning scheme with UseWriteBackCache enabled. If this property is not specified, the write back cache disk is deleted when the virtual machine is shut down, and is re-created when the virtual machine is powered on.
PersistOsDisk: Persist the OS disk when power cycling the non-persistent provisioned virtual machine. Specify either True or False. This property only applies to a provisioning scheme with UseWriteBackCache enabled. If this property is not specified, the OS disk is deleted when the virtual machine is shut down, and is re-created when the virtual machine is powered on.
PersistVm: Persist the non-persistent provisioned virtual machines in Azure environments when power cycling. Specify either True or False. This property only applies when the PersistOsDisk property is set to True. If this property is not specified, they will be deleted from Azure when powered off.
MachinesPerStorageAccount: The maximum number of virtual machines containing unmanged disks that can be provisioned under a single Azure storage account. This property only applies when the UseManagedDisks property is set to False. If this property is not specified, a maximum value of 40 is used by default.
StorageAccountsPerResourceGroup: The maximum number of Azure storage accounts provisioned under a single Azure resource group. This property only applies when the UseManagedDisks property is set to False. If this property is not specified, a maximum value of 100000 is used by default.
DiskEncryptionSetId: The Azure Encryption Set ID that references the customer-managed encryption used for the server-side encryption key to encrypt disks for provisioned virtual machines. The supplied value must be a valid Azure resource ID. This property only applies when the UseManagedDisks property is set to True. If this property is not specified, Citrix takes no action on the provisioned virtual machines. Virtual machine disks use Azure storage encryption for data at rest. Once the provisioning scheme is created, this property cannot be changed.
UseSharedImageGallery: Use Azure Shared Image Gallery as a published image repository for MCS to provision virtual machines in Azure. Specify either True or False. This property only applies when the UseManagedDisks property is set to True. If this property is not specified, UseSharedImageGallery is set to False by default, and the prepared images for the machine catalog are stored as managed disk snapshots.
SharedImageGalleryReplicaRatio: The ratio of virtual machines to shared image gallery version replicas. This value is an integer greater than 0. This property only applies when the UseSharedImageGallery property is set to True. If this property is not specified, SharedImageGalleryReplicaRatio is set to 1000 for persistent OS disks and 40 for non-persistent OS disks by default.
SharedImageGalleryReplicaMaximum: The maximum number of replicas for each shared image gallery version. This value is an integer greater than 0. This property only applies when the UseSharedImageGallery property is set to True. If this property is not specified, SharedImageGalleryReplicaMaximum is set to 10 by default.
DedicatedHostGroupId: The Azure Dedicated Host Group ID. Format the value as “myResourceGroup/myHostGroup”. If this property is used, virtual machines are provisioned on the Azure dedicated hosts specified by DedicatedHostGroupId.
EnableIntuneEnroll: Automatically enroll the provisioned virtual machines with Microsoft Intune to manage them with policy and apps at scale. This property only applies to a provisioning scheme with IdentityType set to “AzureAd”. If this property is not specified, the provisioned virtual machine will not be enrolled with Intune.
Zones: The Azure Availability Zones containing provisioned virtual machines. Use a comma as a delimiter for multiple zones. If this property is not specified, the provisioned virtual machine is randomly placed across all Azure Availability Zones in the region defined by the hosting unit.
UseEphemeralOsDisk: Use Azure Ephemeral OS disk for the provisioned virtual machine. Specify either True or False. This property only applies when the UseManagedDisks property is not False and the UseSharedImageGallery property is set to True. When the UseEphemeralOsDisk property is set to True, the chosen virtual machine size supports the size of the Ephemeral OS disk and the cache disk, which is larger than the master image disk. If this property is not specified, UseEphemeralOsDisk is set to False by default. Once the provisioning scheme is created, this property cannot be changed.
SchemaVersion: This value is a float and is added (value as float 2) automatically to CustomProperties if omitted in CustomProperties. If this property is set to greater than or equal to 2, MCS will use managed disks by default, unless UseManagedDisks property is set to False. If this property is set to less than 2, MCS will use unmanaged disks by default, unless UseManagedDisks property is set to True.
UseTempDiskForWBC: Indicates whether to use Azure temporary storage to store write back cache file. Specify either True or False. If this property is not specified, the UseTempDiskForWBC parameter is set to False by default. The Azure temporary storage can be used to store write back cache file when all the following conditions are meet:

PersistWBC is False UseTempDiskForWBC is True UseWriteBackCache is True UseEphemeralOsDisk is False Azure temporary storage has enough space for both paging file and write back cache file.
PageFileDiskDriveLetterOverride: The drive letter of the disk where the page file is stored. The drive letter should be between ‘C’ and ‘Z’. The properties ‘PageFileDiskDriveLetterOverride’, ‘InitialPageFileSizeInMB’, and ‘MaxPageFileSizeInMB’ should always come together.
InitialPageFileSizeInMB: The initial page file size in megabytes which must be between 16 MB and 16777216 MB, and not greater than the maximum page file size.
MaxPageFileSizeInMB: The maximum page file size in megabytes which must be greater than or equal to the initial page file size, and less than 16777216 MB. Also it can not exceed the amount of free space on the drive.
BackupVmConfiguration: A secondary list of service offerings optionally paired with type as Spot to fall back on when machine power on fails due to resource shortage error from Azure. Type when not specified will be inferred as Regular. We would always try to power on with the primary service offering first, and only when that fails we would try secondary config starting from the first item in the list. Failure to power on with primary or any of the secondary configs will result in a “Resource Not Available” error. Few examples of how to specify this property: “<CustomProperties> <Property xsi:type=`“StringProperty`” Name=`“BackupVmConfiguration`” Value=`”[‘ServiceOffering’: ‘A’, ‘ServiceOffering’: ‘B’, ‘ServiceOffering’: ‘C’]`”/></CustomProperties>” <Property xsi:type=`“StringProperty`” Name=`“BackupVmConfiguration`” Value=`”[{‘ServiceOffering’: ‘A’, ‘Type’: ‘Spot’}, {‘ServiceOffering’: ‘B’, ‘Type’: ‘Regular’}, {‘ServiceOffering’: ‘C’, ‘Type’: ‘Spot’}]`”/></CustomProperties>”

Custom Properties For Aws

The following custom properties are specific to hosting infrastructure targets using the AWS plugin.

AwsCaptureInstanceProperties: Capture AWS instance properties, including the Identity Access Management role and tags from the master image, then apply them to the provisioned virtual machines. Specify either True or False. If this property is not specified, AwsCaptureInstanceProperties is set to False by default. Note: AwsCaptureInstanceProperties is now deprecated.
AwsOperationalResourcesTagging: Apply tags from master image to all Citrix created operational resources including virtual machines, VM disks, VM network interfaces, S3 buckets, S3 objects, launch templates and AMIs. Specify either True or False. When setting this property to True, you must also set the AwsCaptureInstanceProperties parameter to True or must have supplied Machine Profile. If neither of these two values are specified, the AwsOperationalResourcesTagging parameter is set to False by default.

Custom Properties For Gcp

The following custom properties are specific to hosting infrastructure targets using the GCP plugin.

CatalogZones: GCP zones to place provisioned virtual machines. Use comma as delimiter for multiple zones. If this property is not specified, the provisioned virtual machine is randomly placed across GCP zones.
CryptoKeyId: Use the customer-managed encryption key to encrypt data on provisioned virtual machines. Format the value as “project:location:keyRing:key”.If this property is not specified, a google managed encryption key is used.
StorageType: Storage type used for provisioned virtual machine disks. Storage types depend on the region/zone, but can include: pd-standard, pd-balanced, pd-ssd, local-ssd, and pd-extreme. If this property is not specified, the master image’s boot disk type is used by default.
IdentityDiskStorageType: Storage type used for the provisioned virtual machine identity disk. If this property is not specified, ‘pd-standard’ is used by default.
WBCDiskStorageType: Storage type for the provisioned virtual machine write back cache disk. This property only applies to a provisioning scheme with UseWriteBackCache enabled. If this property is not specified, ‘pd-standard’ is used by default.
PersistOsDisk: Persist the OS disk when power cycling the non-persistent provisioned virtual machine. Specify either True or False. This property only applies to a provisioning scheme with UseWriteBackCache enabled. If this property is not specified, the OS disk is deleted when the virtual machine is shut down, and is re-created when the virtual machine is powered on.
PersistWBC: Persist the write back cache disk for the non-persistent provisioned virtual machine between power cycles. Specify either True or False. This property only applies to a provisioning scheme with UseWriteBackCache enabled. If this property is not specified, the write back cache disk is deleted when the virtual machine is shut down, and is re-created when the virtual machine is powered on.

Custom Properties For Vmware

The following custom properties are specific to hosting infrastructure targets using the VMware plugin.

FolderId: The ID of a VM Placement Folder. If a valid value for the FolderID is specified, for example, “group-v1234”, VMs are created in that folder ID. If the property is not specified, VMs are created in the same folder where the master image is placed.

Custom Properties For Scvmm

The following custom properties are specific to hosting infrastructure targets using the SCVMM plugin.

AzureArcSubscriptionId: Azure subscription id that the virtual machine will be connected to as an Azure Arc connected virtual machine. If this property is not specified, the virtual machine will fail to connect to Azure Arc.
AzureArcRegion: Azure region that the virtual machine will be connected to as an Azure Arc connected virtual machine. If this property is not specified, the virtual machine will fail to connect to Azure Arc.
AzureArcResourceGroup: Azure resource group that the virtual machine will be connected to as an Azure Arc connected virtual machine. If this property is not specified, the virtual machine will fail to connect to Azure Arc.
EnableAzureArcOnboarding: Indicates whether to connect the MCS provisioned virtual machines to Azure Arc. Specify either True or False. This property only applies to the SCVMM managed Azure Stack HCI cluster.