Capturing and exporting a virtual machine (VM)

You can capture and export an AIX or IBM i VM instance by using the Power Virtual Server user interface or CLI. A VM is captured as a volume backed image. The image is stored in new volumes on the storage providers. An image can be exported to an IBM Cloud Object Storage (Cloud Object Storage) bucket. When an image is exported, the volumes of the image are copied and packaged in an Open Virtualization Appliance (OVA) file. The OVA file is compressed by using gzip before it gets uploaded to the IBM Cloud Object Storage bucket.

When you capture and export a VM, you can choose the image catalog, Cloud Object Storage, or both as destinations. The image catalog is on the IBM Power storage area network (SAN). IBM Cloud Object Storage is encrypted and dispersed across multiple geographic locations, and accessed over HTTP by using a REST API. This service uses the distributed storage technologies that are provided by the IBM Cloud Object Storage System (formerly Cleversafe). You can always export your image in your image catalog to Cloud Object Storage at a later point. You can also deploy the captured image to create a clone of the VM by using a different network configuration.

The IBM® Power® Virtual Server Job feature tracks long-running asynchronous operations like VM capture, image export, and image import across multiple workspaces in your cloud account.

As part of this Job feature, new version of API and CLI enhancements are introduced for VM capture and image export operations. To view the new APIs, see the following:

API for VM capture - Capture a PVM instance and create a deployable image (version 2).
API for image export - Add image export job to the jobs queue (version 2).

CLI enhancements include changes to the existing ibmcloud pi instance-capture command and a new ibmcloud pi jobs command.

The new VM capture, image export, and image import features are restricted to one operation at a time per Power Virtual Server workspace. If one of these operations is submitted successfully, then another new operation (VM Capture, Image Export, and Image Import) cannot be submitted until the previous operation is complete.

You can use the Power Virtual Server legacy REST APIs for VM Capture, Image Export, and Image Import until 1 October 2022. You must plan to transition to the new IBM® Power Systems™ Virtual Server REST APIs or CLI commands before the earlier APIs are withdrawn from service.

You are charged different rates based on whether you export to the image catalog or COS.

Before you capture an IBM i VM, ensure that any buffer I/O memory is flushed (written) to the disk by running the following command:

CHGASPACT OPTION(*FRCWRT)

Using the Power Virtual Server user interface to capture and export a VM

Click the Capture and export icon in your Virtual server instances view. The icon is to the right of the trash icon.
Choose the volumes that you want to capture and export.
Select whether you want to export the volume backed image to the image catalog, COS, or both.
Give your captured image a Name.
(Optional) If you decide to export to COS, you are presented with more options:
1. Select the Region.
2. Provide your Access and Secret keys.
3. Select your Bucket name and optional folders.
Click Capture and export.
If the capture and export is successful, you are presented with a confirmation message.

If you select large volumes, the export process can take a significantly long period of time.
Find your newly exported image by completing either one of the following tasks:
- If you chose to capture and export your volume backed image to COS, go to your COS bucket.
- If you chose to capture and export your volume backed image to the image catalog, go to Boot images.
(Optional) If you'd like to export your volume backed image from your image catalog to COS, select it and click the Capture and export icon.

Using the CLI to capture and export a VM

To learn more about using the command-line interface to capture and export a VM, see IBM Power Virtual Servers CLI Reference and IBM COS CLI.

To capture an AIX or IBM i VM, use the ibmcloud pi instance-capture command. You can export it to your image catalog, COS, or both.

ibmcloud pi instance-capture INSTANCE_ID --destination DEST --name NAME [--volumes "VOLUME1 VOLUME2"] [--access-key KEY] [--secret-key KEY] [--region REGION] [--image-path TYPE]

Find your newly exported image by completing either one of the following tasks:
- To see your newly exported image in the image catalog, use the ibmcloud pi image-list-catalog command:
```
ibmcloud pi image-list-catalog [--long] [--json]
```
- To see your newly exported image in COS, use the ibmcloud cos list-objects command:
```
ibmcloud cos list-objects --bucket BUCKET_NAME [--delimiter DELIMITER] [--encoding-type METHOD] [--prefix PREFIX] [--starting-token TOKEN] [--page-size SIZE] [--max-items NUMBER] [--region REGION] [--json]
```