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

Image management

August 11, 2025
Contributed by: 
C

Introduction

The MCS catalog creation or update process has two phases:

  • Mastering: a source image is converted into a published image
  • Cloning: new VMs are created from the published image

With the image management functionality, MCS separates the mastering phase from the overall provisioning workflow.

You can prepare various MCS image versions (Prepared Image) from a single source image and use it across multiple different MCS machine catalogs. You can also share prepared image versions across hosting units within host connections of the same connection type. This implementation significantly reduces the storage and time costs, and simplifies the VM deployment and image update process.

The benefits of using this image management functionality are:

  • Generate prepared images in advance without creating a catalog.
  • Reuse prepared images in multiple scenarios, such as creating and updating a catalog.
  • Significantly reduce catalog creation or update time.
  • Share prepared image versions across hosting units within host connections of the same connection type. (only for Azure and VMware)

Note:

  • This feature is currently applicable to Azure, Azure, Red Hat OpenShift, and VMware virtualization environments.
  • You can create an MCS machine catalog without using prepared images. In that case, you cannot get the benefits of the feature.

Use cases

Some of the use cases of image management functionality are:

  • Version management: Image versions allow you to:

    • manage different iterations or updates to a particular image.
    • maintain multiple versions of an image for different purposes.

  • Logical grouping: You can create multiple image definitions to:

    • logically group image versions based on various criteria such as project, department, or application and desktop type.
    • manage images more efficiently within an organization.

  • Image sharing: You can share prepared image versions across hosting units within host connections of the same connection type to:

    • ensure consistency and uniformity of images across different hosting units.

What is a prepared image?

With the image management functionality, MCS decouples the mastering phase from the overall catalog creation or update workflow and breaks down the process into two stages:

  1. Create prepared images from a single source image.
  2. Use the prepared image to create or update an MCS machine catalog.

You can create the prepared images in advance. You can use a single prepared image to create or update multiple MCS provisioned machine catalogs.

Understand how a prepared image is used across multiple MCS machine catalogs when you use the Web Studio from the image:

Prepared image overview

Image definition: Image definitions are a logical grouping of versions of an image. The image definition holds information about:

  • why the image was created
  • what OS it is for
  • other information about using the image.

A catalog isn’t created from an image definition, but from the image versions that are created based on the image definition.

Image version: Image versions manage versionings for the image definition. An image definition can have multiple image versions. Use the image versions as prepared images to create or update a catalog. You can share image versions across hosting units in both Azure and VMware environments, whether the hosting units are in the same hosting connection or not.

Alternatively, if you want to use PowerShell commands to create a provisioning scheme to create or update a catalog, then you must create a prepared image version spec based on the master image version spec as needed for your environment. You can also share image version specs across hosting units in both Azure and VMware environments, whether the hosting units are in the same hosting connection or not.

Requirement

  • For Windows master images, only VDA images version 2311 or later are supported. The MCS/IO component must be explicitly selected and installed. Enabling or disabling the MCS I/O configuration must be determined during machine catalog creation or updates, as it is not enabled by default.s

Limitations

Currently, the feature does not support the following:

  • Multiple NIC in Azure
  • Persistent data disk feature
  • Hibernation for multi-session
  • Image type change

  • While sharing prepared image version across hosting unit in Azure, the following sharing methods are not allowed:

    • Share Directly
    • Share to public community gallery
  • Currently, Azure confidential VM is not supported for image management.

Image lifecycle management using the Web Studio

Lifecycle of the image when you use the Web Studio is:

  1. Create a prepared image: Create an image definition and its initial image version.
  2. Create image versions from the initial image version.
  3. If needed, share an image version with a hosting unit in your virtualization environment.
  4. Use an image version as a prepared image to create catalogs.
  5. Update a machine catalog with a different prepared image.
  6. Manage the image definitions and versions: Edit the name and description of image versions, and description of an image definition.
  7. Delete an image version.
  8. Delete an image definition.

Alternatively, you can also manage images using PowerShell. See Image lifecycle management using PowerShell.

Image lifecycle management using PowerShell

If you want to use PowerShell commands to create a provisioning scheme, then you must create a prepared image version spec based on the master image version spec as needed for your environment.

Master image version spec: A master image version spec is a specific image added or created under an image version. You can add an existing image in the hypervisor as a master image version spec or create a prepared image version spec based on the master image version spec as needed for your environment. The prepared image version spec can be used for multiple provisioning schemes.

You can also share image version specs across hosting units in both Azure and VMware environments, whether they are in the same hosting connection or not. In Azure, the sharing is achieved using the disk sharing capability of Azure Compute Gallery (ACG).

Lifecycle of an image when using PowerShell commands is:

  1. Create an image:

    1. Create an image definition.
    2. Add a new configuration for Image Definition in specified Hosting Connection.
    3. Create an image version.
    4. Add a master image version spec.
    5. Create a prepared image version spec.
  2. If needed, share an image version spec with another hosting unit in your virtualization environment, whether in the same hosting connection or not.

  3. Create an MCS machine catalog using a prepared image version spec:

    1. Create a broker catalog.
    2. Create an identity pool.
    3. Create a provisioning scheme with the parameter of prepared image version spec Uid using the New-ProvScheme command.
    4. Link the broker catalog with the provisioning scheme.
  4. Create VMs in the MCS machine catalog.
  5. Change the prepared image version spec of a provisioning scheme using Set-ProvScheme command.
  6. Manage the image definitions and versions: Edit the image versions and image definitions.
  7. Delete an MCS machine catalog: The deletion order is: machine catalog > shared prepared image version spec (if image sharing) > prepared image version spec > master image version spec > image version > configuration for image definition in the specified hosting connection > image definition. Before deleting the image version spec, ensure that the prepared image version spec is not associated with any MCS machine catalog.

Understand the Images node

Use the Images node to create and manage MCS-prepared images. Its main view is divided into four parts:

  • Without prepared image being shared across host unit

    image-node-main-view

  • With prepared image being shared across host unit:

    image-node-main-view-image-sharing

Label Part Description
A Image definitions Lists the previously created image definitions.
B Image versions Displays image versions of the selected image definition.
C



Details



  • The Details tab displays detailed information about the selected image definition or version such as Master Image, Resource, Hypervisor, name of the image definition, OS type, and session type.
  • The Image Scheme tab displays information about the template used for preparing images such as hard disk, machine size, license type, disk encryption set, machine profile, and so on.
  • The Provisioning Schemes tab displays the provisioning scheme name used for creating the catalog.
  • The Troubleshoot tab provides the error status of the selected image version.
  • In case of image sharing: The Resources tab provides the status of image version share.
D Action bar Lists the actions that you can take on image definitions and versions such as Create Image Version, Edit Description, Manage Image Share(in case of prepared image sharing), Delete Image Version, and Create Catalog.

Share prepared images across Azure subscriptions or tenants

To share a prepared image across subscriptions or tenants on the Azure platform, follow this example:

  • Service principal: SPN 1
  • Subscription: Subscription 1
  • Tenant: Tenant 1

You want to share this image with:

  • Service principal: SPN 2
  • Subscription: Subscription 2
  • Tenant: Tenant 2 (can be the same as Tenant 1)

To successfully share and use the image, you must grant SPN 2 the following permissions in Subscription 1—at the gallery, resource group, or subscription scope:

  • Microsoft.Resources/subscriptions/read
  • Microsoft.Compute/galleries/images/read

  • Microsoft.Compute/galleries/images/versions/read

    Note:

    Any service principal that has any permission on a subscription or resource automatically inherits the Microsoft.Resources/subscriptions/read permission.

Alternatively, assign the Compute Gallery Image Reader built-in role to SPN 2.

For step-by-step guidance, see this Microsoft article.

Where to go next

Create prepared image machine catalogs - Create a prepared image machine catalog in Azure - Create a prepared image machine catalog in VMware - Create a prepared image machine catalog in Red Hat OpenShift

Image management
August 11, 2025
Contributed by: 
C
August 11, 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.