Developer Documentation
Citrix Virtual Apps and Desktops SDK
Current Release 2402 2311 2305 2303 2212 2209 2206 2203 2112 2109 2103 1912
View PDF

about_Prov_MachineProfile

August 9, 2024
Contributed by: 
C

Topic

Citrix Machine Creation Service SDK - Machine Profile

Short Description

Overview of Machine Profile and how to use it to provision machines across different hypervisors

Long Description

Machine Profile provides a way to specify a template that will be used for provisioning machines in a provisioning scheme. Depending on the hypervisor, the template can provide hardware details (CPU/memory, disk tier), networking settings (subnets, security groups) and hypervisor-specific features (disk encryption, accelerated networking, availability zones) that will be carried through to created machines.

Machine Profile allows for having one place to specify all virtual machine settings, instead of having to pass the settings individually when creating or updating a catalog. For instance, the ServiceOffering for a catalog will be automatically set to whatever Machine Profile is using if it’s not provided explicitly via the -ServiceOffering PowerShell parameter. There’s also the added benefit of knowing all settings will be compatible with each other if the hypervisor supports using an already created virtual machine as Machine Profile.

Another key benefit is when new features are implemented by the hypervisor, they have the potential to be supported on day zero. A recent example was Azure adding in support for placing created machines in a proximity group. Right after the feature was released by Azure, if a Machine Profile was configured to use a proximity group, machines provisioned based on that Machine Profile would use the same proximity group.

Property Processing Order

Some properties present in Machine Profile were given explicitly prior to Machine Profile being supported, either via hypervisor specific CustomProperties or through other more general parameters shared across hypervisors like ServiceOffering, NetworkMapping.

Methods of giving parameters explicitly will override any values given in Machine Profile. For instance, if ServiceOffering is given to be Standard_D2s_v3 and Machine Profile specifies a machine size of Standard_D4s_v5, machines will be provisioned with Standard_D2s_v3.

Additionally, some properties will be inferred from the chosen master image if not defined explicitly or via Machine Profile.

To summarize the order in which properties are taken for New-ProvScheme follows:

  • PowerShell parameters (CustomProperties, ServiceOffering, etc) > MachineProfile values > Master image values > Default values

Consider the below example that illustrates the order in which properties are used:

  • PowerShell parameters provided: ServiceOffering, CustomProperties (containing one property: CustomA)
  • MachineProfile defines: ServiceOffering, NetworkMapping, CustomProperties (containing two properties: CustomA, CustomB)
  • Master image defines: CustomProperties (containing two properties: CustomB, CustomC)
  • The end result is that the catalog will use ServiceOffering and custom property CustomA from the provided PowerShell parameters, NetworkMapping and custom property CustomB from MachineProfile, custom property CustomC from the master image.

It’s also important to note the behavior of commands that update existing provisioning schemes/virtual machines: Set-ProvScheme and Set-ProvVM. If a property was set explicitly previously, it will be overridden when the property can be read from a provided Machine Profile and the property is not separately provided. Take the following example:

  • Catalog is created using a MachineProfile and a ServiceOffering provided explicitly of Standard_D2s_v3 and CustomProperties providing a StorageType of Premium_LRS
  • Catalog is updated providing only a MachineProfile that has a ServiceOffering defined as Standard_D4s_v5
  • The end result is that the catalog’s MachineProfile is updated to the new value, the ServiceOffering is updated to Standard_D4s_v5, and StorageType remains as Premium_LRS

In short, for Set-ProvScheme / Set-ProvVM, the order in which properties are used is the following:

  • PowerShell parameters (CustomProperties, ServiceOffering, etc) > MachineProfile values > Previously configured values

Azure Specific Information

When using Azure, there are two types of resources that can be used as a Machine Profile:

  • Virtual Machine: An ARM template will be generated from the virtual machine selected and related resources that are attached (NICs, OS disk, virtual machine extensions, Azure Monitor data collection rules and diagnostic settings) which will be used to create machines in a provisioning scheme.
  • Template Spec Version: An ARM template given explicitly which will be used to create machines in a provisioning scheme. It must contain a definition for a virtual machine resource and at least one network interface. And may include one definition for a disk and any number of virtual machine extensions, Azure Monitor data collection rules and diagnostic settings. A template spec version can be checked for any validation errors prior to use with the cmdlet Test-ProvInventoryItem. A good starting point when building an ARM template to use as Machine Profile is to export the ARM templates for an existing virtual machine and its NIC and make changes from there.

Both types of Machine Profile fully support the same features so whichever is more convenient can be used.

The following are example properties that can be captured from the resource provided as Machine Profile input:

  • Trusted launch (vTPM)
  • Disk Encryption Set
  • Disk storage type
  • Machine size
  • Tags
  • NIC accelerated networking

When the Machine Profile provides virtual machine extensions, only extension types on the allowed list of extensions are carried through, the rest are stripped out. The following extension types are allowed by default:

  • AADLoginForWindows
  • AzureMonitorWindowsAgent
  • AzureMonitorLinuxAgent

Other extension types can be added to the allowed list of extension types with Add-ProvMetadataConfiguration.

Azure has the following properties that can be provided explicitly or through Machine Profile:

  • ServiceOffering (via properties/hardwareProfile/vmSize from the VM resource)
  • NetworkMapping (via properties/ipConfigurations/subnet/id from the NIC resources)
  • SecurityGroups (via properties/ipConfigurations/networkSecurityGroup/id from the NIC resources)

  • CustomProperties

    • DiskEncryptionSetId (via properties/storageProfile/osDisk/managedDisk/diskEncryptionSet/id from the VM resource or properties/encryption/diskEncryptionSetId from the disk resource)
    • StorageType (via properties/storageProfile/osDisk/managedDisk/storageAccountType from the VM resource or sku/name from the disk resource)
    • OsType (via properties/storageProfile/osDisk/osType from the VM resource or properties/osType from the disk resource)
    • Zones (via zones on either the VM or disk resource. Note: This property sets the availability zones)
    • LicenseType (via properties/licenseType from the VM resource)
    • DedicatedHostGroupId (via host/id or hostgroup/id from the VM resource)

Additionally, the following CustomProperties will be read from the master image if not provided explicitly or through Machine Profile:

  • OsType
  • DiskEncryptionSetId

Aws Specific Information

When using AWS, there are two types of resources that can be used as a Machine Profile:

  • EC2 instance: An AWS VM and resources attached to it (e.g., ENIs, root volume, EBS volume properties) will be used to create machines in a provisioning scheme.
  • Launch Template Version: An AWS Launch Template Version given explicitly which will be used to create machines in a provisioning scheme.

The following are example properties that can be captured from the resource provided as Machine Profile input:

  • Instance type
  • EBS optimization
  • Hibernation
  • Elastic Graphics
  • Tags
  • Security Groups
  • IAM profile

AWS also has the following properties that can be provided explicitly or through Machine Profile:

  • ServiceOffering
  • NetworkMapping
  • TenancyType
  • SecurityGroups

Gcp Specific Information

When using Google Cloud Platform, there are two types of resources that can be used as a Machine Profile:

  • VM Instance: Virtual Machines within GCP
  • Instance Template: Serialized Hardware Properties of a GCP Instance

Both types of Machine Profile fully support the same features so whichever is more convenient can be used.

The following are example properties that can be captured from the resource provided as Machine Profile input:

  • Service accounts (via properties/serviceAccounts from the resource)
  • Accelerators (via properties/GuestAccelerators from the resource)
  • Availability policies (via Properties/AvailabilityPolicies from the resource)
  • Shielded VM policies (via Properties/AvailabilityPolicies from the resource)
  • Tags (coming soon)

GCP has the following properties that can be provided explicitly or through Machine Profile:

  • ServiceOffering (via properties/MachineType from the machine profile resource)

  • CustomProperties

    • CatalogZones (via properties/zone. Not applicable if Machine profile is an instance template since instance templates are global resources. All zones in the region will be used in this case.)
    • StorageType (via properties/type from OS disk attached to resource)
    • CryptoKeyId (via properties/Encryption/KeyId from OS disk attached to resource)

Scvmm Specific Information

When using SCVMM, the following resource can be used as a Machine Profile input:

  • Virtual Machine: The properties of the Virtual Machine will be used to create machines in a provisioning scheme.

Note: In SCVMM, we do not support template for Machine Profile.

The following are all the properties that can be captured from the resource provided as Machine Profile input:

  • CPU count
  • CPU Type
  • LimitCPUForMigration
  • TPM (Trusted Platform Module)
  • NetworkInterfaceDetails (through network adapters)
  • Memory
  • Nested Virtualization
  • Secure Boot
  • Operating System
  • VM Generation

Note: Tags are not captured from the virtual machine as machine profile input in SCVMM

SCVMM has the following properties that can be provided explicitly or through Machine Profile:

  • VMCpuCount
  • VMMemoryMB
  • NetworkMapping

Note: Machine Profile cannot be added/updated on existing machines as SCVMM does not currently support either Set-ProvVMUpdateTimeWindow or Set-ProvVM

Xenserver Specific Information

When using XenServer, the following resource can be used as a Machine Profile input:

  • Virtual Machine: Snapshot of a Virtual Machine

The following are example properties that can be captured from the resource provided as Machine Profile input:

  • CPU count
  • Memory
  • Network Mapping
  • Tags
  • Generation
  • VGPU

XenServer has the following properties that can be provided explicitly or through Machine Profile:

  • VMCpuCount
  • VMMemoryMB
  • NetworkMapping

Note: Machine Profile cannot be added/updated on existing machines as SCVMM does not currently support either Set-ProvVMUpdateTimeWindow or Set-ProvVM

Vmware Specific Information

When using VMware, the following resource can be used as machine profile input:

  • VM Template: Can be created in two ways - Converting an existing VM into a VM Template, or cloning an existing VM to a VM Template.

All hardware properties are captured from the machine profile template. Here are some relevant examples:

  • Folder ID
  • vTPM Data
  • Memory
  • CPU Count
  • Storage Policy
  • Guest OS
  • NIC Count
  • VM Tags

VMWare has the following properties that can be provided explicitly or through Machine Profile:

Note the following information around specific properties:

  • vTPM: If the master image VM is vTPM enabled, the VM template must come from the same master image VM.

  • CPU and Cores per Socket: For VMware, CPU Count must be an integral multiple of Cores per Socket. For example, 6 CPU count can have 1,2,3, or 6 Cores per Socket. 4 CPU count can have 1,2, or 4 Cores per Socket.

    • For a new Catalog, both CPU Count and Cores per Socket value are picked up from the machine profile. Unless CPU count is also provided as a parameter, in which case that value is used.
    • For an existing catalog, CPU Count by itself can be updated using the “VmCpuCount” parameter of Set-ProvScheme, but this does not change the value of Cores per Socket. To update both values, provide a new VM Template with the required changes as the Machine Profile parameter in Set-ProvScheme.
  • Storage Policy: Only captured in a vSAN Datastore.

  • NICs: Only the NIC count from the Machine Profile is used. Network mappings from the Machine Profile are not used.

    • NIC count cannot be 0 or higher than what the hosting unit can support.
    • If NIC count is 1, and no mapping is provided, default network/subnet from the Hosting Unit is used.
    • If NIC count is greater than 1, network mapping needs to be provided for each NIC.
    • Mapping has to be 1:1, that is, only one NIC can be mapped to one subnet on the Hosting Unit.

See Also

about_Prov_MachineProfile
August 9, 2024
Contributed by: 
C
August 9, 2024
Contributed by: 
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.