feat(network): add doc for new routing behavior (#4927)

* feat(vpc): start new routing concepts

* feat(vpc): new routing behavior

* fix(vpc): continue routing modifs

* fix(vpc,pgw): update routing doc

* fix(nw): finish routing updates

* fix(pgw): default route

* fix(vpc): routing

* fix(vpc): clarification

* fix(vpc): multiple default routes

* Update pages/public-gateways/faq.mdx

Co-authored-by: Jessica <[email protected]>

* Update pages/vpc/how-to/manage-routing.mdx

Co-authored-by: Jessica <[email protected]>

* Update pages/vpc/reference-content/understanding-routing.mdx

Co-authored-by: Jessica <[email protected]>

* Update pages/vpc/how-to/manage-routing.mdx

Co-authored-by: Jessica <[email protected]>

* fix(vpc): add routing date

* Apply suggestions from code review

Co-authored-by: Jessica <[email protected]>

---------

Co-authored-by: Jessica <[email protected]>

Author: RoRoJ

pages/public-gateways/concepts.mdx

@@ -22,12 +22,14 @@ Allowed IPs is a feature of [SSH bastion](#ssh-bastion). It allows you to specif
 
 ## Default route
 
-The Public Gateway can advertise a default route to resources on an attached Private Network, which takes effect when the IP destination address for a packet is not known on the network itself. In effect, resources in a Private Network will know to route packets through the Public Gateway if the destination IP address is not a host on the Private Network itself.
+When you attach a Public Gateway to a Private Network, you can choose to have it advertise a default route to other attached resources. This means that when the IP destination address for a packet is not known on the Private Network or elsewhere within the VPC, the packet is routed through the Public Gateway, enabling it to find the public internet. The default route is propagated through DHCP.
 
-You can choose to activate the advertisement of the default route when attaching a Private Network to a Public Gateway. The default route is propagated through DHCP.
+By default, the scope of a default route is limited to the Private Network the Public Gateway is directly attached to. However, you also have the option to enable each of your Private Networks to receive advertisements of **all** default routes throughout the entire VPC. This includes routes towards all Public Gateways advertising a default route, as well as any custom-created default routes. 
+
+If you opt to enable the reception of all default routes for a Private Network, resources on that network will be able to access the public internet via any Public Gateway in the VPC advertising a default route, even if it's not directly attached to their Private Network.
 
 <Message type="important">
-After activating the default route, all outbound and inbound traffic for resources attached to the Private Network is directed through the Public Gateway. This includes SSH traffic destined for Instances, which means you will need to [manage SSH connections differently](/public-gateways/troubleshooting/cant-connect-to-instance-with-pn-gateway/).
+The Public Gateway's default route advertisement takes priority over the default route through a resource's public interface. Outbound and inbound public traffic for resources receiving the route advertisement is therefore directed through the Public Gateway. This includes SSH traffic destined for Instances, which means you will need to [manage SSH connections differently](/public-gateways/troubleshooting/cant-connect-to-instance-with-pn-gateway/).
 </Message>
 
 ## DHCP

pages/public-gateways/faq.mdx

@@ -5,7 +5,7 @@ meta:
 content:
   h1: Public Gateways FAQ
 dates:
-  validation: 2025-04-07
+  validation: 2025-05-05
 category: network
 productIcon: PublicGatewayProductIcon
 ---
@@ -22,8 +22,8 @@ No. A public IPv4 address (aka. flexible IP) must be assigned to the Public Gate
 
 ## Can my Instances and other resources access the internet via a Public Gateway without a public IP address?
 
-Yes. The Public Gateway can advertize itself as the [default route to the internet](/public-gateways/concepts/#default-route) over the Private Network it is attached to, so that Instances and other resources on the same Private Network, can access the internet via the gateway.
-Moreover, the Public Gateway supports [static NAT](/public-gateways/how-to/configure-a-public-gateway/#how-to-review-and-configure-nat) (aka. port forwarding), so that ingress traffic from the public internet can reach Instances on the Private Network. This works by mapping pre-defined ports of the public IP address of the gateway to specific ports and IP addresses on the Private Network.
+Yes. The Public Gateway can advertise itself as the [default route to the internet](/public-gateways/concepts/#default-route) over the Private Network it is attached to, so that Instances and other resources can access the internet via the gateway. Resources attached to other Private Networks than the gateway's network in the VPC can [opt in](/vpc/how-to/manage-routing/#how-to-manage-default-route-scope) to receive its default route advertisement.
+Moreover, the Public Gateway supports [static NAT](/public-gateways/how-to/configure-a-public-gateway/#how-to-review-and-configure-nat) (aka. port forwarding), so that ingress traffic from the public internet can reach Instances on the Private Network. This works by mapping pre-defined ports of the public IP address of the gateway to specific ports and IP addresses on the VPC.
 
 ## What happened to static leases (DHCP reservations) when DHCP moved from the Public Gateway to Private Networks?
 

pages/public-gateways/how-to/configure-a-public-gateway.mdx

@@ -7,7 +7,7 @@ content:
   paragraph: Learn how to configure a Public Gateway with the Scaleway console. Follow our step-by-step guide to set up routing, internet access, and SSH bastion for secure, scalable network connectivity.
 tags: public-gateway public gateway dhcp nat smtp
 dates:
-  validation: 2025-01-03
+  validation: 2025-05-05
   posted: 2021-05-26
 categories:
   - network
@@ -38,7 +38,7 @@ This page shows you how to attach a [Public Gateway](/public-gateways/concepts/#
       </Message>
     - If you want to create and attach a new Private Network, select **Attach to a new Private Network**. The Private Network will be created with default configuration (a [CIDR block](/vpc/concepts#cidr-block) will be automatically defined), in your default VPC for the region, if one exists. If you do not have an existing VPC for the appropriate region, you must [create one](/vpc/how-to/create-vpc/#how-to-create-a-vpc) first. A name for the Private Network will be suggested, but feel free to overwrite this with a new name of your choice. Dynamic NAT will be automatically activated on the Public Gateway for the Private Network.
 6. Choose whether to **auto-allocate an available IP from the pool** (the [CIDR block](/vpc/concepts/#cidr-block) defined at the time of creating the Private Network), or use a **[reserved IP address](/ipam/concepts/#reserved-ip-address)** for the attachment.
-7. Use the toggle to select whether to **Advertise the default route**. Find out more about this setting in our [concepts documentation](/public-gateways/concepts/#default-route).
+7. Use the toggle to select whether to tell the gateway whether or not it should [advertise the default route](/public-gateways/concepts/#default-route) to the internet for attached resources. When activated, other resources on this Private Network will learn the default route through the Public Gateway via DHCP. The route will also be installed in the VPC’s route table, and other Private Networks can [opt in](/vpc/how-to/manage-routing/#how-to-manage-default-route-scope) to receive it. 
 8. Click **Attach to Private Network** to finish. You are taken back to the Private Networks tab, where the network you attached now appears, along with the services configured and the IP address of the Public Gateway.
 
 Your Private Network is now attached to your Public Gateway. You can repeat the steps above to attach more Private Networks to the same Public Gateway if you wish.
@@ -71,4 +71,16 @@ By default, the SMTP ports (25, 465, 587 and 2525) on your Public Gateway are bl
 
 <Message type="important">
   See our [troubleshooting](/public-gateways/troubleshooting/cant-connect-to-instance-with-pn-gateway/) documentation if you have any problems configuring your Public Gateway.
+</Message>
+
+## How to enable or disable default route advertisement
+
+You can enable or disable [default route advertisement](/public-gateways/concepts/#default-route) at any time.
+
+1. Click **Public Gateways** in the **Network** section of the side menu.
+2. Click the Public Gateway whose default route advertisement you wish to modify, then click the **Network** tab.
+3. Use the toggle <Icon name="toggle" /> to enable or disable default route advertisement on this network.
+
+<Message type="important">
+If you disable advertisement of a default route, any other Private Networks that were [receiving this default route](/vpc/how-to/manage-routing/#how-to-manage-default-route-scope) will no longer be able to route traffic to this Public Gateway.
 </Message>

pages/public-gateways/how-to/use-ssh-bastion.mdx

@@ -17,6 +17,10 @@ SSH bastion is a server dedicated to managing connections to the infrastructure
 
 The [Allowed IPs](#how-to-configure-allowed-ips) feature lets you control which public IPs can access resources behind the bastion. 
 
+<Message type="note">
+You can also use SSH bastion to connect to resources [receiving the Public Gateway's default route advertisement](/vpc/how-to/manage-routing/#how-to-manage-default-route-scope), even if they are not attached to the same Private Network as the gateway.
+</Message>
+
 <Macro id="requirements" />
 
 - A Scaleway account logged into the [console](https://console.scaleway.com)

pages/public-gateways/quickstart.mdx

@@ -46,7 +46,7 @@ categories:
         Only Private Networks which are in the same region as the Public Gateway are displayed in this list.
     </Message>
 6. Choose whether to **auto-allocate an available IP from the pool** (the [CIDR block](/vpc/concepts/#cidr-block) defined at the time of creating the Private Network), or use a **[reserved IP address](/ipam/concepts/#reserved-ip-address)** for the attachment.
-7. Use the toggle <Icon name="toggle" /> to tell the gateway whether or not it should [advertise the default route](/public-gateways/concepts/#default-route) to the internet for attached resources.
+7. Use the toggle <Icon name="toggle" /> to tell the gateway whether or not it should [advertise the default route](/public-gateways/concepts/#default-route) to the internet for attached resources. When activated, other resources on this Private Network will learn the default route through the Public Gateway via DHCP. The route will also be installed in the VPC’s route table, and other Private Networks can [opt in](/vpc/how-to/manage-routing/#how-to-manage-default-route-scope) to receive it. 
 8. Click **Attach to Private Network** to finish. You are taken back to the Private Networks tab, where the network you attached now appears, along with the services configured and the IP address of the Public Gateway.
 
     Your Private Network is now attached to your Public Gateway. You can repeat the steps above to attach more Private Networks to the same Public Gateway if you wish.

pages/public-gateways/troubleshooting/cant-connect-to-instance-with-pn-gateway.mdx

@@ -13,16 +13,27 @@ categories:
   - network
 ---
 
-If you are having trouble [connecting to your Instance via SSH](/instances/how-to/connect-to-instance/), when the Instance is attached to a Private Network which also has an attached Public Gateway, read on for help and solutions.
+## Problem
 
-The action to take depends on whether:
+You are unable to successfully [connect to your Instance via SSH](/instances/how-to/connect-to-instance/), when the Instance is attached to a Private Network which is receiving a default route advertisement from a Public Gateway. You may be experiencing connection timeouts or other error messages.
 
-- The Private Network(s) attached to your Instance have [DHCP enabled](/vpc/how-to/activate-dhcp/), and 
-- Your Public Gateway is set to [advertise a default route](/public-gateways/concepts/#default-route) (true by default).
+This troubleshooting guide applies to you if:
 
-If the above two conditions are not true, there may be other factors impacting your Instance, like one of your Instances running a DHCP server. Try disconnecting and reconnecting the Instance from the Private Network. 
+- Your Instance is attached to a Private Network which has an attached Public Gateway, AND
+- The gateway is set to [advertise a default route](/public-gateways/concepts/#default-route) (true by default), AND
+- The Private Network(s) attached to your Instance have [DHCP enabled](/vpc/how-to/activate-dhcp/)
 
-If DHCP **is** activated and your Public Gateway **is** set to advertise a default route, not being able to connect to your Instance via SSH is **expected behavior**. All the traffic towards your Instance now goes through the Public Gateway. 
+It may also apply if:
+
+- Your Instance is attached to a Private Network which is set to [receive all default route advertisements](/vpc/how-to/manage-routing/#how-to-manage-default-route-scope) from the VPC, AND
+- There is a Public Gateway in the VPC which is advertising a default route, AND
+- The Private Network(s) attached to your Instance have DHCP enabled
+
+If neither of the above scenarios applies, there may be other factors impacting SSH connection to your Instance, like one of your Instances running a DHCP server. Try disconnecting and reconnecting the Instance from the Private Network. 
+
+## Solution
+
+If one of the above scenario applies, not being able to connect to your Instance via SSH is **expected behavior**. The Public Gateway's default route advertisement takes priority over the default route through a resource's public interface. All the traffic towards your Instance now goes through the Public Gateway. 
 
 To access your Instance using SSH in this scenario, the recommended solution is to use [SSH bastion](/public-gateways/how-to/use-ssh-bastion/).
 

pages/vpc/concepts.mdx

@@ -124,11 +124,19 @@ Routes can be of the following types:
 
 When deciding which route to apply, the route table reads the routes from most specific to least specific, in terms of destination IP range. The first matching route encountered is the one that determines the path for the traffic. Therefore, a route to destination `172.16.8.0/22` is applied before a default route to `0.0.0.0/0`.
 
+Each route in a route table has a **scope**: it may be advertised across the entire VPC, or on certain Private Networks only.
+
 ## Routing
 
-Routing allows Private Networks in the same VPC to communicate with each other, via managed and custom routes. Routing is activated by default whenever you create a new VPC, and can be activated on pre-existing VPCs by [following these steps](/vpc/how-to/manage-routing/#how-to-activate-routing).
+Routing allows resources on Private Networks witin the same VPC to communicate with each other, via managed and custom routes. Routing is activated by default whenever you create a new VPC, and can be activated on pre-existing VPCs by [following these steps](/vpc/how-to/manage-routing/#how-to-activate-routing).
+
+Each routed VPC has a [route table](#route-table) which is automatically populated with routes to each of its Private Networks. When you attach a Public Gateway to a Private Network, and tell it to advertise a default route to the internet, such routes are also added to the VPC's route table. You can also create your own [custom routes](/vpc/how-to/manage-routing/#how-to-create-a-custom-route), to route traffic towards defined destination IP ranges towards specific "next hop" resources.
 
-Each routed VPC has a [route table](#route-table) which is automatically populated with routes to each Private Network in the VPC, as well as to any attached Public Gateways. These routes allow the VPC to automatically route packets between its Private Networks, or from a given Private Network to its attached Public Gateway when the destination is outside the VPC. You can also create your own [custom routes](/vpc/how-to/manage-routing/#how-to-create-a-custom-route).
+<Message type="note">
+If you have [updated](/vpc/how-to/manage-routing/#how-to-update-routing-behavior) routing behavior on your VPC, or created a VPC since July 1st 2025, routing takes on the following characteristics:
+- Custom routes are advertised across the entire VPC, instead of only on the Private Network of the resource designated as next hop.
+- You can optionally [enable each Private Network in the VPC to receive default route advertisements](/vpc/how-to/manage-routing/#how-to-manage-default-route-scope) not only from their locally attached Public Gateways, but from other Public Gateways (or default custom routes) attached to different Private Networks throughout the whole VPC. 
+</Message>
 
 Read more about how routing works in [our detailed guide](/vpc/reference-content/understanding-routing/).