Product documentation
Citrix DaaS™
View PDF

Create catalogs using prepared images in Amazon WorkSpaces Core Managed Instances

March 30, 2026
Contributed by: 
C

Create prepared images and use the prepared images to create an MCS machine catalog using:

  • Studio
  • PowerShell

Key steps

  1. Create the image definition and the initial image version.
  2. Create image versions from the initial image version.
  3. Use the image version as a prepared image to create a catalog.

Create an image definition and initial image version using Studio

To create an image definition and the initial image version, do the following:

  1. From Studio, go to the Images node, and click Create Image Definition. Click Next on the Introduction page.
  2. On the Image Definition page, specify the OS type and Session type for the image definition.

  3. On the Image page, select Resources (only the resources applicable for the set connection are listed), a master image to use as a template for creating the image version, and a machine profile for capturing hardware properties from. Select a machine profile to capture hardware properties from a VM instance or launch template version.

    Note:

    • Before selecting an image, verify that the master image has VDA 2311 or later installed and the MCSIO driver is installed on the VDA.
    • The Instance Metadata Service (IMDS) V2 is only supported and not IMDS V1. For information, see How Instance Metadata Service Version 2 works.
  4. On the Machine Specification page, select a machine size. The machine size of the machine profile (selected on the Image page) is selected by default.
  5. On the NICs page, select or add NICs for the preparation image. For each NIC, select an associated VPC subnet.
  6. On the Version Description page, enter a description for the initial image version created.
  7. On the Summary page, verify the details of the image definition and the initial image version created. Enter a name and description for the image definition. Click Finish.

Create image versions using Studio

Image versions allow for the management of different iterations or updates to a particular image. This functionality enables you to maintain multiple versions of an image for different purposes.

To create image versions from the initial image version, do the following:

Note:

The hosting unit of all the image versions must be the same.

  1. Go to the Images node, select an image version or an image definition, and click Create Image Version.
  2. On the Image definition page, you can change the hosting unit, and reselect the master image and machine profile for that image version.
  3. If you want the configuration of the image version to be different from the initial configured image version, then configure the settings on the Machine Specification and NICs pages of the Create Image Version dialog.
  4. Add a description for the image version. Click Finish.

Note:

If the creation of the image version fails for any reason, the Troubleshoot tab at the bottom provides a Retry option.

Create a prepared image version spec using PowerShell

The detailed PowerShell commands to create a prepared image version spec are as follows:

  1. Check the available image definition names using the Test-ProvImageDefinitionNameAvailable command. For example,

    Test-ProvImageDefinitionNameAvailable -ImageDefinitionName <string[]>
<!--NeedCopy-->

  2. Create an image definition using the New-ProvImageDefinition command. For example,

    New-ProvImageDefinition -ImageDefinitionName image1 -OsType Windows -VdaSessionSupport MultiSession
<!--NeedCopy-->

  3. Create a new configuration for image definition in the specified Hosting connection using the Add-ProvImageDefinitionConnection command.

    Add-ProvImageDefinitionConnection -ImageDefinitionName image1 -HypervisorConnectionName test-conn
<!--NeedCopy-->

  4. Create an image version using the New-ProvImageVersion command. For example,

    New-ProvImageVersion -ImageDefinitionName image1 -Description "version 1"
<!--NeedCopy-->

  5. Add a master image version spec to the image version using the Add-ProvImageVersionSpec command. For example,

    Add-ProvImageVersionSpec -ImageDefinitionName  image1  -ImageVersionNumber  1 -HostingUnitName wsc -MasterImagePath "XDHyp:\HostingUnits\wsc\win10-2411-ami (ami-00123456789abcdef).template”"
<!--NeedCopy-->

    Note:

    You can add only one master image version spec to one image version for a hosting unit.

  6. Create a prepared image version spec from the master image version spec using the New-ProvImageVersionSpec command. The SourceImageVersionSpecUid parameter is derived from the Add-ProvImageVersionSpec command. For example,

    New-ProvImageVersionSpec
-SourceImageVersionSpecUid  00000000-0000-0000-0000-00000000000
-MachineProfile 'XDHyp:\HostingUnits\wsc\w2022-2411 (lt-00123456789abcdef).launchtemplate\lt-00123456789abcdef (1).launchtemplateversion' -RunAsynchronously
<!--NeedCopy-->

Example of the complete set of PowerShell commands to create image definition, image version, and prepared image version spec:

New-ProvImageDefinition -ImageDefinitionName image1 -OsType Windows -VdaSessionSupport MultiSession
 
 
Add-ProvImageDefinitionConnection -ImageDefinitionName image1 -HypervisorConnectionName wsc -CustomProperties $CustomProperties
 
$imageVersion = New-ProvImageVersion -ImageDefinitionName image1 -Description "version 1"
 
$SourceImageVersionSpec = Add-ProvImageVersionSpec -ImageVersionUid $imageVersion.ImageVersionUid `
    -HostingUnitUid $hostingunit.HostingUnitUid `
    -MasterImagePath "XDHyp:\HostingUnits\wsc\win10-2411-ami (ami-00123456789abcdef).template”
 
New-ProvImageVersionSpec -MachineProfile 'XDHyp:\HostingUnits\wsc\w2022-2411 (lt-00123456789abcdef).launchtemplate\lt-00123456789abcdef (1).launchtemplateversion' -SourceImageVersionSpecUid $SourceImageVersionSpec.ImageVersionSpecUid
Add-ProvImageVersionSpecHostingUnit -ImageVersionSpecUid 00000000-0000-0000-0000-00000000000-HostingUnitName wsc
$PreparedImageVersionSpec = Get-ProvImageVersionSpec -ImageVersionUid $imageVersion.ImageVersionUid | Where SourceImageVersionSpecUid-eq $SourceImageVersionSpec.ImageVersionSpecUid
<!--NeedCopy-->

Note:

  • All image version specs in an image definition must belong to the same hosting unit.
  • An image version can have only one master image version spec and one prepared image version spec.
  • All image version specs must have a machine profile.

Share prepared images across availability zones and regions

You can now share a single prepared image across different availability zones, tied to different hosting units, within the same AWS region or in different regions for your Amazon WorkSpaces Core Managed Instances. This lets you use one prepared image to create and update MCS machine catalogs in various availability zones and regions. When sharing across different AZs in different regions, the prepared image version will be copied from the original region to the destination regions.

You can maintain a single prepared image and use it to create and update machine catalogs across multiple availability zones and regions tied to different hosting units. This significantly reduces your image management overhead, ensures consistency across deployments, and streamlines the provisioning process. You can also seamlessly update existing machine catalogs with prepared images from a different availability zone or region.

Use cases

  • Centralized Image Management: You create a prepared image in one availability zone (for example, us-east-1a). You can then share this image to other availability zones like us-east-1b within the same us-east-1 AWS region or us-west-1a in a different us-west-1 region. This allows a single image to serve multiple hosting units and simplifies maintenance for you.
  • Efficient Catalog Creation and Updates: You can use a prepared image created in AZ 1 (for example, us-east-1a) to create new catalogs in AZ 1. After sharing this image to AZ 2 (for example, us-east-1b), you can then use the shared image in AZ 2 to create and update catalogs in AZ 2.
  • Cross-hosting unit and hosting connection deployments: If your environment has multiple hosting units under the same or different AWS regions, you can efficiently share prepared images between these hosting units.

Limitations

  • Sharing within same AWS Account: You cannot share across different AWS Accounts in the current implementation.

Important considerations

  • Deletion order: To delete an original prepared image version specification, you must first delete all its shared image version specifications. Alternatively, you must delete the original and shared specifications simultaneously.
  • Image Version dependency: When you remove an image version, you must first remove any sharing configurations that depend on that specific image version. Catalogs that you created from the original (unshared) image can remain intact.
  • Catalog back-portability: You can update existing machine catalogs that you deployed before this feature’s introduction. Use prepared images that you created in a different availability zone or region from where you originally deployed the catalog.
  • Complete deletion: When you delete a prepared image, you can no longer use it in any availability zone where you shared or originally created it. Moreover, a prepared image version cannot be deleted until all catalog tied the prepared image version are deleted first.

Prerequisites

Before you configure or use this feature, ensure that you meet the following conditions:

  • Your environment must be an Amazon WorkSpaces Core Managed Instances environment.
  • You must configure multiple hosting units (each can be tied to different availability zones) and host connections (each can be tied to a different region) under the same AWS account.

Configure using Studio UI

You can share prepared images across availability zones tied to different hosting units using the Studio UI.

To share a prepared image

  1. Navigate to the Images node of the Studio and select the prepared image version you wwant to share with other availability zones.
  2. Select Manage Image Share at the top navigation bar to manage the image sharing for the selected image version.
  3. On the Manage Image Share page, select one or more resources you want to share the image version with. The resources can be in different availability zones from that of the original image version.
  4. Click Save to share the image version in the resources across other availability zones. The image version is updated such that it is shared across the different resources that you selected. Once complete, use the image version to create catalogs in the availability zones the image version is shared across.

To remove sharing of a prepared image

  1. On the Images node of the Studio, select the prepared image version you would like to remove from sharing.
  2. Select Manage Image Share at the top navigation bar to manage the image sharing for the selected image version.

  3. Clear the checkboxes from one or more resources (availability zones) that you want to stop sharing the image version with.

    Note:

    The resources must no longer have any catalogs associated with and created from the shared image version. Any catalogs created from the shared image version to be removed must be deleted first.

  4. Click Save to remove sharing of the resources across the cleared availability zones. The image version is updated such that it is no longer shared in those availability zones.

Configure using PowerShell

Alternatively, you can share prepared images across availability zones tied to different hosting units using PowerShell commands.

To share a prepared image

  1. Ensure that you have the ImageVersionSpecUid of the prepared image you want to share. You can retrieve this using Get-ProvImageVersionSpec or similar Get- commands in PowerShell.
  2. Determine the HostingUnitName of the availability zone (can be the same or a different region) where you want to make the prepared image available. This is the name of the hosting unit you configured for that specific AZ.

  3. Run the Add-ProvImageVersionSpecHostingUnit command: Use the following PowerShell command. Replace <ImageVersionSpecUid> with your image’s Uid and <targetHostingUnitName> with the name of the hosting unit in the target availability zone that you want to share the image version specification to:

    Add-ProvImageVersionSpecHostingUnit -ImageVersionSpecUid <ImageVersionSpecUid> -HostingUnitName <targetHostingUnitName>
<!--NeedCopy-->
  4. After successful execution, you can see the image’s status in the Studio UI indicating that you shared it with the specified hosting unit.

To remove sharing of a prepared image

  1. Ensure you have the ImageVersionSpecUid of the prepared image from which you want to remove sharing.
  2. Determine the HostingUnitName of the availability zone from which you want to remove the shared image.

  3. Run the Remove-ProvImageVersionSpecHostingUnit command: Use the following PowerShell command. Replace <ImageVersionSpecUid> with your image’s Uid and <targetHostingUnitName> with the name of the hosting unit in the target Availability Zone that you want to remove the sharing of the image version specification from:

    Remove-ProvImageVersionSpecHostingUnit -ImageVersionSpecUid <ImageVersionSpecUid> -HostingUnitName <targetHostingUnitName>
<!--NeedCopy-->

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.

A machine profile-based machine catalog

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, tenancy type, instance type, security groups, network mappings, EBS volume properties, EBS optimization, CPU options, 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:

AWS tenancy

AWS provides the following tenancy options: shared tenancy (the default type) and dedicated tenancy. Shared tenancy means that multiple Amazon WorkSpaces Core instances from different customers might reside on the same piece of physical hardware. Dedicated tenancy means that your Amazon WorkSpaces Core instances run only on hardware with other instances that you have deployed.

Note:

The dedicated instances are only supported (dedicated hosts are currently not supported). Other customers do not use the same piece of hardware.

Tenancy type is captured from machine profile

When you use MCS to create a catalog to provision machines in AWS, the tenancy type is captured from the machine profile.

  • Shared hardware: This setting is suitable for most deployments. Multiple customers share pieces of hardware even though they do not interact with each other. Using shared hardware is the least expensive option for running your Amazon EC2 instances.
  • Dedicated instance: This setting is more suitable for deployments with specific security or compliance requirements. With a dedicated instance, you still enjoy the benefits of having a host separate from other AWS customers but you do not pay for the entire host. You do not need to worry about the capacity of the host but you are charged at a higher rate for the instances. Additionally, Dedicated Instances provide limited support for Bring Your Own License (BYOL).

Create a catalog

A prepared image and a machine profile is required for creating catalogs of Amazon WorkSpaces Core Managed Instances. You can use an AWS VM Instance or AWS Launch Template version as the machine profile input.

Note:

Currently, creation of catalogs of both persistent and non-persistent VMs (CleanOnBoot property is True or False) is supported.

Before creating a catalog of Amazon WorkSpaces Core Managed Instances, you need to finish creating:

  1. A connection to Amazon WorkSpaces Core Managed Instances. See Connection to Amazon WorkSpaces Core Managed Instances
  2. A prepared image.

You can create a catalog using:

Create a catalog using Studio

Create a machine catalog from the Images node

Use the Create catalog option in the Images node to create a catalog using the image version.

Alternatively, you can select the version when creating a catalog in the Machine Catalogs node, linking to the prepared image option in the catalog creation workflow. See Create a machine catalog from the Machine Catalogs node.

To create an MCS machine catalog from the Images node, do the following:

  1. Select an image version and click Create catalog. Click Next on the Introduction page.
  2. On the Machine Management and Image pages, the settings are pre-selected based on the selected image version. On the Image page, enter a note for the selected prepared image.
  3. Complete the settings on the following pages.
  4. On the Summary page, check the details of the machine catalog. Enter a name and description for the machine catalog. Click Finish.
  5. Go to the Machine Catalogs node to see the created machine catalog.

Create a machine catalog from the Machine Catalogs node

To create an MCS machine catalog from the Machine Catalogs node, do the following:

  1. Click Machine Catalogs on the left navigation pane.
  2. Click Create Machine Catalog. The Machine Catalog Setup page appears.
  3. On the Machine Type page, select a machine type for the catalog, for example, Multi-session OS.

  4. On the Machine Management page, select the following settings:

    1. Select Machines that are power managed (for example, virtual machines or blade PCs).
    2. Select Citrix provisioning technology. Then, select Citrix Machine Creation Services™.
    3. In the Resources field, select the resources (Availability Zone or Local Zone) that you configured while creating the host connection and click Next.
  5. On the Desktop experience page, select either random or static desktop that you want users to have when they log in. If a static desktop is selected, further specify whether you want to save changes that the user makes on the local disk (persistent or non-persistent).

  6. On the Image page, click Select an image to select a prepared image for the machine catalog. Select the prepared version that you created. Click the image version name. To view more details about the selected image version, click the version number, which is underlined. Click Done.

    The machine profile associated with the prepared image appears and its hardware properties (for example, instance type, tenancy type, network mappings, security groups, volume properties) are used to create machines in the catalogs. To change the machine profile source to another VM or launch template version click the edit button.

  7. On the Virtual Machines page:

    1. Enter the number of VMs for the catalog.
    2. The default machine specification is displayed, which is based on the machine profile. To change it, select the edit icon and select a machine specification.
  8. On the NICs page, select the NICs (or ENIs) for the VMs.

  9. On the Machine Identities page, configure the machine identity type for the machines in the catalog:

    1. To configure domain-joined machines (on-premises Active Directory or Microsoft Entra hybrid joined), select the domain and create new AD accounts for the VMs to be created in this machine catalog. The provisioned VMs are joined to the domain selected. To provision non-domain joined machines, select the non-domain join option.
    2. Specify the account naming scheme for the new accounts to be created for the VMs.
  10. On the Domain credentials page, click Enter credentials to provide the credentials for the selected domain. Enter admin-level username and password when prompted. You can also use a service account if you have domain credentials already saved previously by following our product docs.
  11. Click through the remaining pages until the Summary page. Enter a name for the machine catalog and select Finish to create the machine catalog.

Limitations on creating a machine catalog in an AWS local zone

  • Certain local zones only support certain hardware configurations (for example, Perth local zone does not support GP3 volumes, only GP2).
  • Since only gp2 is universally supported across all local zones, and not all support gp3, ID disk creation defaults to using gp2 volume type.
  • You must select a machine profile with hardware specifications that are supported in the desired local zone.
  • Prepared image AMIs snapshots and ID disk snapshots defaults to being placed in the region, rather than the local zone (due to AWS limitations regarding visibility into EBS snapshot support in local zones).
  • Only local zones supporting full EC2 and EBS services are supported zones.

Create a catalog using PowerShell

Create a catalog using a prepared image version spec and machine profile

  • Create an MCS non-persistent machine catalog from the prepared image version spec using the New-ProvScheme command. For example,

     New-ProvScheme -ProvisioningSchemeName <string> -ImageVersionSpecUid <Guid> -HostingUnitUid <Guid> -IdentityPoolUid <Guid> [-CleanOnBoot $true] [-MachineProfile <string>] [-ProvisioningSchemeType “MCS”]
 <!--NeedCopy-->

  • Create an MCS persistent machine catalog from the prepared image version spec using the New-ProvScheme command. For example,

     New-ProvScheme -ProvisioningSchemeName <string> -ImageVersionSpecUid <Guid> -HostingUnitUid <Guid> -IdentityPoolUid <Guid> [-CleanOnBoot $false] [-MachineProfile <string>] [-ProvisioningSchemeType “MCS”] 
 <!--NeedCopy-->

Example of the complete set of Powershell commands to create a catalog:

$Catalog = New-BrokerCatalog  -AllocationType "Random"  -IsRemotePC $False  -MinimumFunctionalLevel "L7_20" -Name "wsccatalog" -PersistUserChanges "Discard" -ProvisioningType "MCS" -Scope @() -SessionSupport "MultiSession"

$IdentityPool = New-AcctIdentityPool  -AllowUnicode  -Domain "domainname" -IdentityPoolName "wsccatalog" -IdentityType "ActiveDirectory"  -NamingScheme "aws##" -NamingSchemeType "Numeric" -Scope @()

$PreparedImageVersionSpec = Get-ProvImageVersionSpec -ImageDefinitionName image1 -ImageVersionNumber 1 -Filter "PreparationType -eq 'Mcs'"

$Task = New-ProvScheme -ProvisioningSchemeName wsccatalog -ImageVersionSpecUid $PreparedImageVersionSpec.ImageVersionSpecUid -HostingUnitName wsc -IdentityPoolName wsccatalog -CleanOnBoot -Scope @() -SecurityGroup @() -MachineProfile 'XdHyp:\HostingUnits\cvad-test-scalestress\us-east-1a.availabilityzone\machine-profile-instance i (i-0xxxxxxxx).vm' -RunAsynchronously

Get-ProvTask -TaskId $Task.TaskId
$ProvScheme = Get-ProvScheme -ProvisioningSchemeName wsccatalog

Set-BrokerCatalog -Name $Catalog.Name -ProvisioningSchemeId $ProvScheme.ProvisioningSchemeUid
<!--NeedCopy-->

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

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

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" `
-ImageVersionSpecUid ‘24dfb047-e867-527g-896c-25664xxxxx1t’ ` 
-CleanOnBoot `
-MachineProfile "XDHyp:\HostingUnits\xxxx-ue1a\machineprofiletest (lt-01xxxxx).launchtemplate\lt-01xxxxx (1).launchtemplateversion"
<!--NeedCopy-->

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

Update the machine profile source

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

Encrypt OS and ID disks

You can create a 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 (ID).

  • 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 prepared image that is encrypted (for example, an AMI created from an instance or snapshot that contains an 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 prepared 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:

  • Prepared image (created using image management from master image that has encrypted disk)
  • Machine profile

Considerations while using machine profile input are:

  • The KMS key of the machine profile input takes precedence over the prepared image’s KMS key.
  • If no machine profile input is provided, then the KMS key of the prepared 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 prepared image template (AMI) and the 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 the prepared image is unencrypted, then disks of catalog VMs are not encrypted.
  • When the prepared 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 the Set-ProvScheme PowerShell command to have:

  • A machine profile input with a volume containing a new KMS key.
  • A prepared image created from the master image with encrypted AMI using image management.

Important considerations:

  • The volumes of new VMs added to the catalog are encrypted with the new KMS key.
  • To update the 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 prepared image AMI to an unencrypted prepared image AMI.

Enable NitroTPM and UEFI secure boot for VM instances

When creating a catalog, you can now select a prepared 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 prepared image from the master image. See Create a prepared image for Amazon WorkSpaces Core Managed Instances.
  5. Create a machine catalog by selecting the prepared image with NitroTPM and UEFI secure boot enabled in Citrix 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

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 the AWS EC2 console, you cannot see the 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.

Filter VM instances using PowerShell

An AWS VM 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 VM 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-->

Where to go next

More information

Create catalogs using prepared images in Amazon WorkSpaces Core Managed Instances
March 30, 2026
Contributed by: 
C
March 30, 2026
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.