Product documentation
Citrix DaaS™
View PDF

Create a prepared image machine catalog in AWS EC2

December 3, 2025
Contributed by: 
C

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

  • Studio
  • PowerShell commands

The key steps to create an MCS machine catalog using the prepared image are:

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

Create an image definition and initial image version

Use 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) V1 and V2 are both supported.
  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, check 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

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.

Use 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 aws -MasterImagePath "XDHyp:\HostingUnits\aws\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\aws\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 aws-CustomProperties $CustomProperties
 
$imageVersion = New-ProvImageVersion -ImageDefinitionName image1 -Description "version 1"
 
$SourceImageVersionSpec = Add-ProvImageVersionSpec -ImageVersionUid $imageVersion.ImageVersionUid `
    -HostingUnitUid $hostingunit.HostingUnitUid `
    -MasterImagePath "XDHyp:\HostingUnits\aws\win10-2411-ami (ami-00123456789abcdef).template”
 
New-ProvImageVersionSpec -MachineProfile 'XDHyp:\HostingUnits\aws\w2022-2411 (lt-00123456789abcdef).launchtemplate\lt-00123456789abcdef (1).launchtemplateversion' -SourceImageVersionSpecUid $SourceImageVersionSpec.ImageVersionSpecUid
Add-ProvImageVersionSpecHostingUnit -ImageVersionSpecUid 00000000-0000-0000-0000-00000000000-HostingUnitName aws
$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

You can now share a single prepared image across different availability zones, tied to different hosting units, within the same AWS region for your AWS EC2. This allows you to use one prepared image to create and update MCS machine catalogs in various availability zones.

You can maintain a single prepared image and use it to create and update machine catalogs across multiple availability zones 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.

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 or us-east-1c within the same us-east-1 AWS 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 deployment: If your environment has multiple hosting units under the same AWS region and AWS account, you can efficiently share prepared images between these hosting units.

Limitations

  • Region-specific sharing: You can only share prepared images across availability zones within the same AWS Region. You can’t share across different AWS regions or 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 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 AWS EC2 environment.
  • You must configure multiple hosting units (each can be tied to different availability zones) within the same AWS Region and under the same AWS account.
  • Configure the IAM permission as detailed in the IAM permissions section to ensure sharing across same AWS account.

IAM permissions

To get the account ID for the current connection and ensure sharing across the same AWS account, your AWS account must include the following IAM permissions:

{  
   `"Effect": "Allow",`  
    `"Action": "iam:GetAccountSummary",`  
    `"Resource": "*"`  
}
<!--NeedCopy-->

Configure using PowerShell

You can share prepared images across availability zones tied to different hosting units using only PowerShell commands currently.

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 where you want to make the prepared image available. This is the name of the hosting unit you configured for that specific availability zone.

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

Create a machine catalog

Use 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) 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 on-premises Active Directory or Microsoft Entra hybrid joined for the machines in the catalog by selecting the domain and creating new AD accounts for the VMs to be created in this machine catalog. The provisioned VMs are joined to the domain selected. Specify the account naming scheme for the new AD accounts to be created for the VMs. Click Next.
  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.

Use 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 "awscatalog" -PersistUserChanges "Discard" -ProvisioningType "MCS" -Scope @() -SessionSupport "MultiSession"

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

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

$Task = New-ProvScheme -ProvisioningSchemeName awscatalog -ImageVersionSpecUid $PreparedImageVersionSpec.ImageVersionSpecUid -HostingUnitName aws -IdentityPoolName awscatalog -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 awscatalog

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

Where to go next

More information

Create a prepared image machine catalog in AWS EC2
December 3, 2025
Contributed by: 
C
December 3, 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.