Sidebar navigationMain contentFooter
HomeComputeInstancesAPI/CLI
Using routed IPs
Jump toUpdate content

Routing public IPs to Instances using the Scaleway API

Reviewed on 16 June 2023 • Published on 17 May 2023
Security & Identity (IAM):

You may need certain IAM permissions to carry out some actions described on this page. This means:

  • you are the Owner of the Scaleway Organization in which the actions will be carried out, or
  • you are an IAM user of the Organization, with a policy granting you the necessary permission sets
Requirements:

Routed IPs - Overview

Note:

This guide is part of Scaleway’s IP Mobility project and will evolve over time.

During the deployment of an Instance, a private IP address linked to the underlying node hosting the Instance is assigned to it. If the underlying physical node changes, the private IP address will also change accordingly.

This change can occur when you stop and restart your Instance. This private network enables communication between Instances without the need for a public IP address. In addition, the public network is provided by a network component that manages a carrier-grade NAT (Network Address Translation), establishing a one-to-one mapping between the flexible IP and the private IP assigned to the Instance during provisioning.

When routing a public IP directly to an Instance, private IPs are no longer in use. Instead, traffic is routed directly to the flexible IP of the Instance. The main advantage of this approach is that your underlying IP remains unchanged when you stop and start the Instance or when it gets provisioned on another hypervisor. However, it also means that it will not have network access if you do not attach any flexible IP to your Instance. Another feature of routed IP is the ability to assign multiple flexible IP addresses to your Instance, allowing you to use both IPv4 and IPv6 protocols.

Note:
  • Currently, the routed IP is available in the pl-waw-2, fr-par-3 and nl-ams-2 Availability Zones.
  • Dynamic IPs continue to be supported after the migration to routed IPs.
  • The field enable_ipv6 is being deprecated and has no meaning for routed IP enabled Instances.

How to enable routed IP?

Note:

Currently, routed IP is disabled by default. If you are interested in exploring its functionality, you need to explicitly enable it.

In this section, we will guide you through the process of creating a new Instance with a routed IP. We will also provide instructions on migrating your existing legacy Instances.

  • The following examples rely on httpie, you can easily adapt them with curl if you prefer.
  • The API_URL variable contains the following value: https://api.scaleway.com/instance/v1/zones/<zone>
  • The HEADERS variable contains: X-Auth-Token:<API secret key>
Important:

Keep in mind that once the migration to routed IPs is complete, there is no way to revert it.

Creating a routed IP

You can request routed IPs using the Scaleway API. Available IP types are IPv4 and IPv6.

❯ cat payloads/ip-data.json
{
    "type": "routed_ipv6",
    "project": "7ddae24a-ad61-4744-830c-079d1c66abe1"
}
❯ http post $API_URL/ips $HEADERS <payloads/ip-data.json
Tip:

If you want an IPv4 address instead, replace the type routed_ipv6 with routed_ipv4.

Tip:

Note that the field address will always be null with "type": "routed_ipv6" because in practice you get assigned a complete /64 prefix and not a single IP address. You will then find the prefix information within the prefix key.

Create a new Instance with a routed IP

Run the following command to create an Instance with the previously created IP address.

❯ cat payloads/server-data.json
{
    "name": "my-publicip-instance",
    "commercial_type": "GP1-S",
    "dynamic_ip_required": false,
    "enable_ipv6": false,
    "routed_ip_enabled": true,
    "project": "7ddae24a-ad61-4744-830c-079d1c66abe1",
    "public_ip": "01ac2664-699e-46b5-80be-9d43d477857f",
    "image": "62f9eea9-61dc-4944-b420-069687a3238a"
}
❯ http post $API_URL/servers $HEADERS <payloads/server-data.json
Tip:

In order to create an Instance with a routed IP, you have to add "routed_ip_enabled": true to your payload.

Create a new Instance with one IPv4 only

First you need to create an IPv4 reservation, then create a new Instance with this public IP attached.

❯ cat payloads/ip-data.json
{
    "type": "routed_ipv4",
    "project": "7ddae24a-ad61-4744-830c-079d1c66abe1"
}
❯ http post $API_URL/ips $HEADERS <payloads/ip-data.json

And now we create the Instance.

❯ cat payloads/server-data.json
{
    "name": "my-publicipv4-instance",
    "commercial_type": "GP1-S",
    "dynamic_ip_required": false,
    "enable_ipv6": false,
    "routed_ip_enabled": true,
    "project": "7ddae24a-ad61-4744-830c-079d1c66abe1",
    "public_ip": "01ac2664-699e-46b5-80be-9d43d477858f",
    "image": "62f9eea9-61dc-4944-b420-069687a3238a"
}
❯ http post $API_URL/servers $HEADERS <payloads/server-data.json
Tip:

In order to create an Instance with a routed IP, you have to add "routed_ip_enabled": true to your payload.

Create a dual stack IPv4/IPv6 Instance

You can now attach several IPs to one public IP enabled Instance and you can mix up both IPv4 and IPv6 addresses. We assume you create multiple IPs as described in the example.

Then you can create a new Instance using those IPs through the public_ips field.

Note:

Not to be confused with the public_ip field that only accepts one IP.

❯ cat payloads/server-data.json
{
    "name": "my-publicip-instance-multi",
    "commercial_type": "GP1-S",
    "dynamic_ip_required": false,
    "enable_ipv6": false,
    "routed_ip_enabled": true,
    "project": "7ddae24a-ad61-4744-830c-079d1c66abe1",
    "public_ips": ["01ac2664-699e-46b5-80be-9d43d477868f", "487e556c-0351-4a12-9762-4f33bc2c2379", "92873598-d8e6-4d98-9254-697b3e56ff6b"],
    "image": "62f9eea9-61dc-4944-b420-069687a3238a"
}
❯ http post $API_URL/servers $HEADERS <payloads/server-data.json
Tip:

In order to create Instance you have to add "routed_ip_enabled": true to your payload.

Migrating existing Instances to routed IPs

You can use a specific server action to migrate an existing (legacy network) Instance to routed IPs.

❯ http post $API_URL/servers/$SERVER_ID/action $HEADERS action=enable_routed_ip
Note:

Your instance will reboot during this action.

Verifying if an IP is routed or NAT type

You can verify if your IP is a routed IP or a NAT IP through the /ips endpoint:

❯ http $API_URL/ips/201f52df-3c83-4eeb-aff4-038bb15f918d $HEADERS

Verifying routed IPs are enabled for your Instance

You can verify if your Instance is enabled for routed IPs through the /servers endpoint:

❯ http $API_URL/servers/9515993f-f596-4b51-84e8-9e48f2d49eb8 $HEADERS
Managing Instance snapshots with the CLI (v2)Using cloud-init