fix(pgw): add v2 prep doc

Author: RoRoJ

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

@@ -19,7 +19,7 @@ This document explains what to expect and how to prepare for the upcoming change
 
 ## Background: DHCP and IPAM
 
-When Public Gateways were originally introduced, they provided DHCP functionality for resources on attached Private Networks. With the [arrival of Scaleway VPC](/network/vpc/reference-content/vpc-migration/), DHCP was moved from Public Gateways to Private Networks themselves.
+When Scaleway originally introduced Public Gateways, they provided DHCP functionality for resources on attached Private Networks. With the [arrival of Scaleway VPC](/network/vpc/reference-content/vpc-migration/), DHCP was moved from Public Gateways to Private Networks themselves.
 
 Scaleway also introduced [IPAM](/network/ipam/concepts/#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. 
 
@@ -31,33 +31,71 @@ Whether you choose a custom or default CIDR block, automatic address assignment
 
 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](https://www.scaleway.com/en/developers/api/public-gateway/), which has until now retained a number of legacy DHCP functions. From this new version, you can expect:
 
+- IPAM mode becomes default
 - Deprecation of the DHCP object
-- IPAM mode becoming default
+- Deprecation of the `address` field
 - Deprecation of DHCP entries
 
 Read on to find out more.
 
+### IPAM mode becomes default
+
+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](https://console.scaleway.com/public-gateway/public-gateways)
+- Checking the value of the `is_legacy` field via the [Public Gateways API](https://www.scaleway.com/en/developers/api/public-gateway/#path-gateways-get-a-public-gateway).
+
+<Message type="tip">
+All Public Gateways created via the Scaleway console since 17 October 2023 are necessarily in IPAM mode.
+</Message>
+
+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.
+
 ### 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 IP addresses should be assigned to devices on attached Private Networks (parameters including the subnet of the DHCP server, entry validity period and more).
+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.
+
+### Deprecation of the `address` field
+
+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.
+
+### Deprecation of DHCP entries
+
+[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.
 
-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 could either:
-- Pass a DHCP object
-- Pass a static IP address to use
+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.
 
+## 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.
 
+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.
 
-These objects define a DHCP configuration, i.e. how IP addresses should be assigned to devices on a Private Network attached to a Public Gateway. Definable parameters include the subnet for the DHCP server, the validity period for DHCP entries, whether to use dynamic pooling, and more. A DHCP configuration object has a DHCP ID, which can then be used as part of a call to create or update a Gateway Network. This lets you attach an existing DHCP configuration to a Public Gateway attached to a Private Network. Similarly, you can use a DHCP ID as a query parameter to list Gateway Networks which use this DHCP configuration object.
+[TODO - INSERT INFORMATION ON HOW TO MIGRATE]
 
+[TODO - WHAT WILL THIS ALL LOOK LIKE IN THE CONSOLE? 
 
+[TODO - DO USERS WHO DON'T USE LEGACY  / DHCP OBJECT / DHCP ENTRIES HAVE ANY ACTION TO TAKE?]
 
+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 [TODO - WHAT WILL HAPPEN TO THEM?]
 
-The NetProdCore will release a new version of the PGW API, deprecating DHCP entries, DHCP object and setting the IPAM mode as the new default mode when creating a PGW.
+## Further help and support
 
-We will need a documentation page explaining:
+If you have any questions, get in touch with us on the `#public-gateway` channel on the [Scaleway Slack Community](https://www.scaleway.com/en/docs/tutorials/scaleway-slack-community/), or [open a support ticket](https://console.scaleway.com/support/tickets/create).
 
-    why we will deprecate the old API
-    what will be the impacts for the customers
-    how can they migrate to the new API (using some TF examples that DevTools will provide)
+The following documentation resources may be useful to you:
 
+- [Public Gateway API Documentation](https://www.scaleway.com/en/developers/api/public-gateway/)
+- [Public Gateway Main Documentation](https://www.scaleway.com/en/docs/network/public-gateways/)
+- [IPAM API Documentation](https://www.scaleway.com/en/developers/api/ipam/)
+- [IPAM Main Documentation](https://www.scaleway.com/en/docs/network/ipam/)