feat(pgw): migration doc for v2 (#4443)

* fix(pgw): explain deprecation

* fix(pgw): add v2 prep doc

* fix(pgw): corrections

* fix(pgw): add info

* fix(pgw): update migration doc

* fix(pgw): typo

* fix(pgw): corrections

* fix(pgw): rebase and add dates

* fix(pgw): add screenshot

* fix(pgw): update deprecation info

* fix(pgw): update

* fix(pgw): correct dates

* fix(pgw): fix deprecation doc

* fix(pgw): add tf refs to guide

* Update pages/public-gateways/reference-content/understanding-v2.mdx

* fix(pgw): fix dates

* fix(pgw): correct links

* fix(concepts): update

* fix(pgw): add faq

* Update pages/public-gateways/reference-content/understanding-v2.mdx

* Apply suggestions from code review

Co-authored-by: ldecarvalho-doc <[email protected]>

* fix(pgw): review comments

---------

Co-authored-by: ldecarvalho-doc <[email protected]>

Author: RoRoJ

pages/public-gateways/concepts.mdx

@@ -73,14 +73,15 @@ Private Networks attached to legacy Public Gateways must stay in the gateway's a
 
 **IPAM** Public Gateways are fully and natively integrated with the Scaleway IPAM without any workaround. Your gateway is in IPAM mode if:
 - You created it via the Scaleway console on or after 17 October 2023 
-- You created it via the Scaleway API or developer tools using the `ipam_config` object, and the auto-calculated `is_legacy` [Gateway parameter](https://www.scaleway.com/en/developers/api/public-gateway/#path-gateways-create-a-public-gateway) has a value of `false`. 
-
-You cannot "migrate" a legacy Public Gateway to become an IPAM-mode gateway. While legacy Public Gateways continue to function thanks to our [workaround](/vpc/reference-content/vpc-migration/#public-gateways-and-vpc), you cannot modify them to become natively integrated IPAM networks. If you wish to have an IPAM-mode Public Gateway, for example to benefit from IP management via Scaleway's [IPAM](https://www.scaleway.com/en/developers/api/vpc/) API as more features become available, or to use Kapsule with full isolation, you must create a new gateway.
+- You created it via the Scaleway API or devtools using the `ipam_config` object, and the auto-calculated `is_legacy` [Gateway parameter](https://www.scaleway.com/en/developers/api/public-gateway/#path-gateways-create-a-public-gateway) has a value of `false`. 
+- You moved it from legacy mode to IPAM mode using the dedicated button in the console, or the dedicated API call.
 
 <Message type="note">
 When creating a Kubernetes Kapsule cluster with [full isolation](/kubernetes/reference-content/secure-cluster-with-private-network/#can-i-use-a-public-gateway-with-my-private-network-to-exit-all-outgoing-traffic-from-the-nodes) you are required to attach a Public Gateway to the cluster's Private Network, and this **cannot** be a legacy Public Gateway - it must be an IPAM-mode gateway.
 </Message>
 
+See also our dedicated documentation on [moving Public Gateways to IPAM-mode](/public-gateways/reference-content/understanding-v2/) to ensure compatibility with our new API v2.
+
 ## Legacy gateway
 
 See [IPAM](#ipam).

pages/public-gateways/faq.mdx

@@ -29,13 +29,33 @@ Moreover, the Public Gateway supports [static NAT](/public-gateways/how-to/confi
 
 On 12 July 2023, DHCP functionality moved from Public Gateways to Private Networks. See our [dedicated migration documentation](/vpc/reference-content/vpc-migration/) for full details.
 
-Pre-existing static leases created via the Public Gateway were fully migrated and still work for your attached resources on a Private Network. Manual static lease configuration is still available via the API and other developer tools, but is no longer available via the Scaleway console. We recommend that you use [Scaleway IPAM](/ipam/) to reserve private IP addresses on specific Private Networks, which you can then use when attaching resources.
+Pre-existing static leases created via the Public Gateway were fully migrated and still work for your attached resources on a Private Network. Manual static lease configuration is still available via the API v1 and other developer tools, but this functionality is now deprecated, and does not exist in v2 of the API.
 
-## Why is my Public Gateway labelled as Legacy?
+Read our [dedicated documentation](/public-gateways/reference-content/understanding-v2/) to learn how to put your gateway into IPAM-mode and replicate static DHCP reservation functionality with Scaleway IPAM.
 
-**Legacy** Public Gateways use a [workaround](/vpc/reference-content/vpc-migration/#public-gateways-and-vpc) to ensure compatiblity with Scaleway's IPAM (**I** **P** **A**ddress **M**anagement) tool. IPAM acts as a single source of truth for the IP addresses of Scaleway resources
+## Why is my Public Gateway labeled as Legacy?
 
-Your gateway is probably a legacy gateway if you created it prior to 17 October 2023. These gateways will continue to function, but are not natively integrated with IPAM, and you cannot take advantage of features such as IP management via Scaleway [IPAM](/ipam/), or fully-isolated Kubernetes Kapsules. You should create a new gateway if you want to benefit from such features. 
+**Legacy** Public Gateways use a [workaround](/vpc/reference-content/vpc-migration/#public-gateways-and-vpc) to ensure compatibility with Scaleway's IPAM (**I** **P** **A**ddress **M**anagement) tool. IPAM acts as a single source of truth for the IP addresses of Scaleway resources
+
+Your gateway is a legacy gateway if you created it prior to 17 October 2023 and you never recreated it in IPAM mode. Legacy gateways are now deprecated, as they are incompatible with v2 of the Public Gateways API. Such gateways must be [moved to IPAM mode](/public-gateways/reference-content/understanding-v2/) before October 2025 to ensure ongoing functionality.
+
+## I received a message about v1 of the Public Gateways API being deprecated, do I need to take action?
+
+The Public Gateways API v1 is now deprecated, and will be removed on 1 October 2025. Only IPAM-mode gateways will be compatible with the new version of the API (v2). Whether or not you need to take action depends on the following two points:
+
+- 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](/public-gateways/reference-content/understanding-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](https://github.com/scaleway/terraform-provider-scaleway/blob/master/docs/guides/migration_guide_vpcgw_v2.md) 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](https://console.scaleway.com/public-gateway/public-gateways) 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](https://www.scaleway.com/en/developers/api/public-gateway/v1/#path-gateways-put-a-public-gateway-in-ipam-mode), or the `move_to_ipam` flag in [Terraform](https://github.com/scaleway/terraform-provider-scaleway/blob/master/docs/guides/migration_guide_vpcgw_v2.md).
+
+  - **IPAM mode**: You do not have any action to take, except updating any code and scripts that you have (see above).
+
+See our [dedicated documentation](/public-gateways/reference-content/understanding-v2/) for full details.
 
 ## Do I need a Public Gateway for each Availability Zone (AZ)?
 

pages/public-gateways/reference-content/assets/scaleway-pgw-listing.webp

@@ -0,0 +1,8 @@
+---
+meta:
+  title: Public Gateways - Additional Content
+  description: Explore detailed Scaleway configurations, best practices and troubleshooting for Scaleway Public Gateways. Optimize the configuration of your gateway with our comprehensive reference guides.
+content:
+  h1: Public Gateways - Additional Content
+  paragraph: Explore detailed Scaleway configurations, best practices and troubleshooting for Scaleway Public Gateways. Optimize the configuration of your gateway with our comprehensive reference guides.
+---