Export or import image

Edit online

The image export or import APIs helps you to export or import images from a backup node that is 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 helps 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 the powervc-image command-line interface (CLI) command and vice-versa.

Export an image to a backup node without an 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
Resetting image backups to Error state
Force deleting an image backup
Get task progress of an image export
Get task progress of an image import

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`	To export an image from a backup node, with or without uploading it to the IBM Cloud Object Storage.
POST	`/v3/{project-id}/image-backups/import_image`	To import an image from a backup node, with or without downloading it from IBM Cloud Object Storage.

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

This operation exports an image to a backup node in PowerVC without uploading to Cloud Object Storage. This API takes the image ID, details of the Cloud Object Storage, and the details of the backup node hostname 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 the name of the exported image.
`description`	Body	String	Optional. The description of the image is 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 an image to Cloud Object Storage. Default option is True.
`compression`	Body	String	Optional. Whether to compress the volume files when you create the image OVA. Default option is True. You can set the compression value by using any of these options. True in which the `gzip` compression is used. Fast in which the `pigz` compression is used. False in which there is no compression.

Notes:

To successfully export an image without compression, set use_fast_compression = False in the cinder.conf file on the PVC controller and the backup node. Also, include "compression": "False" in the API request body.

The successful export operation of an image without compression also depends on the backup service --fast-compression configuration property. If --fast-compression configuration property is true, the export operation always uses compression. To disable the compression, you must also disable the --fast-compression property. To update the configuration property, enter the following CLI command:
```
powervc-config storage backup-service posix --backup-node <name_of_backup_node> --fast-compression False
```

Example of exporting an image to a backup node without upload to Cloud Object Storage:

{
"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”
    "compression": "Fast" 
    }
}

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 you export 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 Cloud Object Storage. This API takes the image ID, details of the Cloud Object Storage details, and the details of the backup node hostname 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 an upload to Cloud Object Storage
Name	Style	Type	Description
`name`	Body	String	Display the name of the exported image.
`description`	Body	String	Optional. The description of the image is exported.
`src_image_id`	Body	String	ID of the image to be exported
`cos-bucket`	Body	String	Cloud Object Storage 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 an image to Cloud Object Storage. Default option is True.

Example of exporting an image to a backup node with upload to Cloud Object Storage:

{
"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 an upload to Cloud Object Storage
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 you export an image to a backup node with upload to Cloud Object Storage:

{
    "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 Cloud Object Storage. This API takes the image ID, details of the Cloud Object Storage, and the details of the backup node hostname 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 the name of the imported image.
`description`	Body	String	Optional. The description of the image is 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 whether 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`, 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 Cloud Object Storage and imported. If the image backup ID is not provided, image backup is downloaded from the backup node to PowerVC without download from Cloud Object Storage.

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 you import 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 Cloud Object Storage. This API takes the image ID, details of the Cloud Object Storage, and the details of the backup node hostname 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 Cloud Object Storage
Name	Style	Type	Description
`name`	body	string	Display the name of the imported image.
`description`	body	string	Optional. The description of the image is imported.
`volume_type`	body	string	Optional. ID of the storage template.
`ova_name`	body	string	Name of the image OVA that is being imported. The .ova and .ova.gz formats are supported for the Image OVA.
`cos_bucket`	body	string	Name of the Cloud Object Storage bucket from where the image must be downloaded.
`backup_host`	body	string	Optional. Backup node hostname.

Example of importing an image with download from Cloud Object Storage 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 Cloud Object Storage
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 you import an image with download from Cloud Object Storage 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"
    }
}

Resetting image backups to Error state

If image backup is in creating_backup, extracting_ova, deleting, or uploading state, you can reset the status of the image backup to Error state. This API takes only the status:error parameter. However, if the image backup is in available, upload_failed, error, download_failed, or uploaded state, you cannot use this API.

Response code

Normal Response Code - HTTPAccepted (202)

Request parameters

Table 10. Parameters in the request for setting image backups to error state
Name	Style	Type	Description
`status`	Body	String	Specify the status as "error".

Example for setting image backups to error state:

PUT  https://<PowerVC-IP>:9000/v3/<tenant-id>/image-backups/<image-backup-id>/reset_status

Body:
          {
        "reset_status":
            {
                     "status": "error"
            }
      }

Get task progress of an image export

The Get task progress API is used to view the progress of the image export task.

Response code

Normal Response Code - OK (200)

Request parameters

Table 11. Parameters in the response for get task progress of an image export
Name	Style	Type	Description
`flow_details`	Body	Dictionary	Specifies the flow details of the ExportFlow task.
`progress`	Body	Integer	Specifies the status of the ExportFlow task.
`completed_tasks`	Body	Dictionary	Specifies the details of the task that is completed.
`pending_tasks`	Body	Dictionary	Specifies the details of the pending tasks, if any.
`task_results`	Body	Dictionary	Specifies the details of the final task results.

Example of Get progress output of an image export task:

GET     /v3/{tenant_id}/image-backups/get_progress?action=export&task_id={task_id}&backup_id={backup_id}


{
  "details": {
    "flow_details": {
      "ExportFlow": "SUCCESS"
    },
    "progress": 100,
    "completed_tasks": {
      "backup_vol_05962f4f-ebe6-4aa4-b9b6-fd7bd297d1ca_63": "SUCCESS",
      "temp_vol_05962f4f-ebe6-4aa4-b9b6-fd7bd297d1ca_63": "SUCCESS",
      "update_task": "SUCCESS",
      "delete_vol_05962f4f-ebe6-4aa4-b9b6-fd7bd297d1ca_63": "SUCCESS",
      "create_ova_63": "SUCCESS"
    },
    "pending_tasks": {},
    "task_results": {
      "backup_vol_05962f4f-ebe6-4aa4-b9b6-fd7bd297d1ca_63": {
        "backup_id": "fb9f0444-a4a6-4534-9472-3ad5c7a547d0",
        "volume_id": "05962f4f-ebe6-4aa4-b9b6-fd7bd297d1ca",
        "boot_index": 0,
        "size": 10,
        "backup_file_name": "temp_vol_059-c5b29121-da8f-4e_63",
        "container": "dummycoreos-36febdd1-98a5-4f_63/temp_vol_059-c5b29121-da8f-4e_63",
        "service_metadata": "volume_c5b29121-da8f-4e99-b0e3-958adb69081e_20221129062851_backup_fb9f0444-a4a6-4534-9472-3ad5c7a547d0"
      },
      "temp_vol_05962f4f-ebe6-4aa4-b9b6-fd7bd297d1ca_63": "c5b29121-da8f-4e99-b0e3-958adb69081e",
      "update_task": null,
      "delete_vol_05962f4f-ebe6-4aa4-b9b6-fd7bd297d1ca_63": null,
      "create_ova_63": null
    }
  }
}

Get task progress of an image import

The Get task progress API is used to view the progress of the image import task.

Response code

Normal Response Code - OK (200)

Request parameters

Table 12. Parameters in the response for get task progress of an image import
Name	Style	Type	Description
`flow_details`	Body	Dictionary	Specifies the flow details of the ImportFlow and PreImportFlow tasks.
`progress`	Body	Integer	Specifies the status of the ImportFlow and PreImportFlow tasks
`completed_tasks`	Body	Dictionary	Specifies the details of the task that is completed.
`pending_tasks`	Body	Dictionary	Specifies the details of the pending tasks, if any.
`task_results`	Body	Dictionary	Specifies the details of the final task results.

Example of Get progress output of an image import task:

GET   /v3/{tenant_id}/image-backups/get_progress?action=import&task_id={task_id}&backup_id={backup_id}


{
  "details": {
    "flow_details": {
      "ImportFlow": "SUCCESS",
      "PreImportFlow": "SUCCESS"
    },
    "progress": 100,
    "completed_tasks": {
      "restore_284524ae-cd70-49aa-adec-5864f53bbd82": "SUCCESS",
      "update_img_abh-ova-import": "SUCCESS",
      "create_image_abh-ova-import": "SUCCESS",
      "restored_5e384010-6f33-11ed-87e9-fa57a9c8c120_57": "SUCCESS",
      "create_map_restored_5e384010-6f33-11ed-87e9-fa57a9c8c120_57": "SUCCESS",
      "extract_ova_dummycoreos57.ova": "SUCCESS"
    },
    "pending_tasks": {},
    "task_results": {
      "restore_284524ae-cd70-49aa-adec-5864f53bbd82": null,
      "update_img_abh-ova-import": null,
      "create_image_abh-ova-import": "39d3eb1c-b47c-49ab-b62b-9706373fd49a",
      "restored_5e384010-6f33-11ed-87e9-fa57a9c8c120_57": "4a418051-3941-4d10-bf52-a0f0996114a8",
      "create_map_restored_5e384010-6f33-11ed-87e9-fa57a9c8c120_57": [
        {
          "boot_index": 0,
          "source_type": "volume",
          "delete_on_termination": "true",
          "destination_type": "volume",
          "device_type": "disk",
          "volume_id": "4a418051-3941-4d10-bf52-a0f0996114a8"
        }
      ],
      "extract_ova_dummycoreos57.ova": null
    }
  }
}

Force deleting an image backup

If the image backup is in transient states such as creating_backup, extracting_ova, deleting, or uploading, use this API to delete the image backups forcefully. The API takes only force=True as the option in the DELETE request. If you use the force=False option or use the API without the force option, the API does not allow deletion. If image backup is in available, upload_failed, error, download_failed, or uploaded state, this API deletes the image backup even if the force option is used.

Response code

Normal Response Code - HTTPAccepted (202)

Example to delete an image backup forcefully:

DELETE https://<PowerVC-IP>:9000/v3/<tenant-id>/image-backups/<image-backup-id>?force=true