Developer Documentation
Image portability service

Image Portability Service Automation for Citrix Provisioning (PVS)

March 28, 2024
Contributed by: 
C

Image Portability Service can be used to automate some common Citrix Provisioning (PVS) operations that cannot be performed while streaming.

Reverse Image

Reverse Imaging takes a VHD(X) from a Citrix Provisioning (PVS) store, and recreates the original platform image. This allows you to perform any upgrade tasks that you need to perform with PVS streaming disabled. You can then use the Image Portability Service Publish operation to return the image to the PVS environment.

Reverse Imaging is performed by sending a POST request to the Image Portability Service images/$reverseImage endpoint. For more information, see the Reverse Imaging section.

Convert to UEFI

Convert to UEFI takes a MBR/BIOS VHD(X) from a Citrix Provisioning (PVS) store and converts the disk format to GPT/EFI

Convert to UEFI is performed by sending a POST request to the Image Portability Service images/$convertToUefi endpoint. For more information, see the Convert to UEFI section.

Upgrade PVS

Upgrade PVS takes a VHD(X) from a Citrix Provisioning (PVS) store and upgrades the version of PVS on the image to the version specified in the job request.

Upgrade PVS is performed by sending a POST request to the Image Portability Service images/$upgradePvs endpoint. For more information, see the Upgrade PVS section.

PVS Images APIs

Reverse Imaging

(Reverse Imaging is currently only supported on vSphere)

A POST request to the images/$reverseImage endpoint is used to start an asynchronous job which returns a shared VHD(X) to native hypervisor format. 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 reverseImage job creates a Compositing Engine VM (CE), attaches a SMB shared VHD(X) to this CE, and instructs the CE to recreate a native hypervisor image on the specified target platform. The request body specifies details about the configuration of the CE including the network it is to be attached to. The reverseImage job also needs to know the size of the output disk, because the target disk must be created before the Compositing Engine can mount the source image. Care must be taken to ensure that the output disk size is greater than or equal to the virtual size of the source image. Note that the virtual size of the source image may be significantly larger than the size of the VHD(X) file.

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

The reverseImage job requires credentials to the destination hypervisor management endpoints for creating the CE VM and for reading from 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 from a SMB shared PVS store to a vSphere VMDK you would make the following request:

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

with a request body like this

{
  "platform": "vSphere",
  "platformCredentialId": "ips-vsphere-login",
  "resourceLocationId": "25b561b8-06b0-45bf-83b4-86ac84598443",
  "subscriptionId": "ecaecd6d-3c8a-4aef-82c5-37bcd2128272",
  "vCenterHost": "vcenter-8.megacorp.cust",
  "datacenter": "datacenter1",
  "datastore": "Datastore1",
  "network": "pvs-management",
  "cluster": "citrix",
  "outputDiskName": "[Datastore1] images/reversed-win10.vmdk",
  "outputSizeMb": "32768",
  "inputImageFormat": "VhdxDiskFormat",
  "inputImageFilename": "win10",
  "inputStorageLocation": {
    "type": "SMB",
    "credentialId": "pvs-smb",
    "host": "pvs-store.file.core.windows.net",
    "sharePath": "disks"
  }
}
<!--NeedCopy-->

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

Convert to UEFI

(Convert to UEFI is currently supported on vSphere, XenServer, Azure and GCP)

A POST request to the images/$convertToUefi endpoint is used to start an asynchronous job which returns a VHD(X) differencing disk in the same SMB share and folder as the original disk. This endpoint requires authentication and a JSON request body specifying parameters such as the image to be converted and to where the differencing disk will be output to.

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 convertToUefi job creates a Compositing Engine VM (CE), attaches a SMB shared VHD to this CE, and instructs the CE to create a differencing disk in the GPT/UEFI format. 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 source SMB fileshare, and between the CE and all Connector Appliances in the Resource Location.

The convertToUefi job requires credentials to the destination hypervisor management endpoints for creating the CE VM and for reading from and 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 a convertToUefi job you would make the following request:

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

with a request body like this

{
  "platform": "vSphere",
  "platformCredentialId": "ips-vsphere-login",
  "resourceLocationId": "25b561b8-06b0-45bf-83b4-86ac84598443",
  "vCenterHost": "vcenter-8.megacorp.cust",
  "datacenter": "datacenter1",
  "datastore": "Datastore1",
  "network": "pvs-management",
  "cluster": "citrix",
  "inputStorageLocation": {
    "type": "SMB",
    "credentialId": "pvs-smb",
    "host": "pvs-store.file.core.windows.net",
    "sharePath": "disks"
  },
  "inputImageFilename": "win10",
  "inputImageFormat": "VhdxDiskFormat",
  "outputImageFilename": "win10-converted"
}
<!--NeedCopy-->

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

Upgrade PVS

(Upgrade PVS is currently only supported on vSphere)

A POST request to the images/$upgradePvs endpoint is used to start an asynchronous job which returns a VHD(X) with PVS upgraded to the version of PVS specified in the job request. This endpoint requires authentication and a JSON request body specifying parameters such as the image to upgrade, and the PVS version to upgrade to.

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 upgradePvs job creates a Compositing Engine VM (CE), attaches a SMB shared VHD(X) to this CE, and instructs the CE to create a copy of the VHD(X) with PVS upgraded to the version specified in the job request. The request body specifies details about the configuration of the CE including the network it is to be attached to. Additionally, the upgradePvs job needs to know the size of the output disk, because the target disk must be created before the Compositing Engine can mount the source image. Care must be taken to ensure that the output disk size is greater than or equal to the virtual size of the source image. Note that the virtual size of the source image may be significantly larger than the size of the VHD(X) file.

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

The upgradePvs job requires credentials to the destination hypervisor management endpoints for creating the CE VM and for reading from and 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 an upgradePvs job you would make the following request:

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

with a request body like this

{
  "platform": "vSphere",
  "platformCredentialId": "ips-vsphere-login",
  "resourceLocationId": "25b561b8-06b0-45bf-83b4-86ac84598443",
  "subscriptionId": "ecaecd6d-3c8a-4aef-82c5-37bcd2128272",
  "vCenterHost": "vcenter-8.megacorp.cust",
  "datacenter": "datacenter1",
  "datastore": "Datastore1",
  "network": "pvs-management",
  "cluster": "citrix",
  "upgradeOptions": {
    "installPvs": "2311"
  },
  "inputStorageLocation": {
    "type": "SMB",
    "credentialId": "pvs-smb",
    "host": "pvs-store.file.core.windows.net",
    "sharePath": "disks"
  },
  "inputImageFilename": "win10",
  "inputImageFormat": "VhdxDiskFormat",
  "outputImageFilename": "win10-with-upgraded-pvs",
  "outputSizeMb": "71680"
}
<!--NeedCopy-->

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

Resources
Image portability service OpenAPI Specification
Copy Download
Image Portability Service Automation for Citrix Provisioning (PVS)
March 28, 2024
Contributed by: 
C
March 28, 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.