VPC APIv1

Download OpenAPI

Introduction

VPC is a set of products and features allowing you to build your own virtual private cloud on top of Scaleway's shared public cloud. It currently consists of Private Networks, which allows instances to be interconnected through a dedicated, private, and flexible L2 network.

You can add as many servers to your networks as you want, and add up to eight (8) different networks per server, taking the form of additional network interfaces inside your instance. This allows you to run services isolated from the public internet and expose them to the rest of your infrastructure without worrying about public network filtering.

Instances can be plugged and unplugged from a network at will, even when the instance is running: the network interface will be hot-plugged to the server, and software can be configured to automatically set it up as soon as it appears.

Technnical limitations

  • A maximum of eight (8) private networks can be plugged to any single instance
  • The MAC address of an instance in a network cannot be changed
  • Broadcast and Multicast traffic, while supported, are heavily rate-limited

You need to have an HTTP client such as curl to use Scaleway API. It is also a good idea to have jq which will help you to read and parse JSON output. Make sure you have these two tools before you begin. Otherwise use your package manager to install them.

To call Scaleway API, you need an X-Auth-Token. If you don't have one yet, refer to our doc about generating API keys.

Next, you will need your Project ID to create VPC resources in. If you don't have it, refer to our doc about creating a Project.

Finally, you will need to chose the Availability Zone in which to create your Private Networks. Keep in mind that Private Networks are per zone and not per region, thus you will only be able to connect Instances to networks from the same Availability Zone.

export SECRET_KEY="<Secret key of your token>"
export PROJECT_ID="<Chosen Project ID>"
export ZONE="<Chosen zone (fr-par-1/nl-ams-1)>"

You can customize the name, tags and project ID for the created Private Network.

curl -s -H "Content-Type: application/json" -H "X-Auth-Token: $SECRET_KEY" \
https://api.scaleway.com/vpc/v1/zones/$ZONE/private-networks \
-d '{"name": "My awesome Private Network", \
"project_id": "'$PROJECT_ID'" \
"tags": ["test", "step1"]}'

Keep the id field of the response: it is your Private Network ID, and is useable across all Scaleway products that support Private Networks. Since it will be used in the next steps, we will put it in a variable for the sake of readability.

export PN_ID="<Your Private Network ID>"

To delete your Private Network, you can use the following call:

curl -s -H "Content-Type: application/json" -H "X-Auth-Token: $SECRET_KEY" \
https://api.scaleway.com/vpc/v1/zones/$ZONE/private-networks/$PN_ID \
-X DELETE

Please note that the Private Network must be empty to be deleted, so be sure to remove any other Scaleway product from your network prior to deletion.

Each product has its own API to interact with Private Networks, and each will be described here.

Instance

Scaleway Instances support Private Networks on a per-server basis. For this, you will need an instance in the same Availability Zone as your Private Network, and the Instance ID. For readability purposes, we will put the Instance ID in a variable:

export SRV_ID="<Your Instance ID>"

Then, use the following call to attach the Instance to your Private Network:

curl -s -H "Content-Type: application/json" -H "X-Auth-Token: $SECRET_KEY" \
https://api.scaleway.com/instance/v1/zones/$ZONE/servers/$SRV_ID/private_nics \
-d '{"private_network_id": "'$PN_ID'"}'

Keep the id field of the response: it is your Private NIC ID. For readability purposes, we will put it in a variable:

export NIC_ID="<Your Private NIC ID>"

Keep the mac_address field of the response, as it will allow you to identify the Private NIC inside your Instance. If successful, a new network interface will appear inside your Instance, ready to be configured to transmit traffic to other instances of the same network, with the MAC address returned by the API call.

By running dmesg, you can confirm that the network interface has been plugged:

[1579004.592869] pci 0000:00:05.0: [1af4:1000] type 00 class 0x020000
[1579004.594835] pci 0000:00:05.0: reg 0x10: [io 0x0000-0x003f]
[1579004.596715] pci 0000:00:05.0: reg 0x14: [mem 0x00000000-0x00000fff]
[1579004.598732] pci 0000:00:05.0: reg 0x20: [mem 0x00000000-0x00003fff 64bit pref]
[1579004.600765] pci 0000:00:05.0: reg 0x30: [mem 0x00000000-0x0007ffff pref]
[1579004.603819] pci 0000:00:05.0: BAR 6: assigned [mem 0xc0100000-0xc017ffff pref]
[1579004.604582] pci 0000:00:05.0: BAR 4: assigned [mem 0x100000c000-0x100000ffff 64bit pref]
[1579004.605555] pci 0000:00:05.0: BAR 1: assigned [mem 0xc0003000-0xc0003fff]
[1579004.606383] pci 0000:00:05.0: BAR 0: assigned [io 0x1000-0x103f]
[1579004.607212] virtio-pci 0000:00:05.0: enabling device (0000 -> 0003)
[1579004.625149] PCI Interrupt Link [LNKA] enabled at IRQ 11
[1579004.644930] virtio_net virtio3 ens5: renamed from eth0

By running ip -br link, you can confirm the presence of the network interface, and confirm its name if several networks are plugged to your instance:

lo UNKNOWN 00:00:00:00:00:00 <LOOPBACK,UP,LOWER_UP>
ens2 UP de:1c:94:44:d0:04 <BROADCAST,MULTICAST,UP,LOWER_UP>
ens5 DOWN 02:00:00:00:00:31 <BROADCAST,MULTICAST>
ens6 DOWN 02:00:00:00:01:5b <BROADCAST,MULTICAST>
ens7 DOWN 02:00:00:00:01:5e <BROADCAST,MULTICAST>

You can now refer to our online documentation on how to configure those network interfaces.

To delete your Private NIC, which equates to unplugging your Instance from the Private Network, you can use the following call:

curl -s -H "Content-Type: application/json" -H "X-Auth-Token: $SECRET_KEY" \
https://api.scaleway.com/instance/v1/zones/$ZONE/servers/$SRV_ID/private_nics/$NIC_ID \
-X DELETE

Then the network interface should disappear from your Instance.

A private network allows interconnecting your instances in an isolated and private network. The network reachability is limited to the instances that are on the same private network. Network Interface Controllers (NICs) are available on the instance and can be freely managed (adding IP addresses, shutdown interface...)

Note that an instance can be a part of multiple private networks.

List private networks

GET
/vpc/v1/zones/{zone}/private-networks
Path Parameters

zone
required string
The zone you want to target. Possible values are fr-par-1 and nl-ams-1.
Query Parameters

order_by
string
The sort order of the returned private networks. Possible values are created_at_asc, created_at_desc, name_asc and name_desc. The default value is created_at_asc.

page
number
The page number for the returned private networks. The default value is 1.

page_size
number
The maximum number of private networks per page. The default value is 20.

name
nullable string
Filter private networks with names containing this string.

tags
array
Filter private networks with one or more matching tags.

organization_id
nullable string
The organization ID on which to filter the returned private networks.

project_id
nullable string
The project ID on which to filter the returned private networks.
200 Response

private_networks
array
id
string
The private network ID.

name
string
The private network name.

organization_id
string
The private network organization.

project_id
string
The private network project ID.

zone
string
The zone in which the private network is available.

tags
array
The private network tags.

created_at
string
The private network creation date.

updated_at
string
The last private network modification date.

total_count
number
Response Example
{
"private_networks": [
{
"id": "string",
"name": "string",
"organization_id": "string",
"project_id": "string",
"zone": "string",
"tags": [
"string"
],
"created_at": "string",
"updated_at": "string"
}
],
"total_count": 42
}
POST
/vpc/v1/zones/{zone}/private-networks
Path Parameters

zone
required string
The zone you want to target. Possible values are fr-par-1 and nl-ams-1.
Body

name
required string
The name of the private network.

project_id
required string
The project ID of the private network.

tags
array
The private networks tags.
Request Example
{
"name": "string",
"project_id": "string",
"tags": [
"string"
]
}
200 Response

id
string
The private network ID.

name
string
The private network name.

organization_id
string
The private network organization.

project_id
string
The private network project ID.

zone
string
The zone in which the private network is available.

tags
array
The private network tags.

created_at
string
The private network creation date.

updated_at
string
The last private network modification date.
Response Example
{
"id": "string",
"name": "string",
"organization_id": "string",
"project_id": "string",
"zone": "string",
"tags": [
"string"
],
"created_at": "string",
"updated_at": "string"
}
GET
/vpc/v1/zones/{zone}/private-networks/{private_network_id}
Path Parameters

zone
required string
The zone you want to target. Possible values are fr-par-1 and nl-ams-1.

private_network_id
required string
The private network id.
200 Response

id
string
The private network ID.

name
string
The private network name.

organization_id
string
The private network organization.

project_id
string
The private network project ID.

zone
string
The zone in which the private network is available.

tags
array
The private network tags.

created_at
string
The private network creation date.

updated_at
string
The last private network modification date.
Response Example
{
"id": "string",
"name": "string",
"organization_id": "string",
"project_id": "string",
"zone": "string",
"tags": [
"string"
],
"created_at": "string",
"updated_at": "string"
}
PATCH
/vpc/v1/zones/{zone}/private-networks/{private_network_id}
Path Parameters

zone
required string
The zone you want to target. Possible values are fr-par-1 and nl-ams-1.

private_network_id
required string
The private network ID.
Body

name
nullable string
The name of the private network.

tags
nullable array
The private networks tags.
Request Example
{
"name": "string",
"tags": [
"string"
]
}
200 Response

id
string
The private network ID.

name
string
The private network name.

organization_id
string
The private network organization.

project_id
string
The private network project ID.

zone
string
The zone in which the private network is available.

tags
array
The private network tags.

created_at
string
The private network creation date.

updated_at
string
The last private network modification date.
Response Example
{
"id": "string",
"name": "string",
"organization_id": "string",
"project_id": "string",
"zone": "string",
"tags": [
"string"
],
"created_at": "string",
"updated_at": "string"
}
DELETE
/vpc/v1/zones/{zone}/private-networks/{private_network_id}
Path Parameters

zone
required string
The zone you want to target. Possible values are fr-par-1 and nl-ams-1.

private_network_id
required string
The private network ID.
204 Response

Empty response