Public Gateways APIv1

Scaleway Public Gateways are building blocks for your infrastructure on Scaleway's public cloud. They sit at the border of Private Networks and provide access to/from other networks or the Internet. As well as this, Public Gateways offer a host of managed features and services to facilitate the management of resources in your Private Network, including DHCP to dynamically assign IP addresses, and NAT to map private IP addresses in the Private Network to the public IP address of the Public Gateway.

Refer to our dedicated concepts page to find definitions of all terminology related to Public Gateways, including DHCP, NAT, SSH bastion and more.

Requirements: To perform the following steps, you must first ensure that:

• You have a Scaleway account
• You have created an API key and that the API key has sufficient IAM permissions to perform the actions described on this page
• You have installed curl

1. Configure your environment variables.

   Note: This is an optional step that seeks to simplify your usage of the Public Gateways API.

2. Choose a Public Gateway type: Public Gateways come in different shapes and sizes, with different network capabilities and pricing. When you create your Public Gateway, you need to include the required Public Gateway type in the request. Use the following call to get a list of available Public Gateway offer types and their details:

3. Create a Public Gateway: run the following command to create a Public Gateway. You can customize the details in the payload (name, description, tags, etc) to your needs: use the information below to adjust the payload as necessary.

   Parameter	Description	Valid values
   type	The type of Public Gateway (commercial offer type) to create. Use the Gateway Types endpoint to get a list of offer types.	Any valid offer type string, e.g. VPC-GW-S
   name	A name of your choice for the Public Gateway	Any string containing only alphanumeric characters and dashes, e.g. my-new-gateway.
   tags	A list of tags to describe your Public Gateway. These can help you manage and filter your gateways.	A list of alphanumeric strings, e.g. ["my-first-tag, my-second-tag
   project_id	The Scaleway Project ID to create the Public Gateway in.	A valid Scaleway Project ID, e.g. f5fe13a0-b9c7-11ed-afa1-0242ac120002

   Note: Further parameters are available, but for the purposes of this quickstart we have included only the essentials. See the Create a Public Gateway endpoint documentation below for full details of all possible parameters.

4. Get a list of your Public Gateways: run the following command to get a list of all your Public Gateways.

5. Attach a Private Network to a Public Gateway: run the following command to attach a Private Network to your Public Gateway, and make all the Gateway's services such as DHCP and NAT available to the Private Network. You can customize the details in the payload to your needs: use the information below to adjust the payload as necessary.

   Tip: If you haven't created a Private Network yet, see the Private Networks documentation to learn how to do so. Ensure you retain the ID of the Private Network.

   This configuration will set up the Public Gateway as a NAT gateway, masquerading traffic sent to it to the outer internet to provide internet access to resources in the Private Network, and serving IP addresses through DHCP to said instances, in the subnet 192.168.1.0/24.

   Parameter	Description	Valid values
   gateway_id	The Public Gateway ID of an existing Public Gateway	Any valid Public Gateway ID, e.g. b1b2edda-9364-422d-93f2-ad04e6a054dc
   private_network_id	The Private Network ID of an existing Private Network	Any valid Private Network ID in the same Availability Zone as the Public Gateway, e.g. 548dbcc3-8b78-486f-a79a-c3f5a17642f9
   enable_masquerade	Defines whether the gateway should masquerade traffic for the attached Private Network (i.e. whether to enable dynamic NAT)	A boolean value, e.g. true
   dhcp	An DHCP object (see object definition in the DHCP endpoint documentation below), which defines DHCP configuration.	An object which includes the Scaleway Project ID of the Public Gateway/Private Network, and the subnet to use for the Private Network e.g. {"project_id": "'$SCW_PROJECT_ID'", "subnet": "192.168.1.0/24"}

   Note: Further parameters are available, but for the purposes of this quickstart we have included only the essentials. See the Attach a gateway to a Private Network endpoint documentation below for full details of all possible parameters.

6. Delete a Public Gateway: run the following call to delete your Public Gateway. Ensure that you replace <PUBLIC-GATEWAY-ID> in the URL with the ID of the Public Gateway you want to delete.

   The expected successful response is empty.

• A maximum of eight (8) Private Networks can be plugged into a single Public Gateway

• Note that the Public Gateway takes some time to start up, and actions on it are impossible unless it is in the running state. To check the current state of a Public Gateway, use the Get a Public Gateway endpoint to get information for your gateway: the status field of the response will tell you if it is running or in another state.

• For further information about Public Gateway limitations https://www.scaleway.com/en/docs/network/public-gateways/troubleshooting/gw-limitations/

Public Gateways can be deployed in the following Availability Zones:

The Scaleway Public Gateways API is a zoned API, meaning that each call must specify in its path parameters the Availability Zone for the resources concerned by the call.

For more help using Scaleway Public Gateways, check out the following resources:

• Our main documentation
• The #vpc-public-gateway channel on our Slack Community
• Our support ticketing system.

List Public Gateways in a given Scaleway Organization or Project. By default, results are displayed in ascending order of creation date.

Create a new Public Gateway in the specified Scaleway Project, defining its name, type and other configuration details such as whether to enable SSH bastion.

Get details of a Public Gateway, specified by its gateway ID. The response object contains full details of the gateway, including its name, type, status and more.

Update the parameters of an existing Public Gateway, for example, its name, tags, SSH bastion configuration, and DNS servers.

Delete an existing Public Gateway, specified by its gateway ID. This action is irreversible.

Refresh the SSH keys of a given Public Gateway, specified by its gateway ID. This adds any new SSH keys in the gateway's Scaleway Project to the gateway itself.

Upgrade a given Public Gateway to the newest software version. This applies the latest bugfixes and features to your Public Gateway, but its service will be interrupted during the update.

List the connections between Public Gateways and Private Networks (a connection = a GatewayNetwork). You can choose to filter by gateway-id to list all Private Networks attached to the specified Public Gateway, or by private_network_id to list all Public Gateways attached to the specified Private Network. Other query parameters are also available. The result is an array of GatewayNetwork objects, each giving details of the connection between a given Public Gateway and a given Private Network.

Attach a specific Public Gateway to a specific Private Network (create a GatewayNetwork). You can configure parameters for the connection including DHCP settings, whether to enable masquerade (dynamic NAT), and more.

Get details of a given connection between a Public Gateway and a Private Network (this connection = a GatewayNetwork), specified by its gateway_network_id. The response object contains details of the connection including the IDs of the Public Gateway and Private Network, the dates the connection was created/updated and its configuration settings.

Update the configuration parameters of a connection between a given Public Gateway and Private Network (the connection = a GatewayNetwork). Updatable parameters include DHCP settings and whether to enable traffic masquerade (dynamic NAT).

Detach a given Public Gateway from a given Private Network, i.e. delete a GatewayNetwork specified by a gateway_network_id.

List DHCP configurations, optionally filtering by Organization, Project, Public Gateway IP address or more. The response is an array of DHCP configuration objects, each identified by a DHCP ID and containing configuration settings for the assignment of IP addresses to devices on a Private Network attached to a Public Gateway. Note that the response does not contain the IDs of any Private Network / Public Gateway the configuration is attached to. Use the List Public Gateway connections to Private Networks method for that purpose, filtering on DHCP ID.

Create a new DHCP configuration object, containing settings for the assignment of IP addresses to devices on a Private Network attached to a Public Gateway. The response object includes the ID of the DHCP configuration object. You can use this ID as part of a call to Create a Public Gateway connection to a Private Network or Update a Public Gateway connection to a Private Network to directly apply this DHCP configuration.

Get a DHCP configuration object, identified by its DHCP ID. The response object contains configuration settings for the assignment of IP addresses to devices on a Private Network attached to a Public Gateway. Note that the response does not contain the IDs of any Private Network / Public Gateway the configuration is attached to. Use the List Public Gateway connections to Private Networks method for that purpose, filtering on DHCP ID.

Update a DHCP configuration object, identified by its DHCP ID.

Delete a DHCP configuration object, identified by its DHCP ID. Note that you cannot delete a DHCP configuration object that is currently being used by a Gateway Network.

List DHCP entries, whether dynamically assigned and/or statically reserved. DHCP entries can be filtered by the Gateway Network they are on, their MAC address, IP address, type or hostname.

Create a static DHCP reservation, specifying the Gateway Network for the reservation, the MAC address of the target device and the IP address to assign this device. The response is a DHCP entry object, confirming the ID and configuration details of the static DHCP reservation.

Set the list of DHCP reservations attached to a Gateway Network. Reservations are identified by their MAC address, and will sync the current DHCP entry list to the given list, creating, updating or deleting DHCP entries accordingly.

Get a DHCP entry, specified by its DHCP entry ID.

Update the IP address for a DHCP entry, specified by its DHCP entry ID. You can update an existing DHCP entry of any type (reservation (static), lease (dynamic) or unknown), but in manually updating the IP address the entry will necessarily be of type reservation after the update.

Delete a static DHCP reservation, identified by its DHCP entry ID. Note that you cannot delete DHCP entries of type lease, these are deleted automatically when their time-to-live expires.

List PAT rules. You can filter by gateway ID to list all PAT rules for a particular gateway, or filter for PAT rules targeting a specific IP address or using a specific protocol.

Create a new PAT rule on a specified Public Gateway, defining the protocol to use, public port to listen on, and private port / IP address to map to.

Set a definitive list of PAT rules attached to a Public Gateway. Each rule is identified by its public port and protocol. This will sync the current PAT rule list on the gateway with the new list, creating, updating or deleting PAT rules accordingly.

Get a PAT rule, specified by its PAT rule ID. The response object gives full details of the PAT rule, including the Public Gateway it belongs to and the configuration settings in terms of public / private ports, private IP and protocol.

Update a PAT rule, specified by its PAT rule ID. Configuration settings including private/public port, private IP address and protocol can all be updated.

Delete a PAT rule, identified by its PAT rule ID. This action is irreversible.

List Public Gateway flexible IP addresses. A number of filter options are available for limiting results in the response.

Create (reserve) a new flexible IP address that can be used for a Public Gateway in a specified Scaleway Project.

Get details of a Public Gateway flexible IP address, identified by its IP ID. The response object contains information including which (if any) Public Gateway using this IP address, the reverse and various other metadata.

Update details of an existing flexible IP address, including its tags, reverse and the Public Gateway it is assigned to.