Understanding and preparing for Public Gateways v2

Scaleway’s VPC offering is evolving, and with this comes changes for the Public Gateway product.

This document explains what to expect and how to prepare for the upcoming changes.

Summary (TL;DR)Link to this anchor

All Scaleway Public Gateways until now have been created and managed with the version 1 of the Public Gateways API, either explicitly via the API itself, or implicitly behind the scenes of the Scaleway console or other developer tools.

We are now deprecating v1 of the API and transitioning to v2.

After a deprecation period ending on 1 Oct 2025, the Public Gateways API v1 and associated developer tools will be removed.

What you need to do before 1 Oct 2025:

• Ensure that your Public Gateway is in IPAM mode. Only IPAM-mode gateways are compatible with v2.

• Put any non-IPAM mode (legacy) Public Gateways in IPAM mode. You can do this in several ways:

  • Use the Move to IPAM mode button in the console
  • Use the dedicated API call.
  • Use the move_to_ipam flag in Terraform

• Update any code or scripts you have that call version 1 of the Public Gateways API, so that they call version 2 instead, and do not refer to removed functionalities.

If your Public Gateway is already in IPAM mode, and you only manage it via the console, you will not be affected by these changes and you do not need to take any action.

Background: DHCP and IPAMLink to this anchor

When Scaleway originally introduced Public Gateways, they provided DHCP functionality for resources on attached Private Networks. With the arrival of Scaleway VPC in 2023, DHCP was moved from Public Gateways to Private Networks themselves.

Scaleway also introduced IPAM to act as a single source of truth for the IP addressing of all Scaleway resources. DHCP uses IPAM to ensure consistent and reliable addressing across all Private Networks.

When you create a Private Network, you can either automatically generate a default IPv4 CIDR block, or define a custom block. A default IPv6 block is automatically created. When you attach resources to the Private Network, they automatically receive an IPv4 address (and, if compatible, an IPv6 address) from this block. Alternatively, you can reserve a specific IP address from the block, and specify this address when attaching the resource.

Whether you choose a custom or default CIDR block, automatic address assignment or use a reserved address, the resource’s private IP address does not risk changing unless you detach the resource from the Private Network. To ensure that you can keep the same address for a resource even after detaching it, use the reserve IP functionality.

Introducing Public Gateways API v2Link to this anchor

Since the assignment and management of IP addresses on Private Networks is now managed by IPAM and the Private Networks themselves, we must complete the removal of the DHCP functionality from Public Gateways. This means releasing a new version (v2) of the Public Gateways API, which has until now retained a number of legacy DHCP functions. From this new version, you can observe:

• IPAM mode becomes default
• Removal of the DHCP object
• Removal of the address field
• Removal of DHCP entries
• New SSH bastion feature: Allowed IPs

Full details of each change are explained below.

IPAM mode becomes defaultLink to this anchor

Scaleway Public Gateways are either in Legacy mode or IPAM mode. You can see the mode of a given gateway by:

• Checking its badge in the gateway listing page of the Scaleway console (see screenshot below).
• Checking the value of the is_legacy field via the Public Gateways API.

Legacy Public Gateways use a workaround to ensure IPAM compatibility. IPAM-mode Public Gateways are fully integrated with Scaleway’s IPAM, which manages the coherent assignment of IP addresses to the gateway itself, and resources on attached Private Networks.

Legacy mode will be deprecated going forward, and will not be compatible with v2 of the Public Gateway API. It will no longer be possible to create legacy-mode Public Gateways, all new gateways will necessarily be in IPAM mode.

If you still have a legacy gateway, you must transition it to IPAM mode so that it is compatible with v2 of the API. This will update the auto-calculated is_legacy field and put your gateway in IPAM mode.

Removal of the DHCP objectLink to this anchor

The DHCP object has remained present in v1 of the API, despite the migration of DHCP to Private Networks, which replaced DHCP on Public Gateways.

The DHCP object does not exist in v2 of the API. Instead, IPAM configuration, where auto-configuration of GatewayNetwork is managed by IPAM and DHCP is managed by Private Networks, replaces any need for DHCP configuration via the Public Gateway.

Remember that you can define a custom CIDR block for a Private Network at the time of creation, and use reserved IP addresses with IPAM when attaching both standard and custom resources.

Removal of the address fieldLink to this anchor

For some time now, this functionality has been available via the API and developer tools only (not the Scaleway console).

When attaching a Public Gateway to a Private Network (creating a Gateway Network) via the API, you could use the address field to define a single static IP address to assign to the Public Gateway on that Private Network.

The address field does not exist in v2 of the API. Instead, you can pass an ipam_ip_id to specify a reserved IP address to use for a Public Gateway on a Private Network, if you wish. On the Scaleway console, you can select a reserved IP to use when attaching a Public Gateway to a Private Network. Otherwise, use the default behaviour where IPAM auto-assigns an IP address from the Private Network’s CIDR block to the Public Gateway at the moment of attachment.

When you use a dedicated method to move a legacy Public Gateway to IPAM mode, it will keep its current IP address on all attached Private Networks.

Removal of DHCP entriesLink to this anchor

For some time now, this functionality has been available via the API and developer tools only (not the Scaleway console).

DHCP entries could be created, belonging to a specified GatewayNetwork (Public Gateway / Private Network attachment), holding dynamic DHCP leases or static, user-created DHCP reservations. They have effectively allowed the Public Gateway to assign certain IP addresses to certain resources on the Private Network.

DHCP entries do not exist in v2 of the API. Instead, you can rely on the default IPAM/DHCP functionality as described above. The default behavior will auto-assign IP addresses to resources on the Private Network from the network’s CIDR block, or you can use the IP reservation functionality to specify the IP address(es) to assign to each resource.

For custom resources, such as VMs hosted on Elastic Metal servers, we now provide dedicated functionality for attaching these to Private Networks. When choosing the Custom Resource type, you can specify a MAC address and hostname at the moment of attachment.

We will automatically migrate any existing DHCP entries to IPAM for you, at the moment you put a legacy Public Gateway into IPAM mode.

SSH bastion allowed IPsLink to this anchor

Allowed IPs is a new functionality of the Public Gateways API v2, that will also be available to all IPAM-mode Public Gateways via the Scaleway console. This feature allows you to specify a list of IP address ranges which should be allowed to connect to the gateway’s SSH bastion and the resources behind it. All other IP addresses will be blocked from connecting. Find out more in the SSH bastion documentation.

Timeline and action to takeLink to this anchor

• March 2025 - V2 release: The Public Gateway v2 API is released, co-existing with v1.

• 8 April 2025 - V1 deprecation: The Public Gateway v1 API is deprecated. Deprecation means that the API will still function, but it is slated for removal and we do not recommended that you keep using it.

  Note

  You will be able to list and manage all gateways with the Scaleway console, which will adapt to use v1 or v2 of the API as necessary depending on whether or not the gateway is in IPAM mode.

• 8 April 2025 - 1 Oct 2025: Migration period: You have a six month migration period to complete the following actions

  • Ensure that your Public Gateway is in IPAM mode. Only IPAM mode gateways are compatible with v2.
  • Put any non-IPAM mode (legacy) Public Gateways in IPAM-mode, by using the Move to IPAM mode button in the console, the dedicated API call, or the move_to_ipam flag in Terraform.
  • Ensure that DHCP is activated on all Private Networks attached to your IPAM-mode Public Gateways.
  • Update any code or scripts you have that call version 1 of the Public Gateways API, so that they call version 2 instead. This includes removing any use of the DHCP entries, DHCP objects or address fields as mentioned above.

  If your Public Gateway is already in IPAM mode, and you only manage it via the console, you will not be affected by these changes and you do not need to take any action.

• 1 Oct 2025 - V1 removal: The Public Gateway v1 API will be removed. Any code or scripts still pointing to v1 will cease to function. We will automatically put any existing legacy Public Gateways into IPAM mode.

FAQLink to this anchor

How do I know if I have to take action?Link to this anchor

• Consider whether you manage your Public Gateway uniquely via the Scaleway console, or via calls to the API/devtools in code and scripts:

  • Code and scripts: If you have any code or scripts that call v1 of the API, or use devtool functionality that is removed from v2 such as DHCP object or entries, you must take action before 1 Oct 2025. Update your code and scripts so they point to v2 of the API. Follow the examples provided for tools such as Terraform to rewrite your devtool templates so they do not refer to removed functionalities. Do this in synchronization with moving your gateway to IPAM mode (if necessary).

  • Console-only: You do not need to take any action, except ensuring that your gateway is in IPAM mode.

• Check in the Scaleway console whether your Public Gateway is in IPAM mode or legacy mode:

  • Legacy mode: You must move the gateway to IPAM mode. Only IPAM mode gateways are compatible with v2. Use the Move to IPAM mode button in the console, the dedicated API call, or the move_to_ipam flag in Terraform.

  • IPAM mode: You do not have any action to take, except updating any code and scripts that you have (see above).

How do I move my legacy Public Gateway to IPAM mode?Link to this anchor

You can do this in several ways:

• Use the Move to IPAM mode button in the console
• Use the dedicated API call.
• Use the move_to_ipam flag in Terraform

What happens when I move my legacy Public Gateway to IPAM mode?Link to this anchor

We will detach your Public Gateway from all attached Private Networks, and reattach it in IPAM mode. You can expect downtime of about 10-20 seconds. We will ensure that the IP address used for the new attachment is the same as the old one.

My Public Gateway is already in IPAM mode, do I need to take any action?Link to this anchor

If you only manage your gateway via the Scaleway console, you do not need to take any action once your gateway is in IPAM mode.

If you have any code or scripts that call v1 of the Scaleway Public Gateways API, you must update these to point towards v2 before 1 Oct 2025.

What if I want to keep using my custom gateway DHCP configuration from v1 of the API?Link to this anchor

After version 1 of the Public Gateways API is removed on 1 Oct 2025, these functionalities will no longer be available.

Going forward, we expect users who were previously using custom DHCP with a Public Gateway to move to the standard set-up of IPAM and Private Networks’ inbuilt DHCP for private IP assignment. Remember that you can define a custom CIDR block for a Private Network at the time of creation, and use reserved IP addresses with IPAM when attaching both standard and custom resources.

I use Terraform to manage my Public Gateway, what should I do?Link to this anchor

If you use Terraform to manage your infrastructure as code, ensure that you are not using any functionality associated with v1 of the API (DHCP objects, DHCP entries or the address field). If necessary, modify your templates to reattach your Public Gateways in IPAM mode with the move_to_ipam flag, and use IPAM functionality to replace any DHCP configurations.

resource "scaleway_vpc_public_gateway" "main" {
  name          = "foobar"
  type          = "VPC-GW-S"
  ip_id         = scaleway_vpc_public_gateway_ip.main.id
  move_to_ipam  = true
}

Refer to our Terraform migration guide for full details and help moving legacy gateways to IPAM mode.

Can’t I just wait for Scaleway to force the move to IPAM mode?Link to this anchor

After 1 Oct 2025 we will carry out a forced action which will move all existing legacy Public Gateways to IPAM mode, and we will remove v1 of the Public Gateways API.

We highly recommend that you move to IPAM mode before this date, so that you can plan a smooth and synchronized transition at a time that suits you.

If you still have code or scripts pointing to v1 of the API after the 1 Oct 2025, these will cease to function.

Further help and supportLink to this anchor

If you have any questions, get in touch with us on the #public-gateway channel on the Scaleway Slack Community, or open a support ticket.

The following documentation resources may be useful to you:

• Public Gateway API Documentation
• Public Gateway Main Documentation
• IPAM API Documentation
• IPAM Main Documentation
• Moving a Public Gateway from Legacy mode to IPAM mode with Terraform