Developer Documentation
Image portability service

Workflows for using Image Portability Service to migrate an image between platforms

April 22, 2024
Contributed by: 
C

The Image Portability Service workflow is divided into the following phases:

  • Export phase - Exports an image from its source platform in a portable format.
  • Upload phase - Uploads the exported image into the appropriate object on the destination platform.
  • Prepare phase - Prepares an image that is uploaded to a target platform for running on that platform.
  • Publish phase - Publishes the prepared image to be ready for streaming by Citrix Provisioning (PVS).

Depending on your environment, you can perform any of the preceding tasks one or more times to migrate your image to all of the desired platforms.

In each phase of the Image Portability Service workflow, use the Image APIs, Job APIs, or Credentials APIs to streamline the management of images between an on-premises Resource Location, and one in a public cloud.

Export

One of the challenges in migrating an image between platforms is exporting the image from its source platform in a portable format. The Image Portability Service manages the task of exporting the disk image on the source platform directly. The image is exported into a canonical format VHD(X) that is understood by the other steps of Image Portability on all supported platforms.

The Image Portability Service currently supports the export of the following:

  • Azure managed disks from Azure Cloud to a Server Message Block (SMB) fileshare
  • AWS EC2 EBS volumes from AWS to a SMB fileshare
  • Google Cloud Platform managed images from Google Cloud Platform to a SMB fileshare
  • VMDK disks from VMware vSphere to a SMB fileshare
  • Nutanix disks from Nutanix Acropolis Hypervisor (AHV) to a SMB fileshare
  • Virtual disks from XenServer to a SMB fileshare

To export an image, send a POST request to the Image Portability Service images/$export endpoint. For more information, see Export an image section.

You can use Image Portability Service PowerShell examples to automate the export image process. For more information, see Export PowerShell example section.

Upload

Uploading the exported image to the destination platform is not an operation managed by the Image Portability Service. Before preparing the image in the target platform, you must upload the exported image into the appropriate object on the destination platform using your preferred mechanism.

If the target platform is Azure, you must create an Azure Managed disk from the exported VHD(X).

If the target platform is Google Cloud you must create a Google Cloud image from the exported VHD(X). Typically this is done by first uploading the exported VHD(X) to a bucket and then importing the bucket to an image.

If the target platform is AWS you must create an Elastic Block Storage (EBS) snapshot from the exported VHD(X). This can be done using one of the following:

Migrated images always use Unified Extensible Firmware Interface (UEFI) as the boot scheme, so it is important for you to set the appropriate flags on the created disks. (HyperVGeneration=”V2” on Azure, guest-os-features=”UEFI_COMPATIBLE” on Google Cloud).

You can use Image Portability Service PowerShell examples to automate the upload image process. For more information, see Upload PowerShell example section.

Prepare

In this phase an image which has been uploaded to a target platform is prepared for running on that platform.

Preparation involves removing any components of the source hypervisor environment, adding any new components required by the target platform, and configuration of any Citrix components installed in the image to function on the target platform.

The Image Portability Service currently supports preparation of following images:

  • Nutanix disks on Nutanix Acropolis Hypervisor (AHV)
  • AWS EBS snapshots
  • Azure managed disks and snapshots
  • Google Cloud images
  • Vsphere VMDKs
  • Xen virtual disks

Preparation of an image is started by sending a POST request to the Image Portability Service images/$prepare endpoint. For more information, see Prepare an image section.

You can use Image Portability Service PowerShell examples to automate the prepare image process. For more information, see Prepare PowerShell example section.

Publish

In this phase, the prepared image is published and ready to be streamed with Citrix Provisioning (PVS). (If you are using Machine Creation Services (MCS) to provision your machine catalog, you do not need to run the “Publish” stage.)

The Image Portability Service currently supports publication of images for PVS on the following platforms:

  • Azure
  • GCP
  • vSphere versions 7.x and 8.0
  • XenServer version 8.2

Publication of an image is started by sending a POST request to the Image Portability Service images/$publish endpoint. For more information, see Publish an image section.

You can use Image Portability Service PowerShell examples to automate the publish image process. For more information, see Publish PowerShell example section.

Image Portability Service APIs

Images APIs

Export an image

A POST request to the images/$export endpoint is used to start an asynchronous job which exports a specified image. This endpoint requires authentication and a JSON request body specifying parameters such as the image to be exported and to where it is to be exported.

On success, the response will include a Location header containing a path which can be used to monitor the status of the job or cancel it using the Job Management endpoints.

The export job creates a Compositing Engine VM (CE), attaches the image being exported to this CE, and instructs the CE to export the attached image to the destination SMB fileshare. When exporting from VMware vSphere, the CE is created in your vSphere environment. When exporting from Nutanix AHV, the CE is created in your AHV environment. When exporting from XenServer the CE is created in your XenServer environment. When exporting from Azure, the CE is created in your Azure subscription. When exporting from AWS, the CE is created in your AWS account. The request body specifies details about the configuration of the CE including the network it is to be attached to.

Note that the network the CE is attached to must provide connectivity between the CE and the destination SMB fileshare, and between the CE and all Connector Appliances in the Resource Location.

The export job requires credentials for creating the CE VM and for writing to the SMB fileshare. These credentials must be provided in the request body in the form of Credential Wallet references. For background on the Credential Wallet, see the Image Portability documentation and for the credential management APIs, see the Credential APIs section.

For example to start the export of an image from Azure to an SMB share you would make the following request:

POST https://api-us.cloud.com/ips/images/$export
<!--NeedCopy-->

with a request body like this

{
  "platform": "Azure",
  "platformCredentialId": "ips-azure-spn",
  "subscriptionId": "ecaecd6d-3c8a-4aef-82c5-37bcd2128272",
  "resourceGroup": "ips-rg",
  "virtualNetworkResourceGroupName": "ips-vnet-rg",
  "virtualNetworkName": "ips-vnet",
  "virtualNetworkSubnetName": "ips",
  "targetDiskResourceGroupName": "ips-disk-rg",
  "targetDiskName": "win10-gold.vhd",
  "resourceLocationId": "25b561b8-06b0-45bf-83b4-86ac84598443",
  "outputStorageLocation": {
    "type": "SMB",
    "credentialId": "ips-smb",
    "host": "ips-disks.file.core.windows.net",
    "sharePath": "publish"
  },
  "outputImageFilename": "win10-gold-export"
}
<!--NeedCopy-->

For descriptions of all the fields in the export request body and for further examples, see Image Management.

Prepare an image

A POST request to the images/$prepare endpoint is used to start an asynchronous job which prepares a specified image. This endpoint requires authentication and a JSON request body specifying parameters such as the image to be prepared.

On success, the response will include a Location header containing a path which can be used to monitor the status of the job or cancel it using the Job Management endpoints.

The prepare job creates a Compositing Engine VM (CE), attaches the image being prepared to this CE and instructs the CE to prepare the attached image. The request body specifies details about the configuration of the CE including the network it is to be attached to.

The network the CE is attached to must provide connectivity between the CE and all Connector Appliances in the Resource Location.

The prepare job requires credentials for creating the CE VM. These credentials must be provided in the request body in the form of Credential Wallet references. For background on the Credential Wallet, see the Image Portability documentation and for the credential management APIs, see the Credential APIs section.

For example, to start the preparation of an image for Azure, you can make the following request:

POST https://api-us.cloud.com/ips/images/$prepare
<!--NeedCopy-->

with a request body like this

{
  "platform": "Azure",
  "platformCredentialId": "ips-azure-spn",
  "subscriptionId": "ecaecd6d-3c8a-4aef-82c5-37bcd2128272",
  "resourceGroup": "ips-rg",
  "virtualNetworkResourceGroupName": "ips-vnet-rg",
  "virtualNetworkName": "ips-vnet",
  "virtualNetworkSubnetName": "ips",
  "resourceLocationId": "25b561b8-06b0-45bf-83b4-86ac84598443",
  "targetDiskResourceGroupName": "ips-disk-rg",
  "targetDiskName": "win10-gold.vhd"
}
<!--NeedCopy-->

For descriptions of all the fields in the prepare request body and for further examples, see Image Management.

Publish an image

A POST request to the images/$publish endpoint is used to start an asynchronous job which publishes a specified image. This endpoint requires authentication and a JSON request body specifying parameters such as the image to be published and to where it is to be published.

On success, the response will include a Location header containing a path which can be used to monitor the status of the job or cancel it using the Job Management endpoints.

The publish job creates a Compositing Engine VM (CE), attaches the image being published to this CE, and instructs the CE to publish the attached image to the destination SMB fileshare. When publishing from Azure, the CE is created in your Azure subscription. The request body specifies details about the configuration of the CE including the network it is to be attached to.

Note that the network the CE is attached to must provide connectivity between the CE and the destination SMB fileshare, and between the CE and all Connector Appliances in the Resource Location.

The publish job requires credentials for creating the CE VM and for writing to the SMB fileshare. These credentials must be provided in the request body in the form of Credential Wallet references. For background on the Credential Wallet, see the Image Portability documentation and for the credential management APIs, see the Credential APIs section.

For example to start the publication of an image from Azure to an SMB share you would make the following request:

POST https://api-us.cloud.com/ips/images/$publish
<!--NeedCopy-->

with a request body like this

{
  "platform": "Azure",
  "platformCredentialId": "ips-azure-spn",
  "subscriptionId": "ecaecd6d-3c8a-4aef-82c5-37bcd2128272",
  "resourceGroup": "ips-rg",
  "virtualNetworkResourceGroupName": "ips-vnet-rg",
  "virtualNetworkName": "ips-vnet",
  "virtualNetworkSubnetName": "ips",
  "targetDiskResourceGroupName": "ips-disk-rg",
  "targetDiskName": "win10-gold.vhd",
  "resourceLocationId": "25b561b8-06b0-45bf-83b4-86ac84598443",
  "outputStorageLocation": {
    "type": "SMB",
    "credentialId": "ips-smb",
    "host": "ips-disks.file.core.windows.net",
    "sharePath": "publish"
  },
  "outputImageFilename": "win10-gold-export"
}
<!--NeedCopy-->

For descriptions of all the fields in the publish request body and for further examples, see Image Management.

Special Case: PrepareAndPublishImage

PrepareAndPublish is an optimized combination of the prepare and publish operations into a single call. By combining the operations, they can be performed in a single compositing engine instance and reduce the cumulative operation time by a few minutes. Since this is a combined operation, errors can be more challenging to resolve than when running the prepare and publish operations sparately. For this reason, users are encouraged to develop their migration automation using the individual operations first, and then switch to PrepareAndPublish after they are happy with the set of parameters being used for the independent operations.

In order to run a PrepareAndPublish operation, a POST request to the images/$prepareAndPublish is used to start an asynchronous job which both prepares and publishes the specified image. This endpoint requires authentication and a JSON request body specifying all of the parameters normally provided to both the prepare AND publish operations above.

For example to start the combined preparation of an Azure managed disk, and publish the resulting image to and Azure SMB share for use by Citrix Provisioning (PVS) you would make the following request:

POST https://api-us.cloud.com/ips/images/$prepareAndPublishImage
<!--NeedCopy-->

with a request body like this

{
  "platform": "Azure",
  "platformCredentialId": "ips-azure-spn",
  "subscriptionId": "ecaecd6d-3c8a-4aef-82c5-37bcd2128272",
  "resourceGroup": "ips-rg",
  "virtualNetworkResourceGroupName": "ips-vnet-rg",
  "virtualNetworkName": "ips-vnet",
  "virtualNetworkSubnetName": "ips",
  "resourceLocationId": "25b561b8-06b0-45bf-83b4-86ac84598443",
  "targetDiskResourceGroupName": "ips-disk-rg",
  "targetDiskName": "win10-gold.vhd"
  "outputStorageLocation": {
    "type": "SMB",
    "credentialId": "ips-smb",
    "host": "ips-disks.file.core.windows.net",
    "sharePath": "publish"
  },
  "outputImageFilename": "win10-gold-export"
}
<!--NeedCopy-->

Disk Integrity Checking

The IPS workflow has the capability to verify that the disk exported at the beginning of the workflow is the same disk that was uploaded and prepared. This is done by computing the MD5 hash of the disk before it is exported, computing the hash of the disk before it is prepared, and verifying that they are the same. Integrity checking is not on by default because it may increase job runtime by up to 50%.

To enable integrity checking, add the following to the body of your export request:

  "hashDisk": true
<!--NeedCopy-->

When the export job is complete, the job status will contain an artifacts section. Part of the artifacts will be the MD5 hash of the exported disk:

"md5Hash": "23a396b3438cd1b16749c6635dd6c9b2"
<!--NeedCopy-->

After you upload the disk, you can verify the disk hash as part of the prepare job by adding the following to the prepare job parameters:

  "md5Hash": "23a396b3438cd1b16749c6635dd6c9b2"
<!--NeedCopy-->

If the computed hash of the target disk does not match the hash supplied with the prepare request, the prepare job will fail and the job failure error will include:

Expected hash [23a396b3438cd1b16749c6635dd6c9b2] does not match provided disk
<!--NeedCopy-->
Resources
Image portability service OpenAPI Specification
Copy Download
Workflows for using Image Portability Service to migrate an image between platforms
April 22, 2024
Contributed by: 
C
April 22, 2024
Contributed by: 
C

In this article

Resources
Image portability service OpenAPI Specification
Copy Download
Site feedback | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.