Volume operations with Scaleway API/CLI

Reviewed on 27 November 2023 • Published on 25 May 2023

Created by Protocol Labs, InterPlanetary File System (IPFS) is a decentralized protocol used to store and share content.

Scaleway IPFS Pinning allows you to permanently store a copy of your data from the public IPFS network on a Scaleway-owned node, thus providing you with an added layer of performance in the region of your choice. That way, your data remains available and accessible, even when your local machine is offline.

With your content now available on both your local node and our resilient and reliable external nodes, you drastically minimize the risk of disruptions thanks to redundancy. You can also enhance your data storage efficiency by pinning your content to your Scaleway node, and then remove it from your local node.

In this page we show you how you can manage your volume operations via both the Scaleway Command Line Interface and Scaleway API.

Scaleway Command Line Interface overview

The Scaleway Command Line Interface (CLI) allows you to create and interact with your volumes and pins. You will be able to create volumes, manage them, add/delete content within them.

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
A valid API key
Downloaded and installed the Scaleway CLI

Configuring the CLI

Open a terminal and enter the following command, to configure the Scaleway CLI on your machine:

scw init

If you have already configured the CLI, you will see a message like the following:

Current config is located at /path/to/config.yaml
access_key: <YOUR ACCESS KEY>
secret_key: <YOUR SECRET KEY>
default_organization_id: <YOUR ORGANIZATION ID>
default_project_id: <YOUR PROJECT ID>
default_region: <YOUR DEFAULT REGION, eg fr-par>
default_zone: <YOUR DEFAULT ZONE, eg fr-par-1>
Do you want to override the current config? (Y/n):

Note

As the project is available on pl-waw, nl-ams and fr-par, you can set the region to pl-waw, nl-ams or fr-par.

Unless you want to change your configuration, you can type n and go directly to the Creating a Volume step of this tutorial.

If you have not yet configured the CLI, you will be guided through the configuration process via a series of questions:
```
Enter a valid secret-key or an email
```

Enter either the email address for your account (you will then be asked for your password), or your API secret key:

To improve this tool we rely on diagnostic and usage data.
Sending such data is optional and can be disabled at any time by running "scw config set send-telemetry=false".
Do you want to send usage statistics and diagnostics? (Y/n):

Type y or n and hit enter.

To fully enjoy Scaleway CLI we recommend you install autocomplete support in your shell.
Do you want to install autocomplete? (Y/n):

Type y or n and hit enter.

To enable autocomplete, scw needs to update your shell configuration.
What type of shell are you using (default: zsh):

Hit enter if the default shell type is already correct for you. Otherwise, enter your shell type and hit enter.

To enable autocomplete we need to append to /Users/yourusername/.zshrc the following lines:
# Scaleway CLI autocomplete initialization.
eval "$(scw autocomplete script shell=zsh)"
Do you want to proceed with these changes? (Y/n):

Type y or n and hit enter. This should complete the configuration process:

Initialization completed with success.

Creating a volume

This operation allows you to create a new volume. A volume serves as a storage area for a set of pins.

Type the following command to create your volume using the CLI.

  scw ipfs volume create name=my-volume

You should get a response like the following, providing details about your newly created volume.

  ID 11111111-1111-1111-1111-111111111111
  ProjectID 00000000-0000-0000-0000-000000000000
  Region fr-par
  CountPin 0
  CreatedAt now
  UpdatedAt now
  Name my-volume

Alternatively, you can also run the following API command. Make sure to replace the values with your own, using the API configuration table below.

  curl -X POST \
    -H "X-Auth-Token: $SECRET_KEY" \
    -H "Content-Type: application/json" \
    "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/volumes" \
    -d '{
      "project_id": "$PROJECT_ID",
      "name": "my-volume"
    }'

| Parameter | Description | | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | $SECRET_KEY | The secret part of your API key | | $REGION_ID | Create a volume in this given region. Possible values are fr-par, pl-waw and nl-ams. Default value is fr-par. | | $PROJECT_ID | ID of the Project you want to create your volume in. Your Project name can only contain alphanumeric characters, spaces, dots, and dashes. To find your Project ID, you can consult the Scaleway console | | name | Create a volume with this given name. |

Deleting a volume

This operation allows you to delete a given volume.

Important

Deleting a volume will also delete all of its associated pins. Once you do so, the volume and all of its pins will no longer be displayed in the console, nor available via the APIs.

Run the following command to delete your volume using the CLI. Just make sure to replace the volume-id value with your own.

scw ipfs volume delete volume-id=11111111-1111-1111-1111-111111111111

Note

If the operation is successful, no output will be returned.

Alternatively, you can also run the following API command. Just make sure to replace the example values with your own, using the API configuration table below.

  curl -X DELETE \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SECRET_KEY" \
    "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/volumes/<volume-id>"

Retrieving information about a volume

This operation allows you to retrieve information about a given volume.

Run the following command to retrieve information about your volume using the CLI:

  scw ipfs volume get volume-id=11111111-1111-1111-1111-111111111111

You should get a response like the following, providing details about the volume.

  ID 11111111-1111-1111-1111-111111111111
  ProjectID 00000000-0000-0000-0000-000000000000
  Region fr-par
  CountPin 0
  CreatedAt now
  UpdatedAt now
  Name my-volume

Alternatively, you can also run the following API command. Just make sure to replace the example values with your own, using the API configuration table below.

  curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/volumes/<VOLUME-ID>"

Listing volumes

This operation allows you to list all volumes from a given Project.

Run the following command to list all volumes from a Project using the CLI:

scw ipfs volume list

You should get a response like the following, providing a list of all volumes contained within a Project.

  ID                                    PROJECT ID
  11111111-1111-1111-1111-111111111111  00000000-0000-0000-0000-000000000000
  22222222-2222-2222-2222-222222222222  00000000-0000-0000-0000-000000000000

Alternatively, you can also run the following API command:

  curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/volumes?order_by=created_at_asc&project_id=$PROJECT_ID"

Update a volume

This operation allows you to update the details of a given volume, specified by its name and/or tag.

Run the following CLI command to update:

scw ipfs volume update volume-id=11111111-1111-1111-1111-111111111111 name=my-updated-name tags=my-tag

You should get an output similar to the following one, showing you your updates:

ID         11111111-1111-1111-1111-111111111111
ProjectID  00000000-0000-0000-0000-000000000000
Region     fr-par
CountPin   0
CreatedAt  11 minutes ago
UpdatedAt  now
Name       my-updated-name

Alternatively, you can also run the following API command. Just make sure to replace the example values with your own, using the API configuration table below:

  curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/volumes/<volume-id>" \
    -d '{
    "name": "my-updated-name",
    "tags": [
      "my-tag"
    ]
  }'

API configuration table

Parameter	Description
`$SECRET_KEY`	The secret part of your API key
`$REGION_ID`	Create a volume in this given region. Possible values are `fr-par`, `pl-waw` and `nl-ams`. Default value is `fr-par`.
`$PROJECT_ID`	ID of the Project you want to create your volume in. Your Project name can only contain alphanumeric characters, spaces, dots, and dashes. To find your Project ID, you can consult the Scaleway console
`name`	Create a volume with this given name.