NavigationContentFooter
Jump toSuggest an edit

Routing public IPs to Instances using the Scaleway CLI/API

Reviewed on 24 June 2024 • Published on 17 May 2023

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
Important
  • The routed IP feature is not compatible with legacy Instance types using the bootscript feature.
  • If you are using a manual DHCP configuration on the public NIC, ensure that it is compatible with a routed IP setup.
  • You must update the scw and cloud-init packages before starting the transition.
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
  • The routed IP feature is available in all Availability Zones.
  • Dynamic IPs continue to be supported after the transition to routed IPs.
  • The field enable_ipv6 is being deprecated and has no meaning for routed IP enabled Instances.

How to use routed IPs with the Scaleway CLI

Since version 2.20.0, the Scaleway CLI tool has native support for the routed IP feature.

Creating a routed IP Instance via CLI

You can create a new routed IP-enabled Instance using the following command:

❯ scw instance server create routed-ip-enabled=true zone=pl-waw-1

Moving an existing Instance to routed IP via CLI

To activate the routed IP feature on an existing Instance, you can move it with the command shown below. Any attached IPv4 will be transferred. However, the current IPv6 will be substituted with a new one. Once assigned, this new IPv6 will remain assigned to the Instance even through stop/start cycles.

Note

Be aware that the Instance will reboot during this process.

❯ scw instance server enable-routed-ip 01e75c58-db6a-432c-914c-1e281a57d31e zone=pl-waw-1
✅ Enable_routed_ip successfully started for the server.

Creating a new routed IP (IPv4/IPv6) via CLI

By using the type= field, you can create routed IPs, either as routed_ipv4 or routed_ipv6. You can then assign the newly-created IP to your Instance.

❯ scw instance ip create type=routed_ipv6 zone=pl-waw-1

How to use routed IPs with the API

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 moving 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 transition to routed IPs is complete, there is no way to revert it.

Creating a routed IP via the API

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 via the API

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 via the API

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.

Moving existing Instances to routed IPs via the API

You can use a specific server action to move 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 via the API

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 via the API

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
API DocsScaleway consoleDedibox consoleScaleway LearningScaleway.comPricingBlogCareers
© 2023-2024 – Scaleway