Block Storage API

Introduction

Scaleway Block Storage provides network-attached storage that can be plugged in and out of cloud products such as Instances like a virtual hard-drive. Block Storage devices are independent from the local storage of Instances, and the fact that they are accessed over a network connection makes it easy to move them between Instances in the same Availability Zone.

Quickstart

1. Configure your environment variables.

   Note

   This is an optional step that seeks to simplify your usage of the Block Storage API. See Availability Zones below for help choosing an Availability Zone. You can find your Project ID in the Scaleway console.

   export SCW_SECRET_KEY="<API secret key>"
   export SCW_DEFAULT_ZONE="<Scaleway Availability Zone>"
   export SCW_PROJECT_ID="<Scaleway Project ID>"
   

   Important

   Make sure that the Availability Zone (AZ) is the same as the one of your Instance. Block volumes can only be attached to Instances in the same AZ.

2. Edit the POST request payload you will use to create your Block volume. Replace the parameters in the following example:

     '{
     "project_id": "d8e65f2b-cce9-40b7-80fc-6a2902db6826",
     "name": "my-volume",
     "perf_iops": "5000",
     "tags": ["donnerstag"],
     "from_empty": {
        "size": "30000000000"}
     }'
   

   Parameter	Description
   project_id	REQUIRED The ID of the Project you want to create your Block volume in. To find your Project ID you can list the projects or consult the Scaleway console.
   name	REQUIRED Name of the volume
   perf_iops	REQUIRED The maximum IO/s expected. This amount is a shared limit between write and read operations, it will be determined by your usage. You must specify either 5000, or 15000.
   tags	The list of tags ["tag1", "tag2", ...] that will be associated with the Database Instance. Tags can be appended to the query of the List Database Instances call to show results for only the Database Instances using a specific tag. You can also combine tags to list Database Instances that posess all the appended tags.
   from_empty	When you create a brand new volume, as opposed to creating a volume from a snapshot, you must specifiy its size.
   size	Volume size. The value should be expressed in bytes. For example 30GB is expressed as 30000000000

3. Create a Block volume by running the following command. Make sure you include the payload you edited in the previous step.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     "Content-Type: application/json" \
     https://api.scaleway.com/block/v1alpha1/zone/$SCW_DEFAULT_ZONE/volumes \
     -d '{
          "project_id": "'"$SCW_PROJECT_ID"'",
          "name": "my-volume",
          "perf_iops": "5000",
          "tags": ["donnerstag"],
          "from_empty": {
              "size": "30000000000"}
        }'
   

   An output similar to the following displays :

   '{
      "id": "e337a374-f19a-4b58-a45d-75076f75fbc5",
      "name": "my-volume",
      "type": "sbs_5k",
      "size": 30000000000,
      "project_id": "d8e65f2b-cce9-40b7-80fc-6a2902db6826",
      "created_at": "2023-09-28T15:48:59.105240Z",
      "updated_at": "2023-09-28T15:48:59.105240Z",
      "references": [],
      "parent_snapshot_id": None,
      "status": "creating",
      "tags": [],
      "specs": {"perf_iops": 5000, "class": "sbs"},
      "zone": "fr-par-1"
      }'
   

   Note

   Make sure to save the id of your volume, as it will be required in the next step.

4. Attach your volume to your Instance using the Instance API Update an Instance call.

   Note

   Make sure the Block volume is created and ready before attaching it to the Instance.

   Important

   Make sure you include all your Instance's existing volumes in the payload, as the update can only be done to all or none of the volumes.

   The payload should include a minimum of one key ("0") with a value equivalent to the setting parameters for the volume. Additional keys for additional volumes should increment by 1 each time. For example, the second volume is "1", the third "2", and so on.

   curl -X PATCH \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     "Content-Type: application/json" \
     https://api.scaleway.com/instance/v1/zone/$SCW_DEFAULT_ZONE/servers/$INSTANCE_ID \
     -d '{
         "volumes": {
            "0": {
               "boot": false,
               "id": "571c8a17-ba68-4c1d-b137-bbd5bc7af104",
               "volume_type": "System volume"
            }
            "1": {
               "boot": false,
               "id": "e337a374-f19a-4b58-a45d-75076f75fbc5",
               "volume_type": "sbs_volume"
            }
         }'
   

Your Block volume is ready to be used with your Instance.

Refer to the How to mount and use your Block volume documentation page to do so.

Going further

For further information and assitance for Scaleway Block Storage, check out the following resources:

• Basic Block Storage Documentation
• #block channel in the Scaleway Slack Community
• How to open a support ticket.

Volume Type

Volume

Snapshot