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.

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.

*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 2203 or later streaming to vSphere 6.7 or 7.0

• Citrix Virtual Apps and Desktops VDA version 1912 CU5, 1912 CU6, 2203, 2206, or 2209

• 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 resource, 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 resource. 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 resource.

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 project, 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.

Amazon Web Services required permissions and configuration

In order to perform image portability service workflows with an Amazon Web Services (AWS) account, the respective Identity and Access Management (IAM) user must have the correct permissions.

For the detailed list, see AWS required permissions.

Set up the Image Portability Service

To set up the Image Portability Service you:

• Deploy connector appliances
• Prepare a machine for PowerShell
• Add credentials to Credential Wallet

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:

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:

  • Has the latest version of PowerShell.

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