fix(pgw): update migration doc

Author: RoRoJ

network/public-gateways/reference-content/understanding-v2.mdx

@@ -7,8 +7,8 @@ content:
   paragraph: Find out what to expect from Public Gateways v2, and get ready for deprecation of DHCP entries and the DHCP object, as well as new default behavior for IPAM mode.
 tags: public-gateways dhcp dhcp-entries api v2 ipam-mode legacy
 dates:
-  creation: 2024-11-05
-  validation: 2024-11-05
+  creation: 2025-01-23
+  validation: 2025-01-23
 categories: 
   - network
 ---
@@ -19,9 +19,17 @@ This document explains what to expect and how to prepare for the upcoming change
 
 ## Summary (TL;DR)
 
-If you have a [legacy](/network/public-gateways/concepts/#ipam) Public Gateway, or a Public Gateway that is still using the [DHCP object](https://www.scaleway.com/en/developers/api/public-gateway/#path-dhcp-list-dhcp-configurations) or [DHCP entries](https://www.scaleway.com/en/developers/api/public-gateway/#path-dhcp-entries-list-dhcp-entries) from the existing API, you must recreate your Public Gateway in the new v2 API, as these functionalities are being deprecated.
+All Scaleway Public Gateways until now have been created and managed with the [v1 version](TODO-LINK) of the Public Gateways API, either explicitly via the API itself or other devtools, or implicitly behind the scenes of the Scaleway console. 
 
-If your Public Gateway is already in [IPAM-mode](/network/public-gateways/concepts/#ipam), and you do not use the DHCP object or DHCP entries (only configurable by the API and not the console) your gateway will be automatically migrated to the new v2, and you do not need to take any action. [TODO - DOWNTIME?]
+**We are now deprecating v1 of the API and transitioning to [v2](TODO-LINK).**
+
+After a six month deprecation period, the Public Gateways API v1 and associated developer tools will be removed. Before this time, you must:
+
+- Ensure that your Public Gateway is in [IPAM mode](/network/public-gateways/concepts/#ipam). Only IPAM mode gateways are compatible with v2.
+- Put any non-IPAM mode ([legacy](/network/public-gateways/concepts/#ipam)) Public Gateways in IPAM mode, by detaching them and reattaching them to their Private Networks.
+- Update any code or scripts you have that call version 1 of the Public Gateways API, so that they call version 2 instead.
+
+If your Public Gateway is already in IPAM-mode, and you only manage it via the console, you will not be affected by this changes and you do not need to take any action.
 
 ## Background: DHCP and IPAM
 
@@ -41,6 +49,7 @@ Since the assignment and management of IP addresses on Private Networks is now m
 - Deprecation of the DHCP object
 - Deprecation of the `address` field
 - Deprecation of DHCP entries
+- New SSH bastion feature: Allowed IPs
 
 Read on to find out more.
 
@@ -57,45 +66,71 @@ All Public Gateways created via the Scaleway console since 17 October 2023 are n
 
 Legacy Public Gateways use a [workaround](/network/vpc/reference-content/vpc-migration/#public-gateways-and-vpc) to ensure IPAM compatibility. IPAM-mode Public Gateways are fully integrated with Scaleway's [IPAM](/network/ipam/concepts/#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. It will no longer be possible to create legacy-mode Public Gateways, all gateways will necessarily be in IPAM mode and the `is_legacy` parameter will be removed.
+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 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. Do this by **detaching and reattaching the Public Gateway from its Private Network**. This will update the auto-calculated `is_legacy` field and put your gateway in IPAM mode.
 
 ### Deprecation of the DHCP object
 
-The [DHCP object](https://www.scaleway.com/en/developers/api/public-gateway/#path-dhcp-list-dhcp-configurations) has, until now, allowed users to define a DHCP configuration, which specified how the gateway should assign IP addresses to devices on attached Private Networks (parameters including the subnet of the DHCP server, entry validity period and more).
+This functionality was available via the API and developer tools only (not the Scaleway console).
+
+The [DHCP object](https://www.scaleway.com/en/developers/api/public-gateway/#path-dhcp-list-dhcp-configurations) has, until now, allowed users to define a DHCP configuration, which specified how the gateway should assign IP addresses to devices on attached Private Networks (parameters including the subnet of the DHCP server, entry validity period and more). 
 
 When attaching a Public Gateway to a Private Network (creating a [Gateway Network](https://www.scaleway.com/en/developers/api/public-gateway/#path-gateway-networks-attach-a-public-gateway-to-a-private-network)) via the API, you can pass a DHCP object, or the ID of an existing DHCP object. 
 
-This functionality will be deprecated going forward. It will no longer be possible to create or attach DHCP objects to Gateway Networks. Instead, IPAM configuration, where auto-configuration of `GatewayNetwork` is managed by IPAM, will become default.
+**The DHCP object will not exist in v2 of the API**. It will no longer be possible to create or attach DHCP objects to Gateway Networks. Instead, IPAM configuration, where auto-configuration of `GatewayNetwork` is managed by IPAM, will become default, and replace any need for DHCP configuration via the Public Gateway.
+
+For legacy gateways using the DHCP object for custom DHCP configuration, **no automatic migration of this DHCP functionality** will take place when the gateway moves into IPAM-mode. We expect users to move to the standard set-up of IPAM and Private Networks for DHCP and private IP assignment.
 
 ### Deprecation of the address field
 
+This functionality was 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](https://www.scaleway.com/en/developers/api/public-gateway/#path-gateway-networks-attach-a-public-gateway-to-a-private-network)) via the API, you can use the `address` field to define a single static IP address to assign to the Public Gateway on that Private Network.
 
-This functionality will be deprecated going forward. Instead, you can pass an `ipam_ip_id` to specify a reserved IP address to use for the Public Gateway on this Private Network, if you wish. Otherwise, IPAM will auto-assign an IP address from the Private Network's CIDR block to the Public Gateway.
+**The `address` field will not exist in v2 of the API**. Instead, you can pass an `ipam_ip_id` to specify a reserved IP address to use for the Public Gateway on this Private Network, if you wish. Otherwise, IPAM will auto-assign an IP address from the Private Network's CIDR block to the Public Gateway.
+
+TODO: will we automatically take care of this when legacy gateways transition to IPAM mode?
 
 ### Deprecation of DHCP entries
 
+This functionality was available via the API and developer tools only (not the Scaleway console).
+
 [DHCP entries](https://www.scaleway.com/en/developers/api/public-gateway/#path-dhcp-entries-list-dhcp-entries) belong to a specified `GatewayNetwork` (Public Gateway / Private Network attachment) and can hold dynamic DHCP leases or static, user-created DHCP reservations. They effectively allow the Public Gateway to assign certain IP addresses to certain resources on the Private Network.
 
-DHCP entries will be deprecated going forward. Instead, you can rely on the default IPAM/DHCP functionality as described [above](#background-dhcp-and-ipam). 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.
+**DHCP entries will not exist in v2 of the API**. Instead, you can rely on the default IPAM/DHCP functionality as described [above](#background-dhcp-and-ipam). 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, you can use the IPAM API's [Attach IP to custom resource](https://www.scaleway.com/en/developers/api/ipam/#path-ips-attach-ip-to-custom-resource) method to assign IP addresses on Private Networks. This lets you associate a [reserved IP](https://www.scaleway.com/en/developers/api/ipam/#path-ips-reserve-a-new-ip) address with a resource name and MAC address.
 
+We will automatically migrate any existing DHCP entries to IPAM for you, at the moment you put a legacy Public Gateway into IPAM mode by detaching it and reattaching it from/to its Private Network.
+
+### SSH bastion allowed IPs
+
+TODO
+
 ## Deprecation and removal timeline
 
-The Public Gateway v1 API will be deprecated on [TODO-DATE. OR JUST CERTAIN FIELDS/OBJECTS 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.
+1. [TODO-DATE] **V1 deprecation**: The Public Gateway v1 API will be 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.
+2. [TODO-DATE] **V2 release**: The Public Gateway v2 API will be released, co-existing with v1. 
+
+    <Message type="note">
+    You will be able to list and manage both v1 and v2 Gateways with the **Scaleway console**. However, all new Public Gateways created via the console after [TODO-DATE] will necessarily be v2 gateways.
+    </Message>
 
-We will release v2 of the Public Gateway API on [TODO-DATE - SAME DATE?]. During the period that both versions of the API co-exist, you must migrate your resources from v1 to v2.
+3. [TODO-DATE - TODO-DATE] **Migration period**: You have a six month migration period to complete the following actions
 
-[TODO - INSERT INFORMATION ON HOW TO MIGRATE]
+    - Ensure that your Public Gateway is in [IPAM-mode](/network/public-gateways/concepts/#ipam). Only IPAM-mode gateways are compatible with v2.
+    - Put any non-IPAM mode ([legacy](/network/public-gateways/concepts/#ipam)) Public Gateways in IPAM-mode, by **detaching them and reattaching them to their Private Networks**.
+    - Ensure that [DHCP is activated](TODO) 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](link).
 
-[TODO - WHAT WILL THIS ALL LOOK LIKE IN THE CONSOLE? ]
+    If your Public Gateway is already in IPAM-mode, and you only manage it via the console, you will not be affected by this changes and you do not need to take any action.
 
-[TODO - DO USERS WHO DON'T USE LEGACY  / DHCP OBJECT / DHCP ENTRIES HAVE ANY ACTION TO TAKE?]
+4. [TODO-DATE] **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.
 
-After a period of [TODO - HOW LONG] weeks/months, v1 of the API will be removed. Any resources that have not been migrated to v2 by this time will cotinue to run, but can no longer be modified, nor recreated on the v1 API if they fail or are deleted. Any CLI, Terraform or other devtool scripts using v1 of the API will no longer function. 
+## FAQ
 
-[TODO - IF PGW ON V1 CRASHES, HOW IS IT RECREATED? Elle est remontée à l'identique (y compris basée sur des fonctionnalités dispos uniquement en v1) ? A confirmer.]
+TODO
 
 ## Further help and support