[MT] Guidance on how to avoid blackholing prefixes bgp (#26708)

* added content

* changed to partial file

* added page

* refined text

* refined h2

Author: marciocloudflare

src/content/docs/magic-transit/how-to/advertise-prefixes.mdx

@@ -28,7 +28,7 @@ Provide all IP prefixes you plan to onboard, along with the ASNs from which they
 - When using Route Origin Authorizations (ROAs) to sign routes for [resource public key infrastructure (RPKI)](https://tools.ietf.org/html/rfc8210), the prefix and originating ASN must match the onboarding submission.
 - If you do not own an ASN, you can use the Cloudflare Customer ASN (AS13335).
 
-#### Choose between Cloudflare’s ASN and your ASN
+#### Choose between Cloudflare's ASN and your ASN
 
 As a part of your IP prefix onboarding process, you need to decide the ASN Cloudflare will use to announce your prefixes. If you supply your own ASN, Cloudflare prepends the main Cloudflare ASN (AS13335) to the BGP `AS_PATH`. For example, if your ASN is `AS64496`, anyone directly peering with Cloudflare sees the path as `13335 64496`.
 
@@ -108,6 +108,8 @@ Create a [POST request](/api/resources/addressing/subresources/prefixes/subresou
 
 :::caution[Warning: ISP route refresh delays may impact traffic]
 Announcing or withdrawing a prefix means Cloudflare will begin or stop advertising routes, impacting traffic flow to or from that IP range. Changes propagate across our global network almost instantly, typically taking effect within minutes. However, Cloudflare has no control over how quickly ISPs refresh their routes.
+
+Refer to [Safely withdraw a BYOIP prefix](#safely-withdraw-a-byoip-prefix) for more information on how to prevent blackholing during prefix withdrawals.
 :::
 
 ### Delete an IP prefix
@@ -149,6 +151,10 @@ For traffic originated from Cloudflare's services, Cloudflare's internal network
 For example, if you have a CDN zone onboarded with a Magic Transit-protected origin that is part of a Cloudflare-advertised `/22` prefix, and you later opt to advertise a more specific and shorter `/24` prefix route directly from your network, Cloudflare's servers will continue to route proxied CDN traffic to your Magic Transit network, which will follow configured routes to your tunnel(s). This is specific to Cloudflare services: traffic from other sources will converge as expected by BGP to the direct route, because it is the most specific.
 :::
 
+## Safely withdraw a BYOIP prefix
+
+<Render file="magic-transit/safely-withdraw-byoip-prefix" product="networking-services" />
+
 ## BGP control to Magic routing table
 
 ### Automatically announce and withdraw anycast-based Magic BGP routes

src/content/docs/magic-transit/how-to/enable-magic-roles.mdx

@@ -4,7 +4,6 @@ title: Enable Magic user roles
 head: []
 description: You can determine which users have, or do not have, configuration
   edit access for Magic products.
-
 ---
 
 import { Render } from "~/components"

src/content/docs/magic-transit/how-to/safely-withdraw-byoip-prefix.mdx

@@ -0,0 +1,10 @@
+---
+pcx_content_type: how-to
+title: Safely withdraw a BYOIP prefix
+sidebar:
+  order: 6
+---
+
+import { Render } from "~/components"
+
+<Render file="magic-transit/safely-withdraw-byoip-prefix" product="networking-services" />

src/content/partials/networking-services/magic-transit/safely-withdraw-byoip-prefix.mdx

@@ -0,0 +1,25 @@
+---
+{}
+---
+
+### Mitigating stuck BGP routes
+
+When you prepare to remove traffic for a [Bring Your Own IP (BYOIP)](/byoip/) prefix from the Cloudflare edge, a direct BGP withdrawal action carries the risk of a stuck BGP route. This state occurs when a route becomes stuck in the Internet's [Default-Free Zone (DFZ)](https://en.wikipedia.org/wiki/Default-free_zone), meaning core routers that missed the withdrawal announcement continue forwarding traffic to a now-inactive next-hop (what is know as the blackhole). You can read more on this in our blog post [BGP zombies and excessive path hunting](https://blog.cloudflare.com/going-bgp-zombie-hunting).
+
+This risk is especially evident in the use case where the global routing table relies on more-specific to less-specific prefix routing fallback. Since this fallback mechanism is highly prone to route instability, Cloudflare recommends a multi-step draining process.
+
+### Multi-step BYOIP withdrawal process
+
+When draining traffic, use the same prefix length on Cloudflare and on your ISP, since matching prefix lengths gives the most effective and deterministic behavior.
+
+The following steps outline the recommended multi-step draining process to achieve a clean traffic cutover and prevent blackholing.
+
+1. **Initiate advertisement from your origin network**: Begin announcing the exact same-length prefix (for example, `192.0.2.0/24`) from your local infrastructure to your upstream Internet Service Providers (ISPs). This action introduces a competing route of the same length into the global routing table. BGP best path selection will favor your native route based on other metrics (for example, shorter AS path length or local preference), allowing traffic to begin draining away from the Cloudflare edge. Note that some of your traffic may not route as expected, since this depends on how your ISP prefers routes (for example, the Cloudflare route may be treated as a less-preferred path if not fully withdrawn).
+2. **Wait for global BGP convergence**: Allow a period of time (typically five to ten minutes) for the new native advertisement to propagate fully across the global routing table, and for routes to converge. This passive waiting period ensures that the majority of traffic has shifted to your local network before the next step.
+3. **Signal BGP withdrawal from the Cloudflare edge**: Once you have verified that traffic has successfully drained, use one of the BGP control methods to stop the advertisement of the prefix from the Cloudflare edge.
+
+	:::caution[ISP route refresh delays may impact traffic]
+	Cloudflare's action to withdraw the route is near-instantaneous across our global network. However, Cloudflare has no control over how quickly external ISPs refresh their BGP tables after the withdrawal.
+	:::
+
+4. The draining process is complete.