Using the snapshot import/export feature with the API

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.

Before you start

To complete the actions presented below, you must have:

• A Scaleway account logged into the console
• Owner status or IAM permissions allowing you to perform actions in the intended Organization
• An Instance with Block Storage volumes
• A valid API key
• A snapshot
• An Object Storage bucket

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 do not have one already, you can create it in the console.

2. Create a snapshot from a volume.

   To use this functionality, you must create a snapshot from the volume you want to export.

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 key pair (<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": "b_ssd", "project": "<scaleway_project_id>", "name": "my-imported-snapshot"}'

The following information is required to run the command above:

• The Availability Zone of the snapshot (here: fr-par-2)

• The secret key of your API key pair (<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 or b_ssd.)

• 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": "b_ssd",
    "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 fr-par-2 AZ:

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"
  }