Skip to content

Commit 2fb9760

Browse files
RebeccaTamachiroRebeccaTamachiro
committed
Import changes based on initial Gdoc draft
1 parent 8810f50 commit 2fb9760

File tree

1 file changed

+180
-19
lines changed

1 file changed

+180
-19
lines changed

‎src/content/docs/byoip/get-started.mdx‎

Lines changed: 180 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,36 +5,197 @@ sidebar:
55
order: 2
66
---
77

8-
import { GlossaryTooltip } from "~/components";
8+
import { APIRequest, Tabs, TabItem } from "~/components";
99

10-
Work with your account team to understand everything you need to ensure a smooth transition during the onboarding process.
10+
Work with your account team to make sure your contract covers everything you need to onboard your prefix. Cloudflare requires service-specific configurations, as well as some requirements common to all BYOIP customers.
1111

12-
Cloudflare requires a service-specific configuration for your prefixes, as well as some requirements common to all BYOIP customers regardless of service type.
12+
Once your account configurations are in place, consider the sections below to learn how to set up your BYOIP prefixes.
1313

14-
## Requirements
14+
## Before you begin
1515

16-
The following requirements are common to all products compatible with BYOIP.
16+
* Verify that your [Internet Routing Registry (IRR)](/byoip/concepts/irr-entries/) records are up to date and contain:
1717

18-
You must verify that your [Internet Routing Registry (IRR)](/byoip/concepts/irr-entries/) records are up to date and contain:
18+
* `route` or `route6` objects matching the exact prefixes you want to onboard
19+
* `origin` matching the correct ASN you want to onboard
1920

20-
- `route` or `route6` objects matching the exact prefixes you want to onboard
21-
- `origin` matching the correct ASN you want to onboard
21+
:::note
22+
The process described on this page only supports using Cloudflare's ASN (AS13335). If you must announce the prefixes under your own ASN, contact your account team.
23+
:::
2224

23-
:::caution[RPKI validation]
24-
You are not required to use <GlossaryTooltip term="Resource Public Key Infrastructure (RPKI)">Resource Public Key Infrastructure (RPKI)</GlossaryTooltip>. However, if you do, make sure your <GlossaryTooltip term="Route Origin Authorization (ROA)">ROAs</GlossaryTooltip> are accurate. You can use [Cloudflare's RPKI Portal](https://rpki.cloudflare.com/?view=validator) and a second source such as [Routinator](https://rpki-validator.ripe.net/ui/) to double-check your prefixes.
25+
* You must use Resource Public Key Infrastructure (RPKI) validation and make sure your ROAs are accurate. You can use [Cloudflare's RPKI Portal](https://rpki.cloudflare.com/?view=validator) and a second source such as [Routinator](https://rpki-validator.ripe.net/ui/) to double-check your prefixes.
26+
27+
* If you are not familiar with how Cloudflare API works, refer to [Fundamentals](/fundamentals/api/). Make sure you have the necessary permissions and that you have your account ID.
28+
29+
## 1. Set up your prefixes
30+
31+
1. Use the [Add Prefix endpoint](/api/resources/addressing/subresources/prefixes/methods/create/) to create a prefix in the Cloudflare account that should own the BYOIP prefix.
32+
33+
(Add codeblock as example)
34+
35+
```json title="Response" {11,12}
36+
37+
"result": {
38+
"id": "72823e95d6c64d48a8111fec81179816",
39+
"created_at": "2025-02-25T00:34:11.423722Z",
40+
"modified_at": "2025-02-25T00:34:11.423722Z",
41+
"cidr": "1.255.115.0/24",
42+
"account_id": "654c5f71c324478cc9f68d60065d4620",
43+
"description": "",
44+
"approved": "P",
45+
"on_demand_enabled": false,
46+
"on_demand_locked": false,
47+
"advertised": null,
48+
"advertised_modified_at": null,
49+
"loa_document_id": null,
50+
"asn": 13335,
51+
"irr_validation_state": "pending",
52+
"rpki_validation_state": "pending"
53+
"prefix_ownership_validation": {
54+
"state" : "pending",
55+
"token": "<>",
56+
"delegate_loa_creation" : true
57+
}
58+
}
59+
60+
```
61+
62+
2. Validate prefix ownership using one of the following methods:
63+
64+
<Tabs> <TabItem label="Modify IRR record">
65+
66+
1. Copy the token returned by the API call.
67+
2. On the IRR record of the prefix you are onboarding, add the following string in either a `description` or `remarks` field. Replace `<TOKEN>` by the actual token you copied in the previous step.
68+
69+
```
70+
cf-validation: <TOKEN>
71+
```
72+
73+
:::note
74+
75+
The exact steps to update your IRR record will depend on the registry you are using. Refer to [Internet Routing Registry (IRR)](/byoip/concepts/irr-entries/) for details.
76+
77+
:::
78+
79+
</TabItem> <TabItem label="Reverse DNS zone and TXT record">
80+
81+
82+
1. Consider the size of the prefix you are bringing to Cloudflare. Since the standard `in-addr.arpa` tree assumes delegations on octet or nibble boundaries, if you onboard prefixes that are not aligned with those, you will have to split up the prefix into subnets and create the corresponding reverse DNS zones for each.
83+
84+
(Add calculation examples (collapsable))
85+
86+
2. Set up a reverse DNS zone. If you use Cloudflare for DNS, refer to [Reverse DNS zones](/dns/additional-options/reverse-zones/#set-up-a-reverse-zone). If you use a different DNS provider, follow their instructions.
87+
3. Create TXT records using `cf-validation` as their `name`. They should look like the following example:
88+
89+
90+
```
91+
cf-validation.<REVERSE_ZONE_ADDRESS> IN TXT <TOKEN>
92+
```
93+
94+
4. Update nameservers at your Regional Internet Registry (RIR).The exact steps to update your nameservers will depend on the registry you are using.
95+
96+
Once the ownership validation is successful, and if the RPKI and IRR validations also pass, the `approved` field in your prefix will return "V". This means you can proceed to create IP address service bindings[^1].
97+
98+
</TabItem> </Tabs>
99+
100+
3. (Optional) Use the [Prefix Details endpoint](/api/resources/addressing/subresources/prefixes/methods/get/) to check if any issues were found during validation. If so, proceed with the necessary changes and make a request to restart validation.
101+
<APIRequest path= "/accounts/{account_id}/addressing/prefixes/{prefix_id}" method="GET" />
102+
103+
(Add response example (collapsable))
104+
105+
(Add code block example)
106+
107+
4. (Optional) You can allow other accounts to use part or all of your BYOIP prefix. Refer to [Prefix delegations](/byoip/concepts/prefix-delegations/) for details.
108+
109+
<APIRequest
110+
path="/accounts/{account_id}/addressing/prefixes/{prefix_id}/delegations"
111+
method="POST"
112+
json={{
113+
"cidr":"<IP_PREFIX_TO_DELEGATE>",
114+
"delegated_account_id": "<ACCOUNT_ID>"
115+
}}
116+
/>
117+
118+
:::note
119+
Although you can delegate IPs to other accounts, the IP address service bindings are still created and managed on the parent account - meaning the Cloudflare account where you added the prefix in step 1.
120+
:::
121+
122+
## 2. Create a default service binding
123+
124+
When you onboard your IP prefixes to Cloudflare, there must be one service binding that spans across your entire prefix. Traffic destined for a given IP address will be routed to this service by default, unless you create an override binding.
125+
126+
:::note
127+
Magic Transit can only be used as default binding, spanning across your entire prefix. You can then override the Magic Transit binding with CDN or Spectrum for smaller subnets but not the other way around. For details refer to [scope](/byoip/service-bindings/#scope).
128+
:::
129+
130+
1. Make a `POST` request to the [Create service binding](/api/resources/addressing/subresources/prefixes/subresources/service_bindings/methods/create/) endpoint, indicating the entire BYOIP prefix that you are onboarding and the service that should be used for your default binding.
131+
132+
<APIRequest
133+
path="/accounts/{account_id}/addressing/prefixes/{prefix_id}/bindings"
134+
method="POST"
135+
json={{
136+
"cidr": "<ENTIRE_BYOIP_PREFIX>",
137+
"service_id": "<DEFAULT_SERVICE>"
138+
}}
139+
/>
140+
141+
A corresponding BGP prefix will be created automatically. Allow five hours before you advertise the prefix.
142+
143+
:::note
144+
For Magic Transit customers, the BGP prefix will be created in a `locked` state. Work with your account team to make sure it is unlocked after additional checks have passed.
145+
:::
146+
147+
### (Optional) Add override bindings
148+
149+
If you want to selectively route traffic on a per-IP address basis to CDN or Spectrum, you can create additional service bindings that will override the default one.
150+
151+
:::note
152+
The steps below only cover assigning specific IPs to additional services. For guidance that includes CDN or Spectrum setup steps, refer to [Service bindings](https://developers.cloudflare.com/byoip/service-bindings/).
25153
:::
26154

27-
## Process overview
155+
1. Plan for what IP(s) will get the additional binding. Cloudflare **strongly** recommends implementing service bindings through an **aggregated** CIDR block, as it is more efficient than adding discrete bindings for non-contiguous CIDR blocks.
156+
157+
(Add collapsable example similar to existing ones in the service bindings docs)
158+
159+
2. Make a `POST` request to the [Create service binding](/api/resources/addressing/subresources/prefixes/subresources/service_bindings/methods/create/) endpoint, indicating the IP address you want to bind to the CDN or Spectrum. Specify the **corresponding network mask** as needed.
160+
161+
<APIRequest path="/accounts/{account_id}/addressing/prefixes/{prefix_id}/bindings" method="POST"json={{ "cidr": "203.0.113.100/32", "service_id": "<SERVICE_ID>"}} code={{mark: [6, 7]}}/>
162+
163+
In the response body, the initial provisioning state should be `provisioning`.
164+
165+
166+
```json output {9}
167+
168+
{
169+
"errors": [],
170+
"messages": [],
171+
"success": true,
172+
"result": {
173+
"cidr": "203.0.113.100/32",
174+
"id": "<SERVICE_BINDING_ID>",
175+
"provisioning": {
176+
"state": "provisioning"
177+
},
178+
"service_id": "<SERVICE_ID>",
179+
"service_name": "<SERVICE_NAME>"
180+
}
181+
}
182+
```
183+
184+
Once a service binding is created (or deleted), it will take **four to six hours** to propagate across Cloudflare's global network.
185+
186+
## 3. Advertise the BGP prefix
187+
188+
Once created, BGP prefixes are initially withdrawn. After all your configurations are in place - including address maps[^2] if you will use CDN service -, proceed to advertise the BGP route for your prefix.
28189

29-
Overall, the steps can be summarized as follows:
190+
1. Use the [Update BGP prefix](/api/resources/addressing/subresources/prefixes/subresources/bgp_prefixes/methods/edit/) endpoint to start the advertisement.
30191

31-
1. You revise your [IRRs and ROAs](#requirements) (if applicable) to make sure they are correct.
32-
2. You prepare a [Letter of Agency (LOA)](/byoip/concepts/loa/) containing both the prefix you are authorizing Cloudflare to announce and which ASN they will be announced under. Cloudflare will present this to our transit partners as evidence that we are allowed to announce the route.
33-
3. You use the [Upload LOA Document](/api/resources/addressing/subresources/loa_documents/methods/create/) API endpoint to submit the letter under your account and the [Add Prefix](/api/resources/addressing/subresources/prefixes/methods/create/) endpoint to create the prefix in your account with the associated `loa_document_id`.
34-
4. After receiving the LOA, Cloudflare validates the [requirements](#requirements) and provisions the IPs.
35-
5. (Optional) You can use [prefix delegations](/byoip/concepts/prefix-delegations/) to share all or part of your prefix with another Cloudflare account.
36-
6. You use [service bindings](/byoip/service-bindings/)[^1] and [address maps](/byoip/address-maps/)[^2] to control how your IPs are used.
37-
7. You advertise or withdraw the BGP route for a prefix via the [BGP Prefixes API](/api/resources/addressing/subresources/prefixes/subresources/bgp_prefixes/).
192+
<APIRequest
193+
path="/accounts/{account_id}/addressing/prefixes/{prefix_id}/bgp/prefixes/{bgp_prefix_id}"
194+
method="PATCH"
195+
json={{
196+
"on_demand": {"advertised": true}
197+
}}
198+
/>
38199

39200
[^1]: Mappings that control through which pipeline traffic destined for a given IP address will be routed.
40201
[^2]: Mappings that specify which IP addresses should be used when Cloudflare responds to DNS queries for proxied hostnames.

0 commit comments

Comments
 (0)