Skip to content

Commit 3a070fb

Browse files
marciocloudflarehyperlint-ai[bot]
marciocloudflare
and
hyperlint-ai[bot]
authored
[Magic] Continues work for APIRequest (#20817)
* removed unnecessary sentence * added apirequest * removed old example * added example response * removed unnecessary sentence * added api request * deleted old example * updated example response * indented content * more details * psk create * added create psk * refined output examples * added new var * added curl * removed old example * added response example * corrected var * added curl * aded curl example * removed old example * Update src/content/partials/magic-transit/tunnel-endpoints/add-tunnels.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --------- Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>
1 parent 73d7183 commit 3a070fb

File tree

4 files changed

+230
-116
lines changed

4 files changed

+230
-116
lines changed

‎src/content/docs/magic-transit/how-to/configure-tunnels.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,8 +58,9 @@ import { GlossaryTooltip, Render } from "~/components";
5858
healthCheck: "/magic-transit/how-to/tunnel-health-checks/",
5959
productPathProbe: "/magic-transit/reference/tunnel-health-checks/",
6060
antiReplayPagePath: "/magic-transit/reference/anti-replay-protection/",
61-
BiVsUniHealthCheck: "unidirectional",
61+
biVsUniHealthCheck: "unidirectional",
6262
tunnelHealthDash: "/magic-transit/how-to/check-tunnel-health-dashboard/",
63+
biVsUniHealthCheckDefaults: "For Magic Transit this option defaults to unidirectional"
6364
}}
6465
/>
6566

‎src/content/docs/magic-wan/configuration/manually/how-to/configure-tunnels.mdx‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -63,13 +63,12 @@ import { GlossaryTooltip, Render } from "~/components";
6363
params={{
6464
productName: "Magic WAN",
6565
productPathDash: "Magic WAN > Configuration",
66-
healthCheck:
67-
"/magic-wan/configuration/common-settings/tunnel-health-checks/",
66+
healthCheck: "/magic-wan/configuration/common-settings/tunnel-health-checks/",
6867
productPathProbe: "/magic-wan/reference/tunnel-health-checks/",
6968
antiReplayPagePath: "/magic-wan/reference/anti-replay-protection/",
70-
BiVsUniHealthCheck: "bidirectional",
71-
tunnelHealthDash:
72-
"/magic-wan/configuration/common-settings/check-tunnel-health-dashboard/",
69+
biVsUniHealthCheck: "bidirectional",
70+
tunnelHealthDash: "/magic-wan/configuration/common-settings/check-tunnel-health-dashboard/",
71+
biVsUniHealthCheckDefaults: "For Magic WAN this option defaults to bidirectional"
7372
}}
7473
/>
7574

‎src/content/partials/magic-transit/tunnel-endpoints/add-tunnels.mdx‎

Lines changed: 212 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,12 @@ params:
55
- healthCheck
66
- productPathProbe
77
- antiReplayPagePath
8-
- BiVsUniHealthCheck
8+
- biVsUniHealthCheck
99
- tunnelHealthDash
10+
- biVsUniHealthCheckDefaults
1011
---
1112

12-
import { Details, Markdown, Render, TabItem, Tabs } from "~/components";
13+
import { APIRequest, CURL, Details, Markdown, Render, TabItem, Tabs } from "~/components";
1314

1415
<Render file="icmp-mfirewall" product="magic-transit" />
1516

@@ -81,131 +82,243 @@ import { Details, Markdown, Render, TabItem, Tabs } from "~/components";
8182

8283
<Details header="GRE tunnel">
8384

84-
Create a `POST` request [using the API](/api/resources/magic_transit/subresources/gre_tunnels/methods/create/) to create a GRE tunnel. You will need your [API Key](/fundamentals/api/get-started/keys/#view-your-global-api-key).
85+
Create a `POST` request [using the API](/api/resources/magic_transit/subresources/gre_tunnels/methods/create/) to create a GRE tunnel.
8586

86-
Example:
87+
<APIRequest
88+
path="/accounts/{account_id}/magic/gre_tunnels"
89+
method="POST"
90+
json={{
91+
"name": "<TUNNEL_NAME>",
92+
"description": "<TUNNEL_DESCRIPTION>",
93+
"interface_address": "<INTERFACE_ADDRESS>",
94+
"cloudflare_gre_endpoint": "<CLOUDFLARE_ENDPOINT>",
95+
"customer_gre_endpoint": "<CUSTOMER_ENDPOINT>"
96+
}}
97+
/>
8798

88-
```bash
89-
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/gre_tunnels \
90-
--header "X-Auth-Email: <EMAIL>" \
91-
--header "X-Auth-Key: <API_KEY>" \
92-
--header "Content-Type: application/json" \
93-
--data '{
94-
"gre_tunnels": [
99+
```json output
100+
{
101+
"errors": [
95102
{
96-
"name": "<TUNNEL_NAME>",
97-
"description": "<TUNNEL_DESCRIPTION>",
98-
"interface_address": "<INTERFACE_ADDRESS>",
99-
"cloudflare_gre_endpoint": "<CLOUDFLARE_ENDPOINT>",
100-
"customer_gre_endpoint": "<CUSTOMER_ENDPOINT>"
103+
"code": 1000,
104+
"message": "message"
105+
}
106+
],
107+
"messages": [
108+
{
109+
"code": 1000,
110+
"message": "message"
101111
}
102-
]
103-
}'
112+
],
113+
"result": {
114+
"gre_tunnels": [
115+
{
116+
"cloudflare_gre_endpoint": "<IP_ADDRESS>",
117+
"customer_gre_endpoint": "<IP_ADDRESS>",
118+
"interface_address": "<INTERFACE_CIDR>",
119+
"name": "<TUNNEL_NAME>",
120+
"description": "<TUNNEL_DESCRIPTION>",
121+
"health_check": {
122+
"direction": "unidirectional",
123+
"enabled": true,
124+
"rate": "low",
125+
"type": "reply"
126+
},
127+
"mtu": 0,
128+
"ttl": 0
129+
}
130+
]
131+
},
132+
"success": true
133+
}
104134
```
105135

106136
</Details>
107137

108138
<Details header="IPsec tunnel">
109139

110-
1. Create a `POST` request [using the API](/api/resources/magic_transit/subresources/ipsec_tunnels/methods/create/) to create an IPsec tunnel. You will need your [API Key](/fundamentals/api/get-started/keys/#view-your-global-api-key).
111-
112-
Note that in example below, replay protection is disabled by default. You can enable it with the flag `"replay_protection": true` for each IPsec tunnel, if the devices you use do not support disabling this feature. If you have already created IPsec tunnels, update them with a [`PUT` request](https://developers.cloudflare.com/api/resources/magic_transit/subresources/ipsec_tunnels/methods/update/). <br/> Refer to <a href={props.antiReplayPagePath}>Anti-replay protection</a> for more information on this topic.
113-
114-
Example:
115-
116-
```bash
117-
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/ipsec_tunnels \
118-
--header "X-Auth-Email: <EMAIL>" \
119-
--header "X-Auth-Key: <API_KEY>" \
120-
--header "Content-Type: application/json" \
121-
--data '{
122-
"ipsec_tunnels": [
123-
{
124-
"name": "<TUNNEL_NAME>",
125-
"description": "<TUNNEL_DESCRIPTION>",
126-
"interface_address": "<INTERFACE_ADDRESS>",
127-
"cloudflare_endpoint": "<CLOUDFLARE_ENDPOINT>",
128-
"customer_endpoint": "<CUSTOMER_ENDPOINT>",
129-
"replay_protection": false
130-
}
131-
]
132-
}'
133-
```
134-
135-
```json output
136-
{
137-
"result": {
138-
"ipsec_tunnels": [
140+
1. Create a `POST` request [using the API](/api/resources/magic_transit/subresources/ipsec_tunnels/methods/create/) to create an IPsec tunnel.
141+
142+
Note that in example below, replay protection is disabled by default. You can enable it with the flag `"replay_protection": true` for each IPsec tunnel, if the devices you use do not support disabling this feature. If you have already created IPsec tunnels, update them with a [`PUT` request](/api/resources/magic_transit/subresources/ipsec_tunnels/methods/update/). Refer to <a href={props.antiReplayPagePath}>Anti-replay protection</a> for more information on this topic.
143+
144+
<APIRequest
145+
path="/accounts/{account_id}/magic/ipsec_tunnels"
146+
method="POST"
147+
json={{
148+
"name": "<TUNNEL_NAME>",
149+
"description": "<TUNNEL_DESCRIPTION>",
150+
"interface_address": "<INTERFACE_ADDRESS>",
151+
"cloudflare_endpoint": "<CLOUDFLARE_ENDPOINT>",
152+
"customer_endpoint": "<CUSTOMER_ENDPOINT>"
153+
}}
154+
/>
155+
156+
```json output
157+
{
158+
"errors": [
139159
{
140-
"id": "<YOUR_TUNNEL_ID>",
141-
"interface_address": "<INTERFACE_ADDRESS>",
142-
"created_on": "2023-04-21T10:42:22.138586Z",
143-
"modified_on": "2023-04-21T10:42:22.138586Z",
144-
"name": "<TUNNEL_NAME>",
145-
"cloudflare_endpoint": "<CLOUDFLARE_ENDPOINT>",
146-
"customer_endpoint": "<CUSTOMER_ENDPOINT>",
147-
"remote_identities": {
148-
"hex_id": "<HEX_ID>",
149-
"fqdn_id": "<FQDN_ID>.ipsec.cloudflare.com",
150-
"user_id": "ipsec@<USER_ID>.ipsec.cloudflare.com"
151-
},
152-
"description": " test",
153-
"health_check": {
154-
"enabled": true,
155-
"target": "<TARGET>",
156-
"type": "reply",
157-
"rate": "mid"
160+
"code": 1000,
161+
"message": "message"
162+
}
163+
],
164+
"messages": [
165+
{
166+
"code": 1000,
167+
"message": "message"
168+
}
169+
],
170+
"result": {
171+
"ipsec_tunnels": [
172+
{
173+
"id": "<IPSEC_TUNNEL_ID>",
174+
"interface_address": "<INTERFACE_CIDR>",
175+
"name": "<TUNNEL_NAME>",
176+
"cloudflare_endpoint": "<IP_ADDRESS>",
177+
"customer_endpoint": "<IP_ADDRESS>",
178+
"description": "<TUNNEL_DESCRIPTION>",
179+
"health_check": {
180+
"direction": "unidirectional",
181+
"enabled": true,
182+
"rate": "low",
183+
"type": "reply"
184+
},
185+
"psk_metadata": {},
186+
"replay_protection": false
158187
}
188+
]
189+
},
190+
"success": true
191+
}
192+
```
193+
194+
Take note of the tunnel `id` value. We will use it to generate a pre-shared key (PSK).
195+
196+
2. Create a `POST` [request](/api/resources/magic_transit/subresources/ipsec_tunnels/methods/psk_generate/) to generate a PSK. Use the tunnel `id` value you received from the previous command.
197+
198+
<APIRequest
199+
path="/accounts/{account_id}/magic/ipsec_tunnels/{ipsec_tunnel_id}/psk_generate"
200+
method="POST"
201+
/>
202+
203+
```json output
204+
{
205+
"result": {
206+
"ipsec_id": "<IPSEC_ID>",
207+
"ipsec_tunnel_id": "<IPSEC_TUNNEL_ID>",
208+
"psk": "<PSK_CODE>",
209+
"psk_metadata": {
210+
"last_generated_on": "2025-03-13T14:28:47.054317925Z"
159211
}
160-
]
161-
},
162-
"success": true,
163-
"errors": [],
164-
"messages": []
165-
}
166-
```
212+
},
213+
"success": true,
214+
"errors": [],
215+
"messages": []
216+
}
217+
```
167218

168-
2. Create a `POST` request to generate a PSK. Use the tunnel `id` you received from the previous command (exemplified by `<YOUR_TUNNEL_ID>` above):
219+
Take note of your `psk` value.
169220

170-
```bash
171-
curl --request POST \
172-
https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/ipsec_tunnels/{your_tunnel_id}/psk_generate \
173-
--header "X-Auth-Email: <EMAIL>" \
174-
--header "X-Auth-Key: <API_KEY>"
175-
```
221+
3. Create a `PUT` [request](/api/resources/magic_transit/subresources/ipsec_tunnels/methods/update/) to update your IPsec tunnel with the PSK.
222+
223+
<CURL
224+
url="https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/ipsec_tunnels/{ipsec_tunnel_id}"
225+
method="PUT"
226+
json={{
227+
"psk": "<PSK_VALUE>"
228+
}}
229+
/>
176230

177231
```json output
178232
{
179-
"result": {
180-
"ipsec_id": "<IPSEC_ID>",
181-
"ipsec_tunnel_id": "<IPSEC_TUNNEL>",
182-
"psk": "<YOUR_PSK_KEY>",
183-
"psk_metadata": {
184-
"last_generated_on": "2023-04-21T10:48:15.953887008Z"
185-
}
186-
},
187-
"success": true,
188-
"errors": [],
189-
"messages": []
233+
"result": {
234+
"modified": true,
235+
"modified_ipsec_tunnel": {
236+
"id": "<IPSEC_ID>",
237+
"interface_address": "<IPSEC_CIDR>",
238+
"created_on": "2025-03-13T14:28:21.139535Z",
239+
"modified_on": "2025-03-13T14:33:26.09683Z",
240+
"name": "<TUNNEL_NAME>",
241+
"cloudflare_endpoint": "<IP_ADDRESS>",
242+
"customer_endpoint": "<IP_ADDRESS>",
243+
"remote_identities": {
244+
"hex_id": "",
245+
"fqdn_id": "",
246+
"user_id": ""
247+
},
248+
"psk_metadata": {
249+
"last_generated_on": "2025-03-13T14:28:47.054318Z"
250+
},
251+
"description": "<TUNNEL_DESCRIPTION>",
252+
"health_check": {
253+
"enabled": true,
254+
"target": "",
255+
"type": "reply",
256+
"rate": "mid",
257+
"direction": "unidirectional"
258+
}
259+
}
260+
},
261+
"success": true,
262+
"errors": [],
263+
"messages": []
190264
}
191265
```
192266

193-
3. Use the above `psk` value to configure the IPsec tunnel on your equipment. You do not need to take further action to use the PSK on Cloudflare's side, as this value is automatically set.
267+
4. Use the `psk` value from step 3 to configure the IPsec tunnel on your equipment as well.
194268

195269
</Details>
196270

197271
<Details header="Configure bidirectional health checks">
198272

199-
Bidirectional health checks are available for GRE and IPsec tunnels. For Magic WAN this option defaults to bidirectional, while for Magic Transit it defaults to unidirectional.
273+
Bidirectional health checks are available for GRE and IPsec tunnels. {props.biVsUniHealthCheckDefaults}.
200274

201-
You can enable bidirectional health checks via the API with `--data '{"health_check": {"direction": "bidirectional"}}'`. For example:
275+
You can change this setting via the API with `"bidirectional"` or `"unidirectional"`:
202276

203-
```bash
204-
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/ipsec_tunnels \
205-
--header "X-Auth-Email: <EMAIL>" \
206-
--header "X-Auth-Key: <API_KEY>" \
207-
--header "Content-Type: application/json" \
208-
--data '{"health_check": {"direction": "bidirectional"}}'
277+
<CURL
278+
url="https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/ipsec_tunnels/{ipsec_tunnel_id}"
279+
method="PUT"
280+
json={{
281+
"health_check":
282+
{
283+
"direction": "bidirectional"
284+
}
285+
}}
286+
/>
287+
288+
```json output
289+
{
290+
"result": {
291+
"modified": true,
292+
"modified_ipsec_tunnel": {
293+
"id": "<IPSEC_ID>",
294+
"interface_address": "<IPSEC_CIDR>",
295+
"created_on": "2025-03-13T14:28:21.139535Z",
296+
"modified_on": "2025-03-13T14:33:26.09683Z",
297+
"name": "<TUNNEL_NAME>",
298+
"cloudflare_endpoint": "<IP_ADDRESS>",
299+
"customer_endpoint": "<IP_ADDRESS>",
300+
"remote_identities": {
301+
"hex_id": "",
302+
"fqdn_id": "",
303+
"user_id": ""
304+
},
305+
"psk_metadata": {
306+
"last_generated_on": "2025-03-13T14:28:47.054318Z"
307+
},
308+
"description": "<TUNNEL_DESCRIPTION>",
309+
"health_check": {
310+
"enabled": true,
311+
"target": "",
312+
"type": "reply",
313+
"rate": "mid",
314+
"direction": "bidirectional"
315+
}
316+
}
317+
},
318+
"success": true,
319+
"errors": [],
320+
"messages": []
321+
}
209322
```
210323

211324
</Details>

0 commit comments

Comments
 (0)