Citrix DaaS

Migrate workloads to public cloud

Image Portability Service simplifies the management of images across platforms. This feature is useful for managing images between an on-premises Resource Location and one in a public cloud. The Citrix Virtual Apps and Desktops REST APIs can be used to automate the administration of resources within a Citrix Virtual Apps and Desktops site.

The Image Portability workflow begins when you use Citrix Cloud to start the migration of an image from your on-premises location to your public cloud subscription. After preparing your image, Image Portability Service helps you transfer the image to your public cloud subscription and prepare it to run. Finally, Citrix Provisioning or Machine Creation Services provisions the image in your public cloud subscription.

Components

Image Portability Service components include:

  • Citrix Cloud services
  • Citrix Credential Wallet
  • Citrix Connector Appliance
  • Compositing Engine VM
  • PowerShell Example Scripts

Citrix Cloud services

The Citrix Cloud Services API is a REST API service that interacts with the Image Portability Service. Using the REST API service, you can create and monitor Image Portability jobs. For example, you make an API call to start an Image Portability job, such as to export a disk, and then make calls to get the status of the job.

Citrix Credentials Wallet

The Citrix Credentials Wallet service securely manages system credentials, allowing the Image Portability Service to interact with your assets. For example, when exporting a disk from vSphere to an SMB share, the Image Portability Service requires credentials to open a connection to the SMB share to write the disk. If the credentials are stored in the Credential Wallet, then the Image Portability Service can retrieve and use those credentials.

This service gives you the ability to fully manage your credentials. The Cloud Services API acts as an access point, giving you the ability to create, update, and delete credentials.

Compositing Engine

The Compositing Engine is the workhorse of the Image Portability Service. The Compositing Engine (CE) is a single VM created at the start of an Image Portability export or prepare job. These VMs are created in the same environment where the job is taking place. For example, when exporting a disk from vSphere, the CE is created on the vSphere server. Likewise, when running a prepare job in Azure or Google Cloud, the CE is created in Azure or Google, respectively. The CE mounts your disk to itself, and then does the necessary manipulations to the disk. Upon completion of the prepare or export job, the CE VM and all of its components are deleted.

Connector Appliance

The Connector Appliance, running provider software to manage IPS resources, runs in your environment (both on-premises and in your Azure or Google Cloud subscription) and acts as a controller for individual jobs. It receives job instructions from the cloud service, and creates and manages the Compositing Engine VMs. The Connector Appliance VM acts as a single, secure point of communication between the Cloud Services and your environments. Deploy one or more Connector Appliances in each of your Resource Locations (on-premises, Azure, or Google Cloud). A Connector Appliance is deployed to each Resource Location for security. By co-locating the Connector Appliance and the Compositing Engine, the deployment’s security posture increases greatly, as all components and communications are kept within your Resource Location.

PowerShell modules

We provide a collection of PowerShell modules for use within scripts as a starting point to develop your own custom automation. The supplied modules are supported as is, but you can modify them if necessary for your deployment.

The PowerShell automation uses supplied configuration parameters to compose a REST call to the Citrix Cloud API service to start the job and then provide you with periodic updates as the job progresses.

If you want to develop your own automation solution, you can make calls to the cloud service directly using your preferred programming language. See the API portal for detailed information about configuring and using the Image Portability Service REST endpoints and PowerShell modules.

Workflows

The Image Portability Service uses a multi-phase workflow to prepare a master catalog image from an on-premises resource location for your public cloud subscription. The service exports the image from the on-premises hypervisor platform and you upload it to your public cloud subscription (our provided PowerShell upload utility can help automate this). Then, Image Portability prepares the image to be compatible with your public cloud platform. Finally, the image is published and ready to be deployed as a new machine catalog within your cloud resource location.

Image Portability Workflow

These high-level workflows are based on the image’s source and target provisioning configuration (Machine Creation or Citrix Provisioning). The chosen workflow determines which Image Portability Job Steps are required.

Refer to the following table to understand which jobs are required for each of the supported IPS workflows.

Workflow (Source to Target) Export Upload Prepare Publish
MCS to MCS Y Y Y N
PVS to MCS* N Y Y N
PVS to PVS on Azure* N Y Y Y
MCS to PVS on Azure Y Y Y Y

*Assumes you have the original image as a Citrix Provisioning vDisk and do not need to export it directly out of the source platform hypervisor.

Requirements

To get started with Image Portability, you must meet the following requirements.

A Citrix Machine Catalog image

IPS requires using images that have one of the following tested configurations:

  • Windows Server 2016, 2019, or 2022

  • Windows 10 or Windows 11

  • Provisioned using Machine Creation Services or Citrix Provisioning

  • Deployed with an on-premises hosting connection to one of the following:
    • VMware vSphere 6.7 or 7.0 (for MCS version 1912 or later)
    • Citrix Provisioning 2106 or later streaming to vSphere 6.7 or 7.0
  • Citrix Virtual Apps and Desktops VDA version 1912, or later

  • Remote Desktop Services enabled for console access in Azure

A Citrix Connector Appliance

You need a Citrix Connector Appliance installed and configured in each Resource Location where you plan to use Image Portability. For example, if you use image portability to move an image from vSphere to both Azure and Google Cloud, you need at least three Citrix Connector Appliances:

  • One or more appliances located on-premises to interact with your vSphere deployment.
  • One or more appliances in your Azure subscription.
  • One or more appliances in your Google Cloud subscription.

See Deploy Connector Appliances for detailed instructions.

An SMB (Windows) file share

You need a Windows SMB file share for temporary storage of data during export jobs hosted in the on-premises Resource Location where you’re using the Image Portability Service. Make sure that the available free space on the share is at least twice the configured size of your image’s file system.

A machine for running PowerShell scripts

Make sure your machine running the PowerShell scripts has the following:

  • PowerShell version 5.1.

  • A fast network connection to the SMB file share. It can be the same machine that is hosting the file share.

  • A fast network connection to the public cloud platforms where you plan to use the Image Portability feature, for example MS Azure or Google Cloud.

    See the section Prepare a machine for PowerShell for details about how to download and configure the Image Portability modules from the PowerShell Gallery.

Your Citrix Cloud Customer ID

Make sure you have a valid Citrix DaaS subscription.

To continue, you need access to Citrix DaaS (formerly Citrix Virtual Apps and Desktops service). If you don’t have access, contact your Citrix representative.

Refer to the API Getting Started documentation for instructions to create and configure an API client to use with image portability.

Azure required permissions and configuration

For the Image Portability Service to do actions in your Azure subscription, you need to grant permissions to certain Azure capabilities to the Azure service principal used by the Image Portability Service. For the detailed list, see Microsoft Azure required permissions.

You can assign the Contributor role to the service principal in the associated subscription. Or, to assign the minimum permissions required, you can create a custom role with the permissions listed, then assign it to the service principal scoped to the correct subscription.

Note:

We recommend using a subscription, or subscriptions, dedicated solely to the Image Portability Service and other Citrix operations. Scope all role assignments to these subscriptions.

Refer to the Azure documentation for configuring security roles for your Azure service principal and for creating custom roles.

Google Cloud required permissions and configuration

For the Image Portability Service to perform actions in your Google Cloud subscription, you grant permissions to certain capabilities to the Google Cloud service principal used by the Image Portability Service.

For the detailed list, see Google Cloud required permissions.

You can assign these permissions using the following roles:

  • Cloud Build Editor
  • Compute Admin
  • Storage Admin
  • Service Account User

See the Google Cloud documentation for more information on configuring service account permissions.

Set up the Image Portability Service

To set up the Image Portability Service you:

Deploy Connector Appliances

Image Portability requires Citrix Connector Appliances to create Image Portability jobs. Connector Appliances help secure interactions with your on-premises and public cloud environments. The Connector Appliances communicate back to the Image Portability Service to report on job status and overall service health.

To deploy and configure Connector Appliance in your environment, follow the steps in Connector Appliance for Cloud Services.

Note the required hardware configuration and network port access for the appliance when planning your deployment.

When your appliance is deployed and registered, the components needed to enable Image Portability are automatically installed.

Prepare a machine for PowerShell

To assist you in getting up and running with Image Portability, we have created PowerShell modules you can customize and use with the service.

The following sections describe how to prepare a machine to run the PowerShell scripts. These scripts are just a few examples. Modify or enhance them to suit your needs.

Note:

  • We do not support any custom scripts that are used with the Image Portability Service.
  • After the initial installation, use Update-Module to update the PowerShell module.

PowerShell requirements

To use the PowerShell scripts, you need the following:

  • A Windows machine to run the PowerShell scripts that drive image portability jobs. The machine:

    • Is running PowerShell version 5.1.

    • Has a 10-Gbs or better network connection to the on-premises SMB file share and a fast connection to your public cloud (Microsoft Azure or Google Cloud, for example).

    • Can be the same machine hosting the file share.

    • Is a machine running Windows 10, Windows Server 2019, or Windows Server 2022, with the latest Microsoft patches.

    • Can connect to the Microsoft PowerShell Gallery to download the required PowerShell libraries.

Depending on your version of Windows, you may need to disable TLS 1.0/1.1 support. Refer to Microsoft PowerShell Gallery TLS support documentation for more information.

By default, PowerShell does not automatically authenticate through a proxy server. Make sure you’ve configured your PowerShell session to use your proxy server, per Microsoft, and your proxy vendor best practices.

If you see errors when running the PowerShell scripts relating to a missing or old version of PowerShellGet, you need to install the latest version as follows:

```
Install-Module -Name PowerShellGet -Force -Scope CurrentUser -AllowClobber
<!--NeedCopy--> ```

Install libraries and modules

Image Portability Service draws on libraries from the Microsoft PowerShell Gallery to drive portability operations.

Important:

After the initial installation, use Update-Module to install new versions.

  1. Run the following PowerShell command to download the latest modules:

    Install-Module -Name "Citrix.Workloads.Portability","Citrix.Image.Uploader" -Scope CurrentUser
    <!--NeedCopy-->
    
    • To change the PATH Environment Variable:

      Press Y and Enter to accept.

    • To install the NuGet provider:

      Press Y and Enter to accept.

    • If informed about an untrusted repository:

      Press A (Yes to All) and Enter to continue.

  2. Confirm that all necessary modules were downloaded by running the command:

    Get-InstalledModule -Name Citrix.*
    <!--NeedCopy-->
    

    This command returns output similar to the following:

    Name Repository Description
    Citrix.Image.Uploader PSGallery Commands to Upload a VHD(x) to an Azure Storage Account or GCP and Get information about a VHD(x)
    Citrix.Workloads.Portability PSGallery Standalone Cmdlet for the Image Job of Citrix Image Portability Service

Update modules to the latest version

Run the following command to update the scripts to the latest version.

Update-Module -Name "Citrix.Workloads.Portability","Citrix.Image.Uploader" -Force
<!--NeedCopy-->

Install the Citrix Virtual Apps and Desktops Remote PowerShell SDK

Image Portability Service requires the Citrix Virtual Apps and Desktops Remote PowerShell SDK to create and manage portability jobs within Citrix Cloud.

Download and install the Remote PowerShell SDK on your machine.

Install platform-specific third-party components

VMware

If you are creating Image Portability jobs that communicate with your VMware environment, run the following command to install the required VMware PowerShell modules.

Install-Module -Name VMWare.PowerCLI -Scope CurrentUser -AllowClobber -Force -SkipPublisherCheck
<!--NeedCopy-->
Azure

If you’re creating Image Portability jobs in Azure, download and install the Azure command-line utilities, then run these commands to install the required Azure PowerShell modules:

Install-Module -Name Az.Accounts -Scope CurrentUser -AllowClobber -Force
Install-Module -Name Az.Compute -Scope CurrentUser -AllowClobber -Force
<!--NeedCopy-->
Google Cloud

If you’re creating Image Portability jobs in Google Cloud, download and install the Google Cloud SDK on your machine.

Uninstall scripts and modules

Run the following commands to uninstall modules used by the Image Portability software.

Note:

Third-party scripts and components aren’t automatically removed when uninstalling IPS modules.

To uninstall modules:

Get-InstalledModule -Name "Citrix.Workloads.Portability","Citrix.Images.Uploader" | Uninstall-Module
<!--NeedCopy-->

Add credentials to Credential Wallet

For end-to-end automation scenarios, you can configure the Image Portability Service to authenticate non-interactively with Citrix Cloud, your public cloud, and on-premises resources. Also, the Image Portability Service uses credentials stored in the Citrix Credential Wallet anytime our APIs are directly authenticating with your on-premises and public cloud resources. Setting credentials as described in this section is a required step for running export, prepare, and publish jobs.

When running jobs, the Image Portability Service requires access to resources you can control. For example, for the Image Portability Service to export a disk from a vSphere server to an SMB share, the service needs login access to both systems. To secure this account information, the Image Portability Service uses the Citrix Credential Wallet service. This service stores your credentials in the wallet with a user defined name. When you want to run a job, provide the name of the credential to use. Also, these credentials can be updated or deleted from the wallet at any time.

Credentials are often stored for these platforms:

  • Google Cloud
  • Microsoft Azure
  • SMB Share
  • VMware vSphere

To manage credentials, refer to the Image Portability Service APIs and Credentials Management section of the Developer API Portal.

Use the Image Portability Service

Preparing images in your on-premises Resource Locations to your public cloud subscription requires creating Image Portability jobs within Citrix Cloud. You can create a job to make direct API calls to the service within your script or program, or by using the example PowerShell modules we have developed to automate API calls. Refer to the Image Portability Service Developer API Portal for information about using REST APIs and PowerShell modules to create IPS jobs.

Publish to Machine Creation Services

The Image Portability Service is used with Machine Creation Services in Azure or Google Cloud. You can combine the PowerShell and REST solutions described in this guide with Citrix DaaS SDKs to create a seamless and automated end-to-end workflow for creating a machine catalog based on the prepared on-premises image, and provisioning the image using Machine Creation Services.

Refer to the Developer API Portal for more information about Citrix DaaS REST APIs.

Refer to the Citrix DaaS documentation for information about using the Remote PowerShell SDK

Deployment for APS and EU Customers

By default, the IPS PowerShell Module connects to the Image Portability Service deployed in the US Region. Customers in APS or the EU can use a configuration parameter when creating jobs to direct IPS to their specific region. Use the following format for this configuration parameter:

Deployment = '<your-deployment>'
<!--NeedCopy-->

The valid deployment values depending on your region are:

Region Deployment Value
APS api.aps.layering.cloud.com
EU api.eu.layering.cloud.com

Specify the Deployment configuration parameter to the IPS job anytime you are:

  • Adding credentials to the Credential Wallet
  • Creating an export job
  • Creating a prepare job
  • Creating a publish job

Automate VDA configuration

When preparing a Citrix-managed image that originated on-premises, you can reconfigure the VDA within the image to support the target environment for which the image is being prepared. Image Portability Service can apply VDA configuration changes on the fly during the preparation phase of the workflow. There are three configuration parameters that define how the VDA operates in the migrated image: InstallMisa, InstallPvs, and XdReconfigure. Define these parameters when creating IPS jobs as follows:

InstallMisa = 'true'
<!--NeedCopy-->

Configuring InstallMisa to true enables the Image Portability Service to install any missing VDA components which would be required to provision the image using MCS.

Configuring InstallMisa to true also requires configuring CloudProvisioningType to Mcs.

InstallPvs = 'version of Pvs e.g. 7.31.0'
<!--NeedCopy-->

Configure InstallPvs to set it to the version of PVS with which you are deploying the image. When InstallPvs is set, the Image Portability Service automatically installs the specified version of the PVS target device software in the image during prepare jobs.

Configuring InstallPvs also requires CloudProvisioningType be configured to Pvs.

For both InstallMisa and InstallPvs, note the following:

  • Only recent LTSR and CR releases of the VDA support this feature.

  • If the necessary components are already present for the installed VDA, no changes are made, even if the parameters are configured.

  • For supported versions of the VDA, Image Portability installs the appropriate version of the required components, even if the necessary VDA components aren’t present.

  • For unsupported versions of the VDA, reconfiguration fails and a message is logged if the necessary VDA components aren’t present. The preparation job completes even if the VDA reconfiguration does not.

XdReconfigure requires one of the following values: controllers or site_guid. Here are example configuration parameters using each value:

Using controllers:

XdReconfigure = @(
    [pscustomobject]@{
        ParameterName = 'controllers'
        ParameterValue = 'comma-separated-list-of-your-cloud-connectors-fqdns'
    }
)
<!--NeedCopy-->

where the ParameterValue is the list of FQDNs of the new DDCs where you want to point the VDA. Multiple DDCs can be specified in comma-separated format.

Using site_guid:

XdReconfigure = @(
    [pscustomobject]@{
        ParameterName = 'site_guid'
        ParameterValue = 'active-directory-site-guid'
    }
)
<!--NeedCopy-->

XdReconfigure also accepts values that are supported when running the VDA command-line installer with the /reconfigure install switch, for example, XenDesktopVdaSetup.exe /reconfigure). Some examples of these values include wem_agent_port, wem_cached_data_sync_port, wem_cloud_connectors, or wem_server. For a complete list of VDA reconfigure command-line options, refer to the Citrix DaaS VDA documentation.

Reference

This section details technical reference information, based on your needs.

Permissions required by the Image Portability Services

This section details the permissions required by the Image Portability Service on each of the supported on-premises and Cloud platforms.

VMware vCenter required permissions

The following vCenter permissions are necessary to run the IPS export disk job in a VMware environment. These permissions can be found under Roles in the Access Control section of the vCenter administration panel.

-  Cryptographic operations
    -  Direct Access

-  Datastore
    -  Allocate space
    -  Browse datastore
    -  Low level file operations
    -  Remove file

-  Folder
    -  Create folder
    -  Delete folder

-  Network
    -  Assign network

-  Resource
    -  Assign virtual machine to resource pool

-  Virtual machine
    -  Change Configuration
        -  Add existing disk
        -  Add new disk
        -  Remove disk

    -  Edit Inventory
        -  Create from existing
        -  Create new
        -  Remove

    -  Interaction
        -  Power off
        -  Power on
<!--NeedCopy-->

Microsoft Azure required permissions

Image Portability requires your Azure service account to have the following permissions:

Microsoft.Compute/disks/beginGetAccess/action
Microsoft.Compute/disks/read
Microsoft.Compute/disks/write
Microsoft.Compute/virtualMachines/extensions/delete
Microsoft.Compute/virtualMachines/extensions/read
Microsoft.Compute/virtualMachines/extensions/write
Microsoft.Compute/virtualMachines/read
Microsoft.Compute/virtualMachines/restart/action
Microsoft.Compute/virtualMachines/write
Microsoft.Network/networkInterfaces/join/action
Microsoft.Network/networkInterfaces/read
Microsoft.Network/networkInterfaces/write
Microsoft.Network/publicIPAddresses/join/action
Microsoft.Network/publicIPAddresses/read
Microsoft.Network/publicIPAddresses/write
Microsoft.Network/virtualNetworks/read
Microsoft.Network/virtualNetworks/subnets/join/action
Microsoft.Network/virtualNetworks/write
Microsoft.Resources/deployments/operationStatuses/read
Microsoft.Resources/deployments/read
Microsoft.Resources/deployments/write
Microsoft.Resources/subscriptions/resourcegroups/delete
Microsoft.Resources/subscriptions/resourceGroups/write
Microsoft.Storage/storageAccounts/listKeys/action
Microsoft.Storage/storageAccounts/write
<!--NeedCopy-->

Google Cloud required permissions

Image Portability requires your Google Cloud service account to have the following permissions:

cloudbuild.builds.create
cloudbuild.builds.get
cloudbuild.builds.list
compute.disks.create
compute.disks.delete
compute.disks.get
compute.disks.list
compute.disks.setLabels
compute.disks.use
compute.globalOperations.get
compute.images.create
compute.images.delete
compute.images.get
compute.images.list
compute.images.setLabels
compute.images.useReadOnly
compute.instances.create
compute.instances.delete
compute.instances.get
compute.instances.setLabels
compute.instances.setMetadata
compute.instances.setServiceAccount
compute.instances.setTags
compute.instances.stop
compute.instances.updateDisplayDevice
compute.networks.get
compute.subnetworks.use
compute.subnetworks.useExternalIp
compute.zoneOperations.get
compute.zones.list
iam.serviceAccounts.actAs
iam.serviceAccounts.get
iam.serviceAccounts.list
resourcemanager.projects.get
storage.buckets.create
storage.buckets.delete
storage.buckets.get
storage.objects.create
storage.objects.delete
storage.objects.get
storage.objects.list
<!--NeedCopy-->
Migrate workloads to public cloud