NavigationContentFooter

Introduction

Scaleway Instances are virtual machines in the cloud. Different Instance types offer different technical specifications in terms of vCPU, RAM, bandwidth and storage. Once you have created your Instance and installed your image of choice (e.g. an operating system), you can connect to your Instance via SSH to use it as you wish. When you are done using the Instance, you can delete it from your account.

Tip

To retrieve information about the different images available to install on Scaleway Instances, check out our Marketplace API.

Concepts

Refer to our dedicated concepts page to find definitions of all concepts and terminology related to Instances.

Quickstart

  1. Configure your environment variables

    Note

    This is an optional step that seeks to simplify your usage of the Instances 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>"
  2. Create an Instance: Run the following command to create an Instance. You can customize the details in the payload (name, description, type, tags etc) to your needs: use the information below to adjust the payload as necessary.

    curl -X POST \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -H "Content-Type: application/json" \
    "https://api.scaleway.com/instance/v1/zones/$SCW_DEFAULT_ZONE/servers" \
    -d '{
    "name": "my-new-instance",
    "project": "'"$SCW_PROJECT_ID"'",
    "commercial_type": "GP1-S",
    "image": "ubuntu_noble",
    "enable_ipv6": true,
    "volumes": {
    "0":{
    "size": 300000000000,
    "volume_type": "l_ssd"
    }
    }
    }'
    ParameterDescriptionValid values
    nameA name of your choice for the Instance (string)Any string containing only alphanumeric characters, dots, spaces and dashes, e.g. "my-new-instance".
    projectThe Project in which the Instance should be created (string)Any valid Scaleway Project ID (see above), e.g. "b4bd99e0-b389-11ed-afa1-0242ac120002"
    commercial-typeThe commercial Instance type to create (string)Any valid ID of a Scaleway commercial Instance type, e.g. "GP1-S", "PRO2-M". Use the List Instance Types endpoint to get a list of all valid Instance types and their IDs.
    imageThe image to install on the Instance, e.g. a particular OS (string)Any Scaleway image label, e.g. "ubuntu_noble", or any valid Scaleway image ID, e.g. "6fc0ade6-d6a3-4fb9-87ab-2444ac71e5c0" which is the ID for the Ubuntu 24.04 Noble Numbat image. Use the List Instance Images endpoint to get a list of all available images with their IDs and labels, or check out the Scaleway Marketplace API.
    enable_ipv6Whether to enable IPv6 on the Instance (boolean)true or false
    volumesAn object that specifies the storage volumes to attach to the Instance. For more information, see Creating an Instance: the volumes object in the Technical information section of this quickstart.A (dictionary) object with a minimum of one key ("0") whose value is another object containing the parameters "name" (a name for the volume), "size" (the size for the volume, in bytes), and "volume_type" ("l_ssd" or "b_ssd"). Additional keys for additional volumes should increment by 1 each time (the second volume would have a key of 1.) Further parameters are available, and it is possible to attach existing volumes rather than creating a new one, or create a volume from a snapshot.
  3. List your Instances: run the following command to get a list of all the Instances in your account, with their details:

    curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    "https://api.scaleway.com/instance/v1/zones/$SCW_DEFAULT_ZONE/servers/"
  4. Delete an Instance: run the following command to delete an Instance, specified by its Instance ID:

    curl -X DELETE \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -H "Content-Type: application/json" \
    "https://api.scaleway.com/instance/v1/zones/$SCW_DEFAULT_ZONE/servers/<Instance-ID>"

    The expected successful response is empty.

Requirements
  • You have a Scaleway account
  • 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

Technical information

Availability Zones

Instances can be deployed in the following Availability Zones:

NameAPI ID
Parisfr-par-1 fr-par-2 fr-par-3
Amsterdamnl-ams-1 nl-ams-2
Warsawpl-waw-1 pl-waw-2

Pagination

Most listing requests receive a paginated response. Requests against paginated endpoints accept two query arguments:

  • page, a positive integer to choose which page to return.
  • per_page, an positive integer lower or equal to 100 to select the number of items to return per page. The default value is 50.

Paginated endpoints usually also accept filters to search and sort results.These filters are documented along each endpoint documentation.

The X-Total-Count header contains the total number of items returned.

Creating an Instance: the volumes object

When creating an Instance using the Scaleway API, the volumes object is not strictly required. However, the defaults vary depending on certain conditions:

  1. If an image label is used:

    • The default will be an sbs_volume volume.
    • The size of this volume will be the OS size (typically 10GB in most cases).
  2. If an image ID from the marketplace is used (or any image based on a unified snapshot):

    • If the Instance supports local storage:
      • The default will be an l_ssd volume.
      • The size of this volume will be the instance's maximum local storage capacity.
    • If the Instance does not support local storage:
      • The default will be a b_ssd volume.
      • The size of this volume will be the OS size.

If you want to customize the storage configuration or add additional volumes, you will need to include the volumes object in your API request. This object should contain at least one (dictionary) object with a minimum of one key ("0") whose value is another object containing the parameters "name" (a name for the volume), "size" (the size for the volume, in bytes), and "volume_type" ("sbs_volume", "l_ssd" or "b_ssd"). Additional keys for additional volumes should increment by 1 each time (the second volume would have a key of "1".)

Note that volume size must respect the volume constraints of the Instance's commercial_type: for each type of Instance, a minimum amount of storage is required, and there is also a maximum that cannot be exceeded. All Instance types support Block Storage (sbs_volume, b_ssd), some also support local storage (l_ssd). Read more about these constraints in the List Instance types documentation, specifically the volume_constraints parameter for each type listed in the response

You can use the volumes object in different ways. The table below shows which parameters are required for each of the following use cases:

Use caseRequired paramsOptional paramsNotes
Create a volume (l_ssd, b_ssd, sbs_volume) from a snapshot of an imagevolume_type, size, bootIf the size parameter is not set, the size of the volume will equal the size of the corresponding snapshot of the image. The image snapshot type should be compatible with the volume_type.
Create a volume (l_ssd, b_ssd) from a snapshotbase_snapshot, name, volume_typeboot
Create a volume of type sbs_volume from a snapshotbase_snapshot, name, volume_typesize, boot
Create an empty volumename, volume_type, sizeboot
Attach an existing volume (l_ssd, b_ssd)idboot
Attach an existing volume of type sbs_volumeid, volume_typeboot
Note

This information is designed to help you correctly configure the volumes object when using the Create an Instance or Update an Instance methods.

Going further

For more help using Scaleway Instances, check out the following resources:

  • Our main documentation
  • The #instance channel on our Slack Community
  • Our support ticketing system.

Instances

Instances are computing units providing resources to run your applications on. Scaleway offers various Instance types including Virtual Instances and dedicated GPU Instances. Note: Instances can be referenced as "servers" in API endpoints.

GET
/instance/v1/zones/{zone}/servers
POST
/instance/v1/zones/{zone}/servers
GET
/instance/v1/zones/{zone}/servers/{server_id}
PATCH
/instance/v1/zones/{zone}/servers/{server_id}
DELETE
/instance/v1/zones/{zone}/servers/{server_id}
GET
/instance/v1/zones/{zone}/servers/{server_id}/action
POST
/instance/v1/zones/{zone}/servers/{server_id}/action

Images

Images are backups of your Instances. One image will contain all the volumes of your Instance and can be used to restore your Instance and its data. You can also use it to create a series of Instances with a predefined configuration. To copy not all but only one specified volume of an Instance, you can use the snapshot feature instead.

GET
/instance/v1/zones/{zone}/images
POST
/instance/v1/zones/{zone}/images
PUT
/instance/v1/zones/{zone}/images/{id}
GET
/instance/v1/zones/{zone}/images/{image_id}
PATCH
/instance/v1/zones/{zone}/images/{image_id}
DELETE
/instance/v1/zones/{zone}/images/{image_id}

Security Groups

A security group is a set of firewall rules on a set of Instances. Security groups enable you to create rules that either drop or allow incoming traffic from certain ports of your Instances.

Security groups are stateful by default which means return traffic is automatically allowed, regardless of any rules. As a contrary, you have to switch in a stateless mode to define explicitly allowed.

GET
/instance/v1/zones/{zone}/security_groups
POST
/instance/v1/zones/{zone}/security_groups
PUT
/instance/v1/zones/{zone}/security_groups/{id}
GET
/instance/v1/zones/{zone}/security_groups/{security_group_id}
PATCH
/instance/v1/zones/{zone}/security_groups/{security_group_id}
DELETE
/instance/v1/zones/{zone}/security_groups/{security_group_id}
GET
/instance/v1/zones/{zone}/security_groups/{security_group_id}/rules
POST
/instance/v1/zones/{zone}/security_groups/{security_group_id}/rules
PUT
/instance/v1/zones/{zone}/security_groups/{security_group_id}/rules
GET
/instance/v1/zones/{zone}/security_groups/{security_group_id}/rules/{security_group_rule_id}
PUT
/instance/v1/zones/{zone}/security_groups/{security_group_id}/rules/{security_group_rule_id}
PATCH
/instance/v1/zones/{zone}/security_groups/{security_group_id}/rules/{security_group_rule_id}
DELETE
/instance/v1/zones/{zone}/security_groups/{security_group_id}/rules/{security_group_rule_id}
GET
/instance/v1/zones/{zone}/security_groups/default/rules

User Data

User data is a key/value store you can use to provide your instance with introspective data.

As an example of use, Scaleway images contain the scw-generate-ssh-keys script, which generates the SSH server’s host keys, then stores their fingerprints as user data under the ssh-host-fingerprints key. This way, before connecting to the instance using SSH, one can query the fingerprints to ensure that the remote host is the expected one, thus avoiding any man-in-the-middle attack.

There are two ways of accessing user data:

  • From within a running Instance, by requesting the Metadata API at http://169.254.42.42/user_data (or http://[fd00:42::42]/user_data using IPv6). The scaleway-ecosystem package, installed by default on all OS images provided by Scaleway, ships with the scw-userdata helper command that allows you to easily query the user data from the instance. For security reasons, viewing and editing user data is only allowed to queries originating from a port below 1024 (by default, only the super-user can bind to ports below 1024). To specify the source port with cURL, use the --local-port option (e.g. curl --local-port 1-1023 http://169.254.42.42/user_data).
  • From the Instance API by using the methods described below.
GET
/instance/v1/zones/{zone}/servers/{server_id}/user_data
GET
/instance/v1/zones/{zone}/servers/{server_id}/user_data/{key}
PATCH
/instance/v1/zones/{zone}/servers/{server_id}/user_data/{key}
DELETE
/instance/v1/zones/{zone}/servers/{server_id}/user_data/{key}

Instance Types

All Instance types available in a specified zone. Each type contains all the features of the Instance (CPU, RAM, Storage) as well as their associated pricing.

GET
/instance/v1/zones/{zone}/products/servers
GET
/instance/v1/zones/{zone}/products/servers/availability

Volume Types

All volume types available in a specified zone. Each of these types will contains all the capabilities and constraints of the volume (min size, max size, snapshot).

GET
/instance/v1/zones/{zone}/products/volumes

IPs

A flexible IP address is an IP address which you hold independently of any Instance. You can attach it to any of your Instances and do live migration of the IP address between your Instances.

Note that attaching a flexible IP address to an Instance removes its previous public IP and interrupts any ongoing public connection to the Instance. This does not apply if you have migrated your server to the new Network stack and have at least one flexible IP attached to the Instance.

GET
/instance/v1/zones/{zone}/ips
POST
/instance/v1/zones/{zone}/ips
GET
/instance/v1/zones/{zone}/ips/{ip}
PATCH
/instance/v1/zones/{zone}/ips/{ip}
DELETE
/instance/v1/zones/{zone}/ips/{ip}

Volumes

A volume is where you store your data inside your Instance. It appears as a block device on Linux that you can use to create a filesystem and mount it.

Two different types of volume (volume_type) are available:

  • l_ssd is a local block storage: your data is downloaded on the hypervisor and you need to power off your Instance to attach or detach a volume.
  • b_ssd is a remote block storage: your data is stored on a centralized cluster. You can plug and unplug a volume while your Instance is running.

Minimum and maximum volume sizes for each volume types can be queried from the zone /products/volumes API endpoint. I.e for:

  • fr-par-1 use https://api.scaleway.com/instance/v1/zones/fr-par-1/products/volumes
  • nl-ams-1 use https://api.scaleway.com/instance/v1/zones/nl-ams-1/products/volumes

Each type of volume is also subject to a global quota for the sum of all the volumes. This quota depends of the level of support and may be changed on demand.

Be wary that when terminating an Instance, if you want to keep your block storage volume, you must detach it before you issue the terminate call.

When using multiple block devices, it's advised to mount them by using their UUID instead of their device name. A device name is subject to change depending on the volumes order. Block devices UUIDs can be found in /dev/disk/by-id/.

POST
/instance/v1/zones/{zone}/block-migration/apply
POST
/instance/v1/zones/{zone}/block-migration/plan
GET
/instance/v1/zones/{zone}/volumes
POST
/instance/v1/zones/{zone}/volumes
PUT
/instance/v1/zones/{zone}/volumes/{id}
GET
/instance/v1/zones/{zone}/volumes/{volume_id}
PATCH
/instance/v1/zones/{zone}/volumes/{volume_id}
DELETE
/instance/v1/zones/{zone}/volumes/{volume_id}

Snapshots

Snapshots contain the data of a specified volume at a particular point in time. The data can include the Instance's operating system, configuration information and/or files stored on the volume.

A snapshot can be done from a specified volume, e.g. you have one Instance with a volume containing the OS and another one containing the application data, and you want to use different snapshot strategies on both volumes.

A snapshot's volume type is its original volume's type (l_ssd or b_ssd). Volumes can be created from snapshots of their own type.

GET
/instance/v1/zones/{zone}/snapshots
POST
/instance/v1/zones/{zone}/snapshots
GET
/instance/v1/zones/{zone}/snapshots/{snapshot_id}
PUT
/instance/v1/zones/{zone}/snapshots/{snapshot_id}
PATCH
/instance/v1/zones/{zone}/snapshots/{snapshot_id}
DELETE
/instance/v1/zones/{zone}/snapshots/{snapshot_id}
POST
/instance/v1/zones/{zone}/snapshots/{snapshot_id}/export

Placement Groups

Placement groups allow the user to express a preference regarding the physical position of a group of Instances. The feature lets the user choose to either group Instances on the same physical hardware for best network throughput and low latency or to spread Instances across physically distanced hardware to reduce the risk of physical failure.

The operating mode is selected by a policy_type. Two policy types are available:

  • low_latency will group Instances on the same hypervisors
  • max_availability will spread Instances across physically distanced hypervisors

The policy_type is set to max_availability by default.

For each policy types, one of the two policy_mode may be selected:

  • optional will start your Instances even if the constraint is not respected
  • enforced guarantees that if the Instance starts, the constraint is respected

The policy_mode is set by default to optional.

GET
/instance/v1/zones/{zone}/placement_groups
POST
/instance/v1/zones/{zone}/placement_groups
GET
/instance/v1/zones/{zone}/placement_groups/{placement_group_id}
PUT
/instance/v1/zones/{zone}/placement_groups/{placement_group_id}
PATCH
/instance/v1/zones/{zone}/placement_groups/{placement_group_id}
DELETE
/instance/v1/zones/{zone}/placement_groups/{placement_group_id}
GET
/instance/v1/zones/{zone}/placement_groups/{placement_group_id}/servers
PUT
/instance/v1/zones/{zone}/placement_groups/{placement_group_id}/servers
PATCH
/instance/v1/zones/{zone}/placement_groups/{placement_group_id}/servers

Private NICs

A Private NIC is the network interface that connects an Instance to a Private Network. An Instance can have multiple private NICs at the same time, but each NIC must belong to a different Private Network.

GET
/instance/v1/zones/{zone}/servers/{server_id}/private_nics
POST
/instance/v1/zones/{zone}/servers/{server_id}/private_nics
GET
/instance/v1/zones/{zone}/servers/{server_id}/private_nics/{private_nic_id}
PATCH
/instance/v1/zones/{zone}/servers/{server_id}/private_nics/{private_nic_id}
DELETE
/instance/v1/zones/{zone}/servers/{server_id}/private_nics/{private_nic_id}
Docs APIScaleway consoleDedibox consoleScaleway LearningScaleway.comPricingBlogCarreer
© 2023-2024 – Scaleway