NavigationContentFooter

Scaleway 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.

Important

This page includes the API reference documentation for all Block Storage Low Latency offers. If you wish to use the Basic Block Storage offers, refer to the Instances API documentation page.

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"}
    }'
    ParameterDescription
    project_idREQUIRED 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.
    nameREQUIRED Name of the volume
    perf_iopsREQUIRED 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.
    tagsThe 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_emptyWhen you create a brand new volume, as opposed to creating a volume from a snapshot, you must specifiy its size.
    sizeVolume 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.

Requirements

To perform the following steps, you must first ensure that:

  • you have an account and are logged into the Scaleway console
  • you have created an API key and that the API key has sufficient IAM permissions to perform the actions described on this page.
  • you have installed curl
  • you have created an Instance.

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

Block Storage volume types are determined by their storage class and their IOPS. There are two storage classes available: bssd and sbs. The IOPS can be chosen for volumes of the sbs storage class

GET
/block/v1alpha1/zones/{zone}/volume-types

Volume

A Block Storage volume is a logical storage drive on a network-connected storage system. It is exposed to Instances as if it were a physical disk, and can be attached and detached like a hard drive. Several Block volumes can be attached to one Instance at a time

Block volumes can be snapshotted, mounted or unmounted

GET
/block/v1alpha1/zones/{zone}/volumes
POST
/block/v1alpha1/zones/{zone}/volumes
GET
/block/v1alpha1/zones/{zone}/volumes/{volume_id}
PATCH
/block/v1alpha1/zones/{zone}/volumes/{volume_id}
DELETE
/block/v1alpha1/zones/{zone}/volumes/{volume_id}

Snapshot

A Block Storage snapshot is a read-only picture of a Block volume, taken at a specific time You can then revert your data to the previous snapshot. You can also create a new read/write Block volume from a previous snapshot

GET
/block/v1alpha1/zones/{zone}/snapshots
POST
/block/v1alpha1/zones/{zone}/snapshots
GET
/block/v1alpha1/zones/{zone}/snapshots/{snapshot_id}
PATCH
/block/v1alpha1/zones/{zone}/snapshots/{snapshot_id}
DELETE
/block/v1alpha1/zones/{zone}/snapshots/{snapshot_id}
POST
/block/v1alpha1/zones/{zone}/snapshots/import-from-s3
Docs APIScaleway consoleDedibox consoleScaleway LearningScaleway.comPricingBlogCarreer
© 2023-2024 – Scaleway