[MT] Advertise prefixes

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

@@ -5,75 +5,148 @@ sidebar:
   order: 5
 ---
 
-import { Details, GlossaryTooltip } from "~/components"
+import { APIRequest, Details, GlossaryTooltip, Render, Tabs, TabItem } from "~/components"
 
-Cloudflare measures the Magic Transit prefix count based on the number of <GlossaryTooltip term="prefix">prefixes</GlossaryTooltip> a customer onboards. The size of each prefix does not matter — there are no commercial or technical restrictions based on prefix length. However, prefixes must be announced exactly as they were provisioned. For example, if a customer onboards a `/20` prefix to Magic Transit, it can only be announced as a `/20`. Smaller sub-prefixes (such as `/24s`) within that `/20` cannot be announced individually unless they are onboarded separately. Onboarding a larger aggregate prefix does not automatically include its smaller subnets for announcement or billing purposes.
+## Onboard prefixes
 
-If a customer wants to announce 16 individual `/24` prefixes that fall within a `/20`, they must onboard all 16 `/24s` as distinct prefixes, in addition to the `/20` if desired. In such a disaggregated setup, the total Magic Transit prefix count increases, as each onboarded prefix — including any sub-prefixes — is treated as a separate billable unit.
+You can bring your own public IPs to Cloudflare to use with Magic Transit. This is a two-step process:
 
-Provide all IP prefixes you plan to onboard, along with the [Autonomous System Numbers (ASNs)](https://www.cloudflare.com/learning/network-layer/what-is-an-autonomous-system/) from which they will be advertised. When specifying prefixes, observe these guidelines:
+1. Adding IP <GlossaryTooltip term="prefix">prefixes</GlossaryTooltip> for each IP address block that you bring to Cloudflare. The IP prefix includes the permission (<GlossaryTooltip term="letter of agency">Letter of Agency or LOA</GlossaryTooltip>) that allows Cloudflare to announce the network or its subnets. The IP prefix is also where you define your optional [Autonomous System Number (ASN)](https://www.cloudflare.com/learning/network-layer/what-is-an-autonomous-system/) to be included in Cloudflare's advertised AS path.
+2. Defining additional BGP prefixes, which control the announcement of the prefix from Cloudflare. By default there is always one BGP prefix that is identical to the IP prefix. You can optionally configure additional, more-specific BGP prefixes (subnets of the IP prefix), up to a maximum prefix length of `/24`.
+
+### IP prefixes
+
+Cloudflare measures the Magic Transit prefix count based on the number of BGP prefixes a customer defines. Each prefix is billed separately, even if they overlap. For example, both a `/16` and any `/24` within it are counted individually. Onboarding a larger aggregate prefix does not automatically include its smaller subnets for announcement or billing purposes.
+
+While there is no billing limit on the accepted prefix sizes, technically only prefixes up to `/24` are accepted for onboarding, as longer ones (like `/25`, `/26`) are not globally routable.
+
+Provide all IP prefixes you plan to onboard, along with the ASNs from which they will be advertised. When specifying prefixes, observe these guidelines:
 
 - Prefixes must support at least 256 hosts (`/24` in classless inter-domain [routing](https://www.cloudflare.com/learning/network-layer/what-is-routing/) CIDR notation). Refer to [Use a Cloudflare IP](/magic-transit/cloudflare-ips/) if you do not meet the `/24` prefix length requirement.
-- Internet Routing Registry entries and <GlossaryTooltip term="letter of agency">Letters of Agency (LOA)</GlossaryTooltip> must match the prefixes and originating prefixes you submit to Cloudflare.
+- Internet Routing Registry entries and Letters of Agency (LOA) must match the prefixes and originating prefixes you submit to Cloudflare.
 - When using contiguous prefixes, specify aggregate prefixes where possible.
 - 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).
-- Prefixes using BGP-controlled advertisements cannot be used in conjunction with dynamic advertisement (via dashboard/API). Please specify your preferred on-demand advertisement method during the prefix onboarding.
-
-<Details header="Prefix configuration example">
 
-| Prefix            | Originating AS |
-| ----------------- | -------------- |
-| `103.21.244.0/23` | AS13335       |
-| `131.0.72.0/22`   | AS395747       |
-| `103.21.245.0/24` | AS395747       |
+#### Cloudflare ASN vs. your own ASN
 
-</Details>
-
-## Cloudflare ASN vs. your own ASN
-
-As a part of your 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`.
+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`.
 
 If you do not have an ASN or do not want to bring your ASN to Cloudflare, you can use the Cloudflare Customer ASN (AS13335).
 
 :::note
 For all future onboardings, you must use AS13335. Current customers who are already using Cloudflare's AS209242 do not need to make any changes and can continue using that ASN.
 :::
 
-## Advertise or withdraw a prefix
+### BGP prefixes
 
-:::note
-You can only advertise your prefix [after running pre-flight checks](/magic-transit/get-started/#5-run-pre-flight-checks) with Cloudflare. If your prefix status is greyed out and shows an _Withdrawn_ status, your prefix is locked. Contact your account team to close the pre-flight checks phase with you and unlock your prefixes.
+BGP prefixes represent the prefix that will be announced through anycast from Cloudflare's global network. By default there is always at least one BGP prefix that is identical to the onboarded IP prefix.
+
+For example, if a customer onboards a `/20` IP prefix to Magic Transit, it can only be announced as a `/20` because there is only the default `/20` BGP prefix. Smaller sub-prefixes (such as `/24s`) within that `/20` cannot be announced individually unless they are configured as separate BGP prefixes.
+
+Note that for billing purposes, Cloudflare measures the Magic Transit prefix count based on the number of BGP prefixes a customer defines.
+
+### BGP prefix advertisement control methods
+
+Cloudflare offers multiple mechanisms for customers to control the announcement and withdrawal of on-demand prefixes. Customers can choose to manage advertisements through one of the following methods:
+
+- The [Addressing API](/api/resources/addressing/subresources/prefixes/subresources/bgp_prefixes/methods/edit/).
+- BGP peering with Cloudflare's route reflectors: Either over the Internet or over a Classic CNI connection. Contact your Cloudflare account team if you need this option.
+- [Magic Network Monitoring](/magic-network-monitoring/): Dynamically announces prefixes based on user-defined traffic thresholds observed in your network.
+
+:::caution[Important]
+You should only use one control method per prefix at any given time. Mixing multiple control planes can lead to conflicting advertisement states, causing unpredictable routing behavior.
 :::
 
-1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account.
-2. Go to **Magic Transit** > **Configuration**.
-3. From **IP Prefixes** tab, select the prefix you want to modify > **Edit**.
-4. From the dropdown menu **Status**, choose weather the status of your IP is _Advertised_ or _Withdrawn_.
-5. _(Optional)_ Edit the description for your prefix.
-6. Select **Edit IP Prefix** to save your changes.
+## Manage BGP prefixes
+
+### Add a BGP prefix
+
+Create a [POST request](/api/resources/addressing/subresources/prefixes/subresources/bgp_prefixes/methods/create/) to add a BGP prefix. For example:
+
+<APIRequest
+  path="/accounts/{account_id}/addressing/prefixes/{prefix_id}/bgp/prefixes"
+  method="POST"
+  json={{
+    "cidr": "192.0.2.0/24"
+  }}
+/>
+
+### Advertise or withdraw a BGP prefix
 
-## Edit the status of a prefix
+<Tabs syncKey="dashPlusAPI">
 
-1. Go to **Magic Transit** > **Configuration**.
-2. From the **IP Prefixes** tab, locate the prefix you want to modify.
-3. Select the three dots in front of the IP prefix > **Delete**.
-4. Confirm your choice from the modal by selecting **Delete**.
+  <TabItem label="Dashboard">
+		:::note
+		You can only advertise your prefix after running pre-flight checks with Cloudflare. If your prefix status is greyed out and shows an Withdrawn status, your prefix is locked. Contact your account team to close the pre-flight checks phase with you and unlock your prefixes.
 
-To avoid latency and potentially dropped routes, enable prefix advertisement from Cloudflare before withdrawing the advertisement from your data center.
+		Currently only the default BGP prefix (that matches the IP prefix) can be controlled via the UI.
+		:::
 
-You should also be aware that announcing or withdrawing a prefix should propagate across Cloudflare's global network almost instantly, with changes typically taking effect within a few minutes at most. However, Cloudflare has no control over how long ISPs take to refresh their routes. Keep this in mind when announcing or withdrawing a prefix from your account, and plan accordingly.
+		1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account.
+		2. Go to **Magic Transit** > **Configuration**.
+		3. From the **IP Prefixes** tab, select the prefix you want to modify > **Edit**.
+		4. From the dropdown menu **Status**, choose weather the status of your IP is **Advertised** or **Withdrawn**.
+		5. (Optional) Edit the description for your prefix.
+		6. Select **Edit IP Prefix** to save your changes.
+  </TabItem>
 
-## Delete a prefix
+  <TabItem label="API">
+		Any configured BGP prefix can be controlled via the API using a [PATCH request](/api/resources/addressing/subresources/prefixes/subresources/bgp_prefixes/methods/edit/). For example:
+
+	<APIRequest
+  path="/accounts/{account_id}/addressing/prefixes/{prefix_id}/bgp/prefixes/{bgp_prefix_id}"
+  method="PATCH"
+  json={{
+    "on_demand":{ "advertised": "true" }
+  }}
+	/>
+  </TabItem>
+
+</Tabs>
+
+:::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.
+:::
+
+### Delete an IP prefix
 
 You can only delete a prefix with an **Unapproved** status. To delete prefixes with a different status, contact your administrator or account manager.
 
 1. From the **IP Prefixes** tab, locate the prefix you want to modify and select **Delete**.
 2. Confirm your choice from the modal by selecting **Delete**.
 
-## Border Gateway Protocol (BGP) control for advertisements (optional)
+### Use the API to set AS prepends on a BGP prefix
+
+Use the [Addressing API](/api/resources/addressing/subresources/prefixes/subresources/bgp_prefixes/methods/edit/) to control the number of times Cloudflare prepends its Autonomous System Number (ASN) to a prefix. You can prepend AS13335 up to three times in the `AS_PATH` of BGP updates for your prefixes. For example:
+
+<APIRequest
+path="/accounts/{account_id}/addressing/prefixes/{prefix_id}/bgp/prefixes/{bgp_prefix_id}"
+method="PATCH"
+json={{
+	"asn_prepend_count": 3
+}}
+/>
+
+AS prepending helps you gracefully transition traffic between network providers. By adding prepends to Cloudflare's advertisement, you make the route through Cloudflare less preferred for some Internet network providers. This allows you to simultaneously advertise the same prefix from an alternate provider with a shorter, more desirable `AS_PATH`. Advertising from both providers at once can provide a smoother traffic migration and minimize packet loss during a change of provider.
+
+The `"asn_prepend_count"` parameter accepts values from `0` to `3`. A higher value makes the route less preferred.
+
+When you use AS prepending to migrate traffic away from Magic Transit, the typical sequence of events is as follows:
+
+- **Initial state**: Cloudflare advertises your prefix with the default priority (`"asn_prepend_count": 0`). All traffic is routed to your network through the Cloudflare global network.
+- **Deprioritize Cloudflare**: You update the prefix via the API to set an AS prepend count (for example, `"asn_prepend_count": 3`). Cloudflare now advertises your prefix with a longer `AS_PATH`. External networks will update their BGP tables to recognize the Cloudflare path has the new, longer `AS_PATH`.
+- **Introduce new provider**: You begin advertising the same prefix from your alternate provider with a standard (shorter) `AS_PATH`.
+- **Final state**: External networks now receive two advertisements: the prepended route through Cloudflare and the non-prepended route through your new provider. The external network will select a path based on its BGP policy rules.
+
+:::caution
+BGP has different mechanisms to control route priorities which are set by the peered network, not by Cloudflare. As such, this is a best effort feature. Cloudflare cannot guarantee that peers will honor AS prepends on Cloudflare's transit and peering connections.
+:::
+
+## BGP control with Cloudflare Route Reflectors
+
+Optionally, you can use BGP to control the advertisement status of your prefix — advertised or withdrawn — from Cloudflare's global network for on-demand deployment scenarios. BGP Control works by establishing BGP sessions to Cloudflare's globally distributed Route Reflectors, which will initiate propagation of your prefix advertisement across Cloudflare's global network. You can peer with Cloudflare's Route Reflectors via Internet or CNI. CNI peering is available through your account team.
 
-Optionally, you can use BGP to control the advertisement status of your prefix — advertised or withdrawn — from Cloudflare's global network for on-demand deployment scenarios. BGP Control works by establishing BGP sessions to Cloudflare's globally distributed Route Reflectors, which will initiate propagation of your prefix advertisement across Cloudflare's global network.
 
 Prefixes can be advertised from Cloudflare's network in a supported on-demand method such as BGP Control, or dynamically via the UI, API, or [Magic Network Monitoring](/magic-transit/magic-network-monitoring/). During the onboarding of your on-demand prefixes, please specify whether you want BGP-controlled advertisement or dynamic advertisement (via dashboard/API/Magic Network Monitoring).
 
@@ -89,16 +162,17 @@ After receiving your information, Cloudflare will update firewall filters to est
 When you withdraw a prefix using BGP, you must ensure the prefix is withdrawn across all BGP sessions on all route reflectors. Otherwise, your prefix will not be withdrawn from Cloudflare's global network.
 :::
 
-### BGP peering
+### Regional settings
 
-If you use Direct CNI as a way to on-ramp your network traffic to Magic Transit, refer to [BGP information](/magic-transit/reference/traffic-steering/#bgp-information) to learn how to use BGP to handle traffic routing between Cloudflare and your network. Note that this is a different option to using BGP as a means to control the advertisement status of your prefix.
+Magic Transit requires static routing to steer traffic from Cloudflare's network over one of your configured tunnel off-ramps (for GRE and IPsec tunnels). For CNI, both static routing and BGP options are available. Currently, advertisement of routes for traffic engineering purposes is not supported. As a best practice to reduce last-hop latency, you should consider scoping your routes regionally.
 
+<Render file="traffic-steering-region-codes" product="networking-services/reference" />
 
-### Regional settings
+The default setting for static route regions is **All Regions**. Configure scoping for your traffic in the **Region code** section when [adding](/magic-transit/how-to/configure-routes/#create-a-static-route) or [editing](/magic-transit/how-to/configure-routes/#edit-a-static-route) a static route.
 
-Magic Transit requires static routing to steer traffic from Cloudflare's network over one of your configured tunnel off-ramps (for GRE and IPsec tunnels). For CNI, both static routing and BGP options are available. Currently, advertisement of routes for traffic engineering purposes is not supported. As a best practice to reduce last-hop latency, you should consider scoping your routes regionally. The default setting for static route regions is **All Regions**. Refer to [Scoping routes to specific regions](/magic-transit/reference/traffic-steering/#scoping-routes-to-specific-regions) for more information.
+Refer to [Scoping routes to specific regions](/magic-transit/reference/traffic-steering/#scoping-routes-to-specific-regions) for more information.
 
-## Example router configurations
+### Example router configurations
 
 Below you can find example peering configurations for [Cisco IOS](https://www.cisco.com/c/en/us/td/docs/ios/fundamentals/command/reference/cf_book.html) and [Juniper Junos OS](https://www.juniper.net/documentation/us/en/software/junos/cli/index.html) for on-demand deployments leveraging BGP Control. The IP addresses used are from Cloudflare's route reflectors and should be left as is.
 
@@ -177,4 +251,4 @@ neighbor 173.245.63.66 {
 neighbor 141.101.67.22 {
     description "CF RR#3 CDG";
 }
-```
+```

src/content/partials/networking-services/reference/traffic-steering-region-codes.mdx

@@ -0,0 +1,17 @@
+---
+{}
+---
+
+Cloudflare has nine geographic regions across the world which are listed below.
+
+| Region code | Region |
+| ----- | ----- |
+| `AFR` | Africa |
+| `APAC` | Asia Pacific |
+| `EEUR` | Eastern Europe |
+| `ENAM` | Eastern North America |
+| `ME` | Middle East |
+| `OC` | Oceania |
+| `SAM` | South America |
+| `WEUR` | Western Europe |
+| `WNAM` | Western North America |

src/content/partials/networking-services/reference/traffic-steering.mdx

@@ -162,19 +162,7 @@ When there are multiple routes to the same prefix with equal priority, and those
 
 ### Region codes and associated regions
 
-Cloudflare has nine geographic regions across the world which are listed below.
-
-| Region code | Region |
-| ----- | ----- |
-| `AFR` | Africa |
-| `APAC` | Asia Pacific |
-| `EEUR` | Eastern Europe |
-| `ENAM` | Eastern North America |
-| `ME` | Middle East |
-| `OC` | Oceania |
-| `SAM` | South America |
-| `WEUR` | Western Europe |
-| `WNAM` | Western North America |
+<Render file="traffic-steering-region-codes" product="networking-services/reference" />
 
 Configure scoping for your traffic in the **Region code** section when adding or editing a static route. Refer to <a href={props.createStaticRoute}>Create a static route</a> and <a href={props.editStaticRoute}>Edit a static route</a> more information.