Export or import image

Edit online

The image export or import APIs let you export or import images from a backup node registered in PowerVC. You can also choose whether you want to upload an image to the IBM® Cloud Object Storage along with export. Similarly, the import image API allows you to import an image to PowerVC from a backup node registered in PowerVC. You can also choose whether you want to download an image from IBM Cloud Object Storage and then import it.

Note: Backup node APIs do not support import or export operation for images that are imported or exported by using powervc-image CLI and vice-versa.

Export an image to a backup node without upload to Cloud Object Storage
Export an image to a backup node with upload to Cloud Object Storage
Import an image from a backup node when an image backup is available
Import an image with download from Cloud Object Storage when image backup is not available

Options for export or import image APIs

Table 1. Options for export or import image APIs
Method	URI	Description
POST	`/v3/{project-id}/image-backups/export_image`	Exports an image from a backup node (with or without upload to IBM COS).
POST	`/v3/{project-id}/image-backups/import_image`	Imports an image from a backup node (with or without download from IBM COS).

Export an image to a backup node without upload to Cloud Object Storage

This operation exports an image to a backup node in PowerVC without upload to COS. This API takes image ID, COS details, backup node hostname details in the request body as input and returns the image backup ID and the task URI in the response body.

Response code

Normal Response Code: OK (201)

Request parameters

Table 2. Parameters in the request for exporting an image to a backup node
Name	Style	Type	Description
`name`	body	string	Display name of the exported image.
`description`	body	string	Optional. Description of the image being exported.
`src_image_id`	body	string	ID of the image to be exported.
`backup_host`	body	string	Optional. Backup node hostname.
`upload_to_cos`	body	Boolean	Optional. Whether to upload image to COS. Default option is True.

Example of exporting an image to a backup node without upload to COS:

{
"image-backup": {
    "name": “export-to-backup-node”,
    "description": “export to backup node without upload to cos”,
    "src_image_id": “9c219888-1ab0-429e-9282-7cbc6957c839",
    "backup_host": “vm-xxx”,
    "upload_to_cos":  ”False”
    }
}

Response body

Table 3. Parameters in the response for exporting an image to a backup node
Name	Style	Type	Description
`backup_id`	body	integer	ID of the image backup.
`task_uri`	body	string	For long running export and import API operations, the link to the task URI is returned that can be used to monitor the progress of import or export image operations.

Example response when exporting an image:

{
    "image-backup": {
        "backup_id": 23,
        "task_uri": "https://9.x.x.x:9000/v3/40a58846608e4e908c43b547d4dfb58c/image-backups/get_progress?action=export&task_id=6f09caf1-0468-4101-9c4d-34d0b0690s89&backup_id=23"
    }
}

Export an image to a backup node with upload to Cloud Object Storage

This operation exports an image to a backup node in PowerVC with upload to COS. This API takes image ID, COS details, backup node hostname details in the request body as input and returns the image backup ID and the task URI in the response body.

Response code

Normal Response Code: OK (201)

Request parameters

Table 4. Parameters in the request for exporting an image to a backup node with upload to COS
Name	Style	Type	Description
`name`	body	string	Display name of the exported image.
`description`	body	string	Optional. Description of the image being exported.
`src_image_id`	body	string	ID of the image to be exported
`cos-bucket`	body	string	COS bucket name for uploading the image. If name is not provided, `cos-default` is selected.
`backup_host`	body	string	Optional. Backup node hostname.
`upload_to_cos`	body	Boolean	Optional. Whether to upload image to COS. Default option is True.

Example of exporting an image to a backup node with upload to COS:

{
"image-backup": {
    "name": “export-to-cos”,
    "description": “export to backup node with upload to cos”,
    "src_image_id": “9c219888-1ab0-429e-9282-7cbc6957c839",
    "cos_bucket": ”bucket-1”,
    "backup_host": “vm-xxx”,
    "upload_to_cos":  ”True”
    }
}

Response body

Table 5. Parameters in the response for exporting an image to a backup node with upload to COS
Name	Style	Type	Description
`backup_id`	body	integer	ID of the image backup.
`task_uri`	body	string	For long running export and import API operations, the link to the task URI is returned that can be used to monitor the progress of import or export image operations.

Example response when exporting an image to a backup node with upload to COS:

{
    "image-backup": {
        "backup_id": 23,
        "task_uri": "https://9.x.x.x:9000/v3/40a58846608e4e908c43b547d4dfb58c/image-backups/get_progress?action=import&task_id=6f09caf1-0468-4101-9c4d-34d0b0690s89&backup_id=23"
    }
}

Import an image from a backup node when an image backup is available

This operation imports an image to a backup node in PowerVC without download from COS. This API takes image ID, COS details, backup node hostname details in the request body as input and returns the image backup ID and the task URI in the response body.

Response code

Normal Response Code: OK (201)

Request parameters

Table 6. Parameters in the request for importing an image to a backup node
Name	Style	Type	Description
`name`	body	string	Display name of the imported image.
`description`	body	string	Optional. Description of the image being imported.
`volume_type`	body	string	Optional. ID of the storage template.
`image_backup_id`	body	string	ID of the image backup.
`backup_host`	body	string	Optional. Backup node hostname.
`import_from_raw_file`	body	Boolean	Optional. Indicate if it is a raw image import.
`os_type`	body	string	Optional. Operating system type for the raw image. Possible values are `aix`, `ibmi`, `rhel`, `coreos`, `sles`, or `ubuntu`.
`architecture`	body	string	Optional. Architecture corresponding to the raw image. Possible values are `ppc64` or `ppc64le`.

Example of importing an image from a backup node when an image backup is available:

{
"import-image": {
    "name": "Import-from-Backup-node",
    "description": "Importing an image from the backup node”,
    "image_backup_id": 32,
    "volume_type": "9c219888-1ab0-429e-9282-7cbc6957c839",
    "backup_host": "vm-xxx"
    }
}

Note: If the image backup ID given is an upload image backup, image backup is downloaded from COS and imported. If the image backup ID is not provided, image backup is downloaded from the backup node to PowerVC without download from COS.

Response body

Table 7. Parameters in the response for importing an image to a backup node
Name	Style	Type	Description
`backup_id`	body	integer	ID of the image backup.
`task_uri`	body	string	For long running export and import API operations, the link to the task URI is returned that can be used to monitor the progress of import or export image operations.

Example response when importing an image from a backup node when an image backup is available:

{
    "image-backup": {
        "backup_id": 23,
        "task_uri": "https://9.x.x.x:9000/v3/40a58846608e4e908c43b547d4dfb58c/image-backups/get_progress?action=export&task_id=6f09caf1-0468-4101-9c4d-34d0b0690s89&backup_id=23"
    }
}

Import an image with download from Cloud Object Storage when image backup is not available

This operation imports an image with download from COS. This API takes image ID, COS details, backup node hostname details in the request body as input and returns the image backup ID and the task URI in the response body.

Response code

Normal Response Code: OK (201)

Request parameters

Table 8. Parameters in the request for importing an image with download from COS
Name	Style	Type	Description
`name`	body	string	Display name of the imported image.
`description`	body	string	Optional. Description of the image being imported.
`volume_type`	body	string	Optional. ID of the storage template.
`ova_name`	body	string	Name of the image OVA that is being imported.
`cos_bucket`	body	string	Name of the COS bucket from where the image must be downloaded.
`backup_host`	body	string	Optional. Backup node hostname.

Example of importing an image with download from COS when image backup is not available:

{
    "import-image": {
        "name": "Import-from-Backup-node",
        "description": "Importing an image from the backup node”,
        "volume_type": "9c219888-1ab0-429e-9282-7cbc6957c839",
        "ova_name": "Export-Image-to-Backup_node_29.ova",
        "cos_bucket": "bucket-1",
        "backup_host": "vm-xxx"
    }
}

Response body

Table 9. Parameters in the response for importing an image with download from COS
Name	Style	Type	Description
`backup_id`	body	integer	ID of the image backup.
`task_uri`	body	string	For long running export and import API operations, the link to the task URI is returned that can be used to monitor the progress of import or export image operations.

Note: If the image OVA was uploaded from the same PowerVC management node and the status of the image backup is upload_failed or download_failed, you can provide the image_backup_id in the import request body instead of the cos_bucket and ova_name.

Example response when importing an image with download from COS when image backup is not available:

{
    "image-backup": {
        "backup_id": 32,
        "task_uri": "https://9.x.x.x:9000/v3/40a58846608e4e908c43b547d4dfb58c/image-backups/get_progress?action=import&task_id=4f09caf1-0468-4101-9c4d-34d0b0690faa&backup_id=32"
    }
}