Product documentation
Citrix Virtual Apps and Desktops
Current Release Service 2411 2407 2402 LTSR 2311 2203 LTSR
View PDF

Create an AWS catalog

July 30, 2025
Contributed by: 
C

Create machine catalogs describes the wizards that create a machine catalog. The following information covers details specific to AWS virtualization environments.

Note:

Before creating an AWS catalog, you need to finish creating a connection to AWS. See Connection to AWS.

Limitation

From Citrix Virtual Apps and Desktops 2203 LTSR and later, MCS AWS plug-in makes DescribeInstanceTypes AWS API call and if that succeeds, then MCS uses the inventory name created from the API response.

Therefore, when you upgrade from Citrix Virtual Apps and Desktops 1912 to 2203 or later, disable the DefineInstanceType permission on AWS, and then update the existing catalog using Set-ProvScheme command to match the AWS naming scheme. Then, add the DescribeInstanceType permissions back after catalog update is complete and the service offering matches AWS naming scheme.

Network setting during image preparation

During image preparation, a preparation virtual machine (VM) is created based on the original VM. This preparation VM is disconnected from the network. To disconnect the network from the preparation VM, a network security group is created to deny all inbound and outbound traffic. This network security group persists and is reused. The network security group’s name is Citrix.XenDesktop.IsolationGroup-GUID, where GUID is randomly generated.

Configure AWS tenancy

AWS provides the following tenancy options:

  • Shared tenancy (the default type): Multiple Amazon EC2 instances from different customers might reside on the same piece of physical hardware.
  • Dedicated tenancy: Your EC2 instances run only on hardware with other instances that you have deployed. Other customers do not use the same piece of hardware.

You can use MCS to provision AWS dedicated hosts by using PowerShell.

Configure AWS dedicated host tenancy using PowerShell

You can create a catalog of machines with host tenancy defined through PowerShell.

An Amazon [EC2] dedicated host is a physical server with [EC2] instance capacity that is fully dedicated, allowing you to use existing per-socket, or per-VM software licenses.

Dedicated hosts have preset utilization based on instance type. For example, a single allocated dedicated host of C4 Large instance types is limited to running 16 instances. See the AWS site for more information.

The requirements for provisioning to AWS hosts include:

  • An imported BYOL (bring your own license) image (AMI). With dedicated hosts, use and manage your existing licenses.
  • An allocation of dedicated hosts with sufficient utilization to satisfy provisioning requests.
  • enable auto-placement.

To provision to a dedicated host in AWS using PowerShell, use the New-ProvScheme cmdlet with the parameter TenancyType set to Host.

Refer to the Citrix Developer Documentation for more information.

Capture machine properties from machine profiles

When creating a catalog to provision AWS machines using MCS, you can use a machine profile to preset certain machine property settings.

To do so, follow these steps:

  1. Store the machine profiles in the same availability zone as the resources where you are creating this catalog.
  2. On the Machine Template page of the catalog creation wizard, select Use a machine profile. Machine profiles that are in the same available zone as the resources you selected are shown.
  3. Select a machine profile as needed.

Tag AWS operational resources

When creating a catalog to provision machines in AWS by using MCS, you can control whether to apply the IAM role and tag properties to those machines. You can also control whether to apply machine tags to operational resources.

An Amazon Machine Image (AMI) represents a type of virtual appliance used to create a virtual machine within the Amazon Cloud environment, commonly referred to as EC2. You use an AMI to deploy services that use the EC2 environment. When you create a catalog to provision machines using MCS for AWS, you select the AMI to act as the golden image for that catalog.

Important:

Creating catalogs by using both a machine profile and a launch template is required for using operational resource tagging.

To create an AWS catalog, you must first create an AMI for the instance you want to be the golden image. MCS reads the tags from that instance and incorporates them into the launch template. The launch template tags are then applied to all Citrix resources created in your AWS environment, including:

  • Virtual Machines
  • VM disks
  • VM network interfaces
  • S3 buckets
  • S3 objects
  • Launch templates
  • AMIs

Tag operational resources using Web Studio

When creating a catalog to provision machines in AWS by using MCS, you can control whether to apply machine tags to operational resources by selecting the Apply machine tags to operational resources option on the Machine Template page.

This option controls whether to apply machine tags to every item created in your AWS environment that facilitates provisioning of machines. Operational resources are created as byproducts of catalog creation. They include both temporary and persistent resources, such as preparation VM instance and AMI.

Tag operational resources using PowerShell

To use PowerShell to tag resources:

  1. Open a PowerShell window from the DDC host.
  2. Run the command asnp citrix to load Citrix-specific PowerShell modules.

To tag a resource for a provisioned VM, use the custom property AwsOperationalResourcesTagging. Example:

New-ProvScheme -ProvisioningSchemeName test 
-CustomProperties “AwsOperationalResourcesTagging,true” 
-MachineProfile "XDHyp:\HostingUnits\xxxx-ue1a\machineprofiletest (lt-01xxxxx).launchtemplate\lt-01xxxxx (1).launchtemplateversion" 
... <Other <standard provscheme parameters>
<!--NeedCopy-->

Copy tags on VMs

You can copy tags on NICs, and disks (Identity disk, write back cache disk, and OS disk) that are specified in the machine profile to newly created VMs in an MCS machine catalog. You can specify these tags in any of the machine profile sources (AWS VM instance or AWS launch template version). This feature is applicable to persistent and non-persistent machine catalogs and VMs.

Note:

  • On AWS EC2 console, you cannot see Tag Network Interfaces values under the Launch Template Version Resource Tags. However, you can run the PowerShell command aws ec2 describe-launch-template-versions --launch-template-id lt-0bb652503d45dcbcd --versions 12 to see the tag specifications.
  • If a machine profile source (VM or launch template version) has two network interfaces (eni-1 and eni-2), and eni-1 has tag t1 and eni-2 has tag t2, then the VM gets both the two network interfaces’ tags.

Create a catalog using a machine profile

You can use a machine profile to capture the hardware properties from an EC2 instance (VM) or launch template version and apply them to the provisioned machines. Properties that are captured can include, for example, EBS volume properties, instance type, EBS optimization, CPU options, tenancy type, hibernation capability and other supported AWS configurations.

You can use an AWS EC2 Instance (VM) or AWS launch template version as the machine profile input.

Note:

  • EBS volume properties are derived only from a machine profile.
  • MCS provisions VMs with Identity disks of GP3 volume type. As GP3 volume type is the cheapest option offered by AWS, this feature minimizes cost. The implementation is applicable only to the VMs added to a new catalog and new VMs added to an existing catalog. Existing VMs created before this feature will continue to have ID disks with GP2 volume type, unless the ID disk is reset.

Important considerations

The important considerations while creating an MCS machine catalog:

  • If you add machine hardware property parameters in the New-ProvScheme and Set-ProvScheme commands, then the values provided in the parameters overwrite the values in the machine profile.
  • If you set AwsCaptureInstanceProperties as true and do not set MachineProfile property, then only IAM roles and tags are captured.

  • You cannot set both AwsCaptureInstanceProperties and MachineProfile at the same time.

    Note:

    The AwsCaptureInstanceProperties is deprecated.

  • If a machine profile is not provided, you must explicitly provide the values of the following properties:

    • Security Group
    • ENI or Virtual Network
  • You can enable AwsOperationalResourcesTagging only if you enable AwsCaptureInstanceProperties or specify a machine profile.

The important considerations after creating an MCS machine catalog:

  • You cannot change a catalog from machine profile-based to non-machine profile-based catalog.

Create a machine catalog using a machine profile

To create a machine catalog using a machine profile:

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

  3. Create an identity pool if not already created. For example,

    New-AcctIdentityPool -IdentityPoolName idPool -NamingScheme ms## -Domain abcdf -NamingSchemeType Numeric
<!--NeedCopy-->

  4. Run New-ProvScheme command. For example:

    New-ProvScheme -ProvisioningSchemeName demet-test-1
-HostingUnitUid aa633238-9xxd-4cf6-80e8-232a758a1xx1
-IdentityPoolUid 34d5b088-e312-416f-907d-16573xxxxxc4
-CleanOnBoot
-MasterImageVM 'XDHyp:\HostingUnits\cvad-test-scalestress\citrix-demet-ami.0 (ami-0ca813xxxxxx061ef).template'
-MachineProfile 'XdHyp:\HostingUnits\cvad-test-scalestress\us-east-1a.availabilityzone\machine-profile-instance i (i-0xxxxxxxx).vm'
<!--NeedCopy-->
  5. Complete creating the catalog. For more information, see Citrix PowerShell SDK.

Update the machine profile

To update the machine profile on a catalog that was initially provisioned with a machine profile, do the following. You can also change the tenancy type and hibernation capability of the machine profile source while editing an MCS machine catalog.

  1. Run Set-ProvScheme command. For example,

    Set-ProvScheme `
-ProvisioningSchemeUid "<ID" `
-MachineProfile "XDHyp:\HostingUnits\abc\us-east-1a.availabilityzone\citrix-cvad-machineprofile-instance (i-0xxxxxxxx).vm"
<!--NeedCopy-->

Create a catalog with launch template version

You can create an MCS machine catalog with a launch template version as a machine profile input. You can also update the input of a machine profile catalog from a VM to a launch template version and from a launch template version to a VM.

On the AWS EC2 console, you can provide the instance configuration information of a launch template along with version number. When you specify the launch template version as a machine profile input while creating or updating a machine catalog, the properties from that version of the launch template are copied to the provisioned VDA VMs.

The following properties can be provided using machine profile input or explicitly as parameters in New-ProvScheme or Set-ProvSchemecommands. If they are provided in New-ProvScheme or Set-ProvScheme commands, they take precedence over the machine profile values of these properties.

  • Service Offering
  • Networks
  • Security Groups
  • Tenancy Type

Note:

If service offering is not provided in the machine profile launch template or as a parameter in the New-ProvScheme command, you get an appropriate error.

To create a catalog using launch template version as a machine profile input:

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

  3. Get the list of launch template versions of a launch template. For example:

    XDHyp:\HostingUnits\test\test-mp-sard (lt-01xxxxx).launchtemplate> ls | Select FullPath
<!--NeedCopy-->

  4. Create an identity pool if not created. For example:

    New-AcctIdentityPool `
-IdentityPoolName "abc11" `
-NamingScheme "abc1-##" `
-NamingSchemeType Numeric `
-Domain "citrix-xxxxxx.local" `
-ZoneUid "xxxxxxxx" `
<!--NeedCopy-->

  5. Create a provisioning scheme with a launch template version as a machine profile input. For example:

    New-ProvScheme `
-ProvisioningSchemeName "MPLT1" `
-HostingUnitUid "c7f71f6a-3f45-4xxx-xxxx-xxxxxxxxxx" `
-IdentityPoolUid "bf3a6ba2-1f80-4xxx-xxxx-xxxxxxxxx" `
-MasterImageVM "XDHyp:\HostingUnits\xxxd-ue1a\apollo-non-persistent-vda-win2022 (ami-0axxxxxxxxxxx).template" `
-CleanOnBoot `
-MachineProfile "XDHyp:\HostingUnits\xxxx-ue1a\machineprofiletest (lt-01xxxxx).launchtemplate\lt-01xxxxx (1).launchtemplateversion"
<!--NeedCopy-->

  6. Register provisioning scheme as a broker catalog. For example:

    New-BrokerCatalog -Name "MPLT1" `
-AllocationType Random `
-Description "Machine profile catalog" `
-ProvisioningSchemeId fe7df345-244e-4xxxx-xxxxxxxxx `
-ProvisioningType Mcs `
-SessionSupport MultiSession `
-PersistUserChanges Discard
<!--NeedCopy-->
  7. Complete creating the catalog. For more information, see Citrix PowerShell SDK

You can also update the input of a machine profile catalog from a VM to a launch template version and from a launch template version to a VM. For example:

  • To update the input of a machine profile catalog from a VM to a launch template version:

     Set-ProvScheme -ProvisioningSchemeName "CloudServiceOfferingTest" `
 -MachineProfile "XDHyp:\HostingUnits\xxxx-ue1a\machineprofiletest (lt-0bxxxxxxxxxxxx).launchtemplate\lt-0bxxxxxxxxxxxx (1).launchtemplateversion"
 <!--NeedCopy-->

  • To update the input of a machine profile catalog from a launch template version to a VM:

     Set-ProvScheme -ProvisioningSchemeName "CloudServiceOfferingTest" `
 -MachineProfile "XDHyp:\HostingUnits\sard-ue1a\us-east-1a.availabilityzone\apollo-non-persistent-vda-win2022-2 (i-08xxxxxxxxx).vm"
 <!--NeedCopy-->

MCSIO enabled catalog

MCS Storage Optimization (MCSIO) improves the performance of the VM by caching disk operations in either memory or on a small, high-speed disk. You can create an MCSIO enabled non-persistent catalog using PowerShell commands. To create such a catalog, you must install the MCSIO driver while installing or upgrading the VDA during the preparation of the AMI instance. By default, that driver is not installed.

After an MCSIO AMI is prepared, you can create an MCSIO enabled non-persistent catalog.

Create an MCSIO enabled catalog

The four parameters added to the New-ProvScheme PowerShell command are:

  • UseWriteBackCache: Turns on caching (write-back cache) for the given provisioning scheme
  • WriteBackCacheDiskSize: Specifies the size in GB of the temporary disk used for caching
  • WriteBackCacheMemorySize: Specifies how much memory in MB to use for caching. This is an optional parameter.
  • WriteBackCacheDriverLetter: Specifies the drive letter to assign for the cache storage disk. This is an optional parameter.

Note:

  • The value of WriteBackCacheDiskSize must be more than zero because at least 1 GB of cache disk storage is required. The cache disk size must not be bigger than the OS disk size.
  • The value of WriteBackCacheMemorySize must be non-zero and less than the machine catalog memory size.

The custom properties that affect MCSIO are:

  • WBCDiskStorageType: Defines the volume type which is used for the temporary disk in AWS. This parameter takes a string argument in the format volume-type[:iops][:throughput]. The following are the volume types:

    • gp2: Do not use iops and throughput parameters for this volume type
    • gp3: Use iops and throughput parameters for this volume type
    • io1: Use only iops parameter for this volume type
    • io2: Use only iops parameter for this volume type

    The default volume type is gp2.

  • PersistWBC: Controls whether to keep or discard the cache disk whenever the AWS instance is powered off. If set to true, the cache disk is kept. If set to false (the default), the cache disk is only created and kept while the AMI instance is powered on.
  • PersistOSDisk: Controls whether to keep or discard the OS disk whenever the AWS instance is powered off. If set to true, the OS disk is kept. If set to false (the default), the OS disk is only created and kept while the AMI instance is powered on.

Perform the following steps in the PowerShell window to create an MCSIO enabled non-persistent catalog:

  1. Open the PowerShell window.
  2. Run asnp citrix* to load the Citrix-specific PowerShell modules.
  3. Create a broker catalog and an identity pool.

  4. Create the provisioning scheme. For example:

    $HostingUnitUid = '0xxxx1d9-bbfc-xxxf-bxxb-exxxxxe008b2'
$MasterImageVM = 'XDHyp:\HostingUnits\ctx-test\aws-apollo-non-persistent-multi-mcsio-vda-win2022 (ami-0bf1810488acbxxxb).template'
$NetworkMap = @{ 'NetworkPath' = 'XDHyp:\HostingUnits\ctx-test\us-east-1a.availabilityzone\10.0.128.0`/17 (vpc-0fa6e41d72507fxxx).network' }
$SecurityGroup = $( 'XDHyp:\HostingUnits\ctx-test\us-east-1a.availabilityzone\private.securitygroup' )
$ServiceOffering = 'XDHyp:\HostingUnits\ctx-test\T3 Medium Instance.serviceoffering'
$CustomProperties = 'WBCDiskStorageType,gp3:6000:250;PersistWBC,false'


$provScheme = New-ProvScheme -ProvisioningSchemeName $CatalogName -HostingUnitUid $HostingUnitUid `
-IdentityPoolUid $acctPool.IdentityPoolUid -CleanOnBoot `
- MasterImageVM $MasterImageVM `
-NetworkMap $NetworkMap `
-ServiceOffering $ServiceOffering `
-SecurityGroup $SecurityGroup `
-CustomProperties $CustomProperties `
-UseWriteBackCache -WriteBackCacheDiskSize 16 -WriteBackCacheMemorySize 256
<!--NeedCopy-->
  5. Add VMs to the catalog.

Improve boot performance with MCSIO

You can improve the boot performance of VMs if you enable MCSIO and set PersistWBC and PersistOSDisk custom properties as true. With such a setting, VMs can boot faster because they do not need to initialize a new cache disk or to recreate a root disk from their template.

Encrypt OS and ID disks

You can create persistent and non-persistent catalog of VMs with AWS KMS keys (Customer managed key and AWS managed key) that can be used to encrypt OS disk and Identity disk.

  • AWS managed keys are automatically rotated every year.
  • Customer managed keys are optional for automatic rotation and can be managed manually.

You can see the following AWS documents for more information on KMS keys:

For encryption of OS and ID disks, configure one of the following:

  • Use a master image that is encrypted (for example, an AMI created from an instance or snapshot that contains a EBS root volume encrypted with KMS key)
  • Use a machine profile source (VM or launch template) that contains an encrypted EBS root volume.

Limitations

Consider the following limitations:

  • MCS currently supports only one disk on master image AMI.

  • You cannot directly encrypt existing unencrypted EBS volumes or snapshots, or modify the KMS key of an existing encrypted volume. To do that, you must:

    1. Create a new snapshot of that volume.
    2. Create a new volume from that snapshot.
    3. Encrypt the new volume.

See the following AWS documents:

Create a catalog with disk encryption

You can create an MCS machine catalog with disk encryption using:

  • Master image
  • Machine profile

Considerations while using machine profile input for disk encryption:

  • The KMS key of machine profile input takes precedence over the master image’s KMS key.
  • If no machine profile input is provided, then the KMS key of the master image AMI is used to encrypt the disks of catalog VMs.
  • If the machine profile has Block Device Mappings present, then the block devices present in the master image template (AMI) and machine profile must match. For example, if AMI has a device defined on /dev/sda1, then the Machine Profile must also have a device defined on /dev/sda1.
  • If there is no key in the machine profile source and master image is unencrypted, then disks of catalog VMs are not encrypted.
  • When the master image is encrypted, a machine profile source VM or launch template must have an encrypted root volume to be considered a valid input.

Modify an existing catalog

You can modify an existing catalog using Set-ProvScheme to have:

  • A machine profile input with a volume containing a new KMS key.
  • A master image template AMI encrypted with a new KMS key.

Important considerations

  • The volumes of new VMs added to the catalog are encrypted with the new KMS key.
  • To update encryption settings when there is an existing machine profile, run Set-ProvScheme with a new machine profile.
  • You cannot modify an existing catalog from having encrypted volumes to unencrypted volumes. You cannot do an image update from an encrypted master AMI to an unencrypted master AMI.

Enable NitroTPM and UEFI secure boot for VM instances

When creating a catalog, you can now select a master image (AMI) with NitroTPM and/or UEFI secure boot enabled. Accordingly, the provisioned VMs in the catalog are also enabled with NitroTPM and/or UEFI secure boot. This implementation ensures that the VMs are secured and trusted. For more information on NitroTPM and UEFI Secure Boot, see the Amazon documentation.

Limitations

  • You can use both NitroTPM and Secure Boot currently in all AWS Regions (including the AWS GovCloud (US) Regions) except China.
  • You cannot enable NitroTPM and UEFI secure boot on existing catalogs. If you want a catalog with NitroTPM and UEFI secure boot enabled, create a new catalog.

Key steps

  1. Set up your AWS environment.
  2. Create a connection to AWS.
  3. Create a master image (AMI) enabled with NitroTPM and/or UEFI secure boot.
  4. Create a machine catalog by selecting the master image with NitroTPM and UEFI secure boot enabled in Web Studio catalog creation menu or when creating a Provisioning Scheme using PowerShell commands.

VMs added to the created catalog have NitoTPM and UEFI secure boot enabled.

Create an AMI that supports NitroTPM and UEFI secure boot

  1. You can create an AMI from a VM that has NitroTPM and/or UEFI secure boot enabled.

    1. Create the instance from using the AWS marketplace images. Example, search for TPM-Windows_Server-2022-English-Full-Base on the aws-marketplace.
    2. Download single or multi session VDA.
    3. Create an AMI from that VM.

  2. Use the register-image command:

    --boot-mode (string)
--tpm-support (string)
<!--NeedCopy-->

    For more information, see register-image.

See the following AWS documents:

You can open a PowerShell window from the Delivery controller host to check if a specific:

  • service offering supports NitroTPM or UEFI secure boot

     (Get-Item -Path “XDHyp:\HostingUnits\aws\T3 Medium Instance.serviceoffering”).AdditionalData.BootMode
 (Get-Item -Path “XDHyp:\HostingUnits\aws\T3 Medium Instance.serviceoffering”).AdditionalData.NitroTpmSupportVersions
 <!--NeedCopy-->

  • template supports NitroTPM or UEFI secure boot

     (Get-HypInventoryItem -LiteralPath “XDHyp:\HostingUnits\aws” -ResourceType “template -Id “ID”).AdditionalData.BootMode

 (Get-HypInventoryItem -LiteralPath “XDHyp:\HostingUnits\aws” -ResourceType “template -Id “ID”).AdditionalData.TpmSupport
 <!--NeedCopy-->

Update the service offering of existing catalog

You can change the service offering of an existing catalog using Set-ProvScheme. The change applies to the newly added VMs. However, you get errors in the following scenarios:

AMIs boot mode AMI supports Nitro TPM? Service offering supports NitroTPM and UEFI secure boot?
UEFI No No
Legacy BIOS Yes No
UEFI Yes No
UEFI Preferred Yes No

Filter VM instances

An AWS EC2 instance that you use as a machine profile VM must be compatible for the machine catalog to create and function correctly. To list the AWS EC2 instances that can be used as machine profile input VMs, you can use the Get-HypInventoryItem command. The command can page and filter the inventory of VMs available on a hosting unit.

Pagination:

Get-HypInventoryItem supports two modes of pagination:

  • Paging mode uses the -MaxRecords and -Skip parameters to return sets of items:
    • -MaxRecords: The default is 1. This controls how many items to return.
    • -Skip: The default is 0. This controls how many items to skip from the absolute beginning (or absolute end) of the list in the hypervisor.
  • Scrolling mode uses -MaxRecords, -ForwardDirection, and -ContinuationToken parameters to allow scrolling of the records:
    • -ForwardDirection: The default is True. This is used along with -MaxRecords to return either the next set of matching records or the previous set of matching records.
    • -ContinuationToken: The returns the items immediately after (or before if ForwardDirection is false) but not including the item given in the ContinuationToken.

Examples of pagination:

  • To return a single record of the machine template with the lowest name. The AdditionalData field has the TotalItemsCount and the TotalFilteredItemsCount:

     Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType template
 <!--NeedCopy-->

  • To return 10 records of the machine template with the lowest name:

     Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType template -MaxRecords 10 | select Name
 <!--NeedCopy-->

  • To return an array of records ending with the highest name:

     Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType template -ForwardDirection $False -MaxRecords 10 | select Name
 <!--NeedCopy-->

  • To return an array of records starting at the machine template associated with the given ContinuationToken:

     Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType template -ContinuationToken "ami-07xxxxxxxxxx" -MaxRecords 10
 <!--NeedCopy-->

Filtering:

The following additional optional parameters are supported for filtering. You can combine these parameters with the pagination options.

  • -ContainsName "my_name": If the given string matches part of an AMI name, then the AMI is included in the Get result. For example:

     Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType template -MaxRecords 100 -ContainName ‘apollo’ | select Name
 <!--NeedCopy-->

  • -Tags '{ "Key0": "Value0", "Key1": "Value1", "Key2": "Value2" }': If an AMI has at least one of these tags, it is included in the Get result. For example:

     Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType template -MaxRecords 100 -Tags '{"opex owner": "Not tagged"}' | select Name
 <!--NeedCopy-->

    Note:

    Two tag values are supported. Not Tagged tag value matches items which do not have the given tag in their list of tags. All values tag value matches items which have the tag regardless of the value of the tag. Otherwise, the match happens only if the item has the tag and the value equals to what is given in the filter.

  • -Id "ami-0a2d913927e0352f3": If the AMI matches the given ID, it is included in the Get result. For example:

     Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType template -Id ami-xxxxxxxxxxxxx
 <!--NeedCopy-->

Filtering on AdditionalData parameter:

The AdditionalData filter parameter lists templates or VMs based on their capability, service offering, or any property which is in AdditionalData. For example:

(Get-HypInventoryItem -ResourceType "launchtemplateversion" -LiteralPath "XDHyp:\HostingUnits\aws" -MaxRecords 200).AdditionalData
<!--NeedCopy-->

You can also add a -Warn parameter to indicate the incompatible VMs. The VMs are included with an AdditionalData field named Warning. For example:

(Get-HypInventoryItem -ResourceType "launchtemplateversion" -LiteralPath "XDHyp:\HostingUnits\aws" -MaxRecords 200 -Template "ami-015xxxxxxxxx" -Warn $true).AdditionalData
<!--NeedCopy-->

Backup SKU list for VMs

Public clouds can sometimes run out of capacity for a specific EC2 instance type (primary SKU). If the primary VM configuration is not available, then the VM cannot start resulting in loss of time and business disruption. To address such scenarios, provide a list of backup EC2 instance types (backup SKUs) that MCS can fall back to in the case of capacity-related issues.

Use a custom property BackupVmConfiguration while creating or updating an MCS machine catalog to provide a list of backup EC2 instance types (Backup SKU List).

If the primary EC2 instance fails, MCS attempts to fall back on the backup EC2 instance types in the order you specify. If MCS is unable to fall back on any of the provided backup EC2 instance types, an error message is displayed. You can then try powering on the primary EC2 instance again. If this fails, MCS retries the backup EC2 instance types.

The backup SKU list can have on-demand instance.

This feature is applicable to both persistent and non-persistent MCS machine catalogs.

Important considerations

  • You can provide multiple backup EC2 instance types in the backup SKU list.
  • The backup SKU list must be unique.
  • A backup EC2 instance cannot be the same as the primary EC2 instance.
  • The backup EC2 instances must be valid AWS instance types.
  • Do not specify duplicate service offerings. Example: BackupVmConfiguration,t2.small|t3.small|t2.small is not valid.
  • The service offering specified in the list must be compatible with the machine catalog configuration. For example, if the catalog uses UEFI and the service offering specified in the backup list doesn’t support it, then the catalog creation or update fails during preflight.
  • You can modify the backup SKU list of an existing catalog using the Set-ProvScheme PowerShell command. You can modify existing VMs using the Set-ProvVM and Set-ProvVMUpdateTimeWindow PowerShell commands.

Configure backup EC2 instances

  1. Open a PowerShell window.
  2. Run asnp citrix\* to load the Citrix-specific PowerShell modules.
  3. Create a Broker catalog.
  4. Create an identity pool.

  5. Add a backup EC2 instance list using the custom property BackupVmConfiguration and create a provisioning scheme. For example:

    $serviceOffering = "XDHyp:\HostingUnits\$hostingUnitName\T3 Medium Instance.serviceoffering"
$customProperties = "AwsCaptureInstanceProperties,false;AwsOperationalResourcesTagging,false;BackupVmConfiguration,t2.small|t2.large|t3.small|t3.large;"
$createdProvScheme = New-ProvScheme -ProvisioningSchemeName $provisioningSchemeName -HostingUnitName $hostingUnitName -IdentityPoolName $provisioningSchemeName -NetworkMapping $networkMapping -SecurityGroup $securityGroupPath -ServiceOffering $serviceOffering -MasterImageVM $masterImageVm -CustomProperties $customProperties
<!--NeedCopy-->
  6. Update the BrokerCatalog with the unique Id of the provisioning scheme.
  7. Create and add VMs to the catalog.

Where to go next

More information

Create an AWS catalog
July 30, 2025
Contributed by: 
C
July 30, 2025
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.