VPC API

Close Introduction

This API concerns the zoned Private Networks service. Private Networks allows Scaleway resources (Instances, Load Balancers, Managed Databases etc.) within a single Availability Zone to be interconnected through a dedicated, private, and flexible L2 network.

You can add as many resources to your networks as you want, and add up to eight (8) different networks per resource. 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.

Concepts

Refer to the Public Gateway concepts page to find definitions of concepts and terminology related to Private Networks.

Quickstart

1. Configure your environment variables

   Note:

   This is an optional step that seeks to simplify your usage of the 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>"Copy

2. Create a Private Network. Run the following command to create a Private Network. You can customize the details in the payload (name, tags etc.) to your needs.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     -H "Content-Type: application/json" \
     "https://api.scaleway.com/vpc/v1/zones/$SCW_DEFAULT_ZONE/private-networks" \
     -d '{
       "name": "My new Private Network",
       "project_id": "'"$SCW_PROJECT_ID"'", 
       "tags": ["test", "dev"]
     }'Copy

   Tip:

   Keep the id field of the response: it is your Private Network ID, and is useable across all Scaleway products that support Private Networks. It may be useful to you to export the Private Network ID as a new environment variable export PN_ID="<Your Private Network ID>

3. Attach a resource to your Private Network. Each Scaleway product has its own API to interact with Private Networks. To attach an Instance, Managed Database, Elastic Metal server, Load Balancer or Public Gateway to your Private Network, see instructions in the documentation of the relevant product API. Here, we take the example of an Instance.

   Use the following call to attach an Instance to your Private Network. Ensure you replace <Instance ID> with the ID of your Instance, and <Private Network ID> with the ID of your Private Network.

   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/<Instance ID>/private_nics" \
     -d '{"private_network_id": "<Private Network ID>"}'Copy

   Tip:

   Keep the id field of the response: it is your Private NIC ID. It may be useful to you to export the Private NIC ID as a new environment variable export NIC_ID="<Your Private NIC ID>.

   Tip:

   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.

4. Confirm that the network interface has been plugged in. To do this, connect to your Instance and run dmseg. You should see an output similar to the following:

   [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 eth0Copy

5. Confirm the presence of the network interface, and confirm its name if several networks are plugged into your Instance. To do this, run ip -br link. You should see an output similar to the following:

   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>Copy

6. Configure the network interface on your Instance. Refer to our dedicated documentation for help with this step. Alternatively, use a Public Gateway to facilitate configuration of your resources on your Private Network.

7. Delete your Private NIC, which equates to unplugging your Instance from the Private Network. Use the following call. Ensure you replace <Instance ID> with the ID of your Instance, <Private Network ID> with the ID of your Private Network, and <NIC ID> with the ID of your Private NIC.

   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>/private_nics/<NIC ID>"Copy

   The network interface disappears from your Instance.

8. Delete your Private Network. Use the following call. Ensure you replace <Private Network ID> with the ID of your Private Network.

   curl -X DELETE \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     -H "Content-Type: application/json" \
     "https://api.scaleway.com/vpc/v1/zones/$SCW_DEFAULT_ZONE/private-networks/<Private Network ID>"
   Copy

   Note:

   Private Networks must be empty to be deleted. Ensure you have detached all resources from your network prior to deletion.

Technical information

Availability Zones

Scaleway Private Networks is a zoned product. It is available in the following Availability Zones:

Technical limitations

The following limitations apply to Scaleway Private Networks:

• A maximum of eight (8) Private Networks can be plugged to any single Instance
• The MAC address of an Instance in a Private Network cannot be changed
• Broadcast and multicast traffic, while supported, are heavily rate-limited

Going further

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

• Our main documentation
• The #private-networks channel on our Slack Community
• Our support ticketing system.

Open Private Networks