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.

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.

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

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

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

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, 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
}
}Copy

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

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

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

• ZSTD compression API response sample:

  {
      "message": "The provided QCOW2 has an unsupported compression type",
      "type": "invalid_request_error"
  }Copy

• Backing files API response sample:

  {
      "message": "The provided QCOW2 file has a backing chain",
      "type": "invalid_request_error"
  }Copy