HomeComputeInstancesAPI/CLI
Using the import/export feature (API)

Jump toUpdate content

Using the snapshot import/export feature with the API

Published on 25 July 2021

The snapshot transfer feature allows you to export or import Instances snapshots. Snapshots are created using the QCOW2 format and their data is stored in a Scaleway Object Storage Bucket. These images can then be used to create a copy of an Instance in a different AZ.

More information on the QCOW2 file format, and how to use it can be found in the QEMU documentation.

Tip:

This page shows you how to use the snapshot import/export feature with the Scaleway API. The import/export feature is also available in the console, CLI, and SDK.

Requirements:

Exporting snapshots

  1. Create a Scaleway Object Storage bucket. You need an S3 bucket to export your QCOW2 file into. Any bucket that belongs to the same project as the snapshot can be used. However, if you don’t have one already, you can create it in the console.

  2. Create a snapshot from a volume. You will need to create a snapshot from the volume you want to export to use this functionality. If you have not done so already, refer to the documentation for instructions on how to create a snapshot.

  3. Call the export snapshot API endpoint to initiate the snapshot export. For example, using curl:

    $ curl -X POST https://api.scaleway.com/instance/v1/zones/fr-par-1/snapshots/<snapshot_uuid>/export \
    -H "X-Auth-Token: <secret_key>" \
    -H "Content-Type: application/json" \
    --data '{"bucket": "my-bucket", "key": "my-exported-snapshot.qcow2"}'

    The following information is required to run the command above:

    • The Availability Zone of the snapshot (here: fr-par-1)
    • The secret key of your API keypair (<secret_key>)
    • The snapshot ID (<snapshot_uuid>)
    • The name of the Object Storage bucket to store the snapshot (which has to exist in the same Scaleway region as the snapshot)
    • A key (can be any acceptable key/object name for Scaleway S3 (suffixing qcow2 images with .qcow2))

    The API returns an output as in the following example:

    {
    "task": {
    "id": "<task_uuid>",
    "description": "export_snapshot",
    "status": "pending",
    "href_from": "/snapshots/<snapshot_uuid>/export",
    "href_result": "https://s3.fr-par.scw.cloud/my-bucket/my-exported-snapshot.qcow2",
    "started_at": "2022-07-25T15:23:49.278630+00:00",
    "terminated_at": null
    }
    }
    Important:

    Snapshots should have a volume size between one gigabyte (GB) and one terabyte (TB).

Importing snapshots

Any snapshot (a valid QCOW2 image) imported to a Scaleway Object Storage bucket can be imported into Instances in the same region as the snapshot. This allows you to create Instances in other Availability Zones within the same region, for example you can deploy Instances in fr-par-2 based on the snapshot exported from an Instance in fr-par-1.

Call the import snapshot API endpoint to initiate the snapshot import.

For example, using curl:

$ curl -X POST https://api.scaleway.com/instance/v1/zones/fr-par-2/snapshots/ \
-H "X-Auth-Token: <secret_key>" -H "Content-Type: application/json" \
--data '{"bucket": "my-bucket", "key": "my-exported-snapshot.qcow2", "volume_type": "unified", "project": "<scaleway_project_id>", "name": "my-imported-snapshot"}'

The follwing information is required to run the command above:

  • The Avilability Zone of the snapshot (here: fr-par-2)
  • The secret key of your API keypair (`<secret_key>)
  • The name of the Object Storage bucket holding the snapshot (which has to exist in the same Scaleway region as the snapshot)
  • The object name of the QCOW2 image
  • The snapshot’s volume type (It can be l_ssd, b_ssd or unified. Use unified if you want to be able to create both l_ssd and b_ssd volumes from this snapshot.)
  • A Scaleway project UUID
  • The name of the newly created snapshot (used to identify the snapshot in the Console)
  • Optional A size parameter. If missing, the size of the created snapshot is defaulted to the QCOW2’s volume size.

The API returns an output as in the following example:

{
"snapshot": {
"id": "<snapshot_uuid>",
"name": "my-imported-snapshot",
"volume_type": "unified",
"creation_date": "2022-07-25T15:27:48.654782+00:00",
"modification_date": "2022-07-25T15:27:48.654782+00:00",
"organization": "<scaleway_organization_id>",
"project": "<scaleway_project_id>",
"size": 10737418240,
"state": "importing",
"base_volume": null,
"tags": [],
"zone": "fr-par-2",
"error_details": null
},
"task": {
"id": "<task_uuid>",
"description": "import_snapshot",
"status": "pending",
"href_from": "/snapshots/",
"href_result": "snapshots/<snapshot_uuid>",
"started_at": "2022-07-25T15:27:48.797883+00:00",
"terminated_at": null
}
}

Once the snapshot has been imported, it becomes available in the list of snapshots in the AZ fr-par-2:

Tip:

The Instance snapshot will be created as soon as the API call returns, but the import action will take several minutes to complete. In the meantime, the snapshot will be in the importing state, before becoming available once the import is successful.

$ curl -X GET https://api.scaleway.com/instance/v1/zones/fr-par-2/snapshots/<snapshot_uuid> \
-H "X-Auth-Token: <secret_key>" | jq ".snapshot.state" "importing"

Import constraints and error handling

Currently, some features of the QCOW2 format are not handled; the import request will not accept images using these features.

These features are:

  • Encryption API response sample:
    {
    "message": "The provided QCOW2 file is encrypted",
    "type": "invalid_request_error"
    }
  • ZSTD compression API response sample:
    {
    "message": "The provided QCOW2 has an unsupported compression type",
    "type": "invalid_request_error"
    }
  • Backing files API response sample:
    {
    "message": "The provided QCOW2 file has a backing chain",
    "type": "invalid_request_error"
    }
Note:

The API might raise other errors if it cannot find the provided object, if the object is not a valid QCOW2 image, if the volume is bigger than one terabyte, etc.