From bc67b18349ea1102f67352b6f78f7417966df46b Mon Sep 17 00:00:00 2001 From: Marcio Date: Fri, 18 Jul 2025 11:01:03 +0100 Subject: [PATCH 1/7] added beta badge --- .../magic-transit/network-health/run-endpoint-health-checks.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx index 41e1c7f90681a8d..ab2e3a5e965e203 100644 --- a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx +++ b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx @@ -2,6 +2,8 @@ pcx_content_type: how-to title: Run endpoint health checks sidebar: + badge: + text: Beta order: 1 --- From 3dabb78d66fb40b4f296a62a2be004f3bbfd0f1d Mon Sep 17 00:00:00 2001 From: Marcio Date: Fri, 18 Jul 2025 11:51:49 +0100 Subject: [PATCH 2/7] added content --- .../run-endpoint-health-checks.mdx | 131 +++++++++++++++++- 1 file changed, 128 insertions(+), 3 deletions(-) diff --git a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx index ab2e3a5e965e203..208f99d2f5e438f 100644 --- a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx +++ b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx @@ -1,14 +1,17 @@ --- pcx_content_type: how-to -title: Run endpoint health checks +title: Run endpoint health checks (beta) sidebar: badge: text: Beta order: 1 + label: Run endpoint health checks --- -Magic Transit uses endpoint health checks to determine the overall health of your [inter-network connections](/magic-transit/reference/tunnels/). Probes originate from Cloudflare infrastructure, outside customer network namespaces, and target IP addresses deep within your network, beyond the tunnel-terminating border router. These "long distance" probes are purely diagnostic. +import { CURL } from '~/components'; + +Magic Transit uses endpoint health checks to determine the overall health of your [inter-network connections](/magic-transit/reference/gre-ipsec-tunnels/). Probes originate from Cloudflare infrastructure, outside customer network namespaces, and target IP addresses deep within your network, beyond the tunnel-terminating border router. These "long distance" probes are purely diagnostic. When choosing which endpoint IP addresses to monitor with health checks, use these guidelines: @@ -17,7 +20,7 @@ When choosing which endpoint IP addresses to monitor with health checks, use the Cloudflare pings health check IPs from within the [published Cloudflare IP range](https://www.cloudflare.com/ips/), which is also available via the [Cloudflare API](/api/resources/ips/methods/list/). -Refer to the table below for an example of an endpoint health check configuration. +When configuring an endpoint health check for an IP prefix, you need to select an IP address that is within the range of that IP prefix. Refer to the table below for an example of an endpoint health check configuration. | Prefix | Endpoint IP address | | ----------------- | ------------------- | @@ -25,3 +28,125 @@ Refer to the table below for an example of an endpoint health check configuratio | `103.21.245.0/24` | `103.21.245.100` | Refer to [Tunnel health checks](/magic-transit/reference/tunnel-health-checks/) for more information on this topic. + +You can learn how to configure and query endpoint health checks. Configuring health checks is a beta feature. + +## Configure endpoint health checks + +Endpoint health checks can only be configured via the Cloudflare API. Endpoint health checks can not be configured via the dashboard, and they are not shown in the dashboard. + +Refer to the [API documentation](/api/resources/diagnostics/) to learn how to create, list, and delete endpoint health checks. Here is an example of a request to the Cloudflare API to create a new endpoint health check. + + + +```json output +{ + "result": { + "id": "", + "check_type": "icmp", + "endpoint": "8.31.160.1" + }, + "success": true, + "errors": [], + "messages": [] +} +``` + +## Query GraphQL endpoint health checks + +You can also use GraphQL to query endpoints within your network. This allows you to know if an IP within your network is reachable, and also set alerts in case there is a problem. + +You can query the following categories: + +- `checkId`: The ID of the check associated with the health check. +- `checkType`: The type of check associated with the health check. +- `date`: The health check event timestamp truncated to the day. +- `datetime`: The health check event timestamp. +- `datetimeFifteenMinutes`: The health check event timestamp truncated to multiples of 15 minutes. +- `datetimeFiveMinutes`: The health check event timestamp truncated to multiples of five minutes. +- `datetimeHalfOfHour`: The health check event timestamp truncated to multiples of 30 minutes. +- `datetimeHour`: The health check event timestamp truncated to the hour. +- `datetimeMinute`: The health check event timestamp truncated to the minute. +- `endpoint`: The endpoint of the check associated with the health check. + +Refer to the example below on how to create a query to check your endpoint's health: + +```graphql +query Viewer { + viewer { + accounts(filter: { accountTag: "YOUR_ACCOUNT_TAG" }) { + magicEndpointHealthCheckAdaptiveGroups( + filter: { date_geq: "2025-05-10" } + limit: 10 + ) { + count + dimensions { + checkId + checkType + date + datetime + datetimeFifteenMinutes + datetimeFiveMinutes + datetimeHalfOfHour + datetimeHour + datetimeMinute + endpoint + } + sum { + failures + total + } + } + } + } +} +``` + +## Configure alerts for endpoint health checks + +You can set up alerts to be notified when the state of your endpoint's health is below a threshold defined by you. + +1. Make a `GET` request to get a list of IDs for all of the endpoint health checks configured: + + + +```json output +{ + "result": [ + { + "id": "", + "check_type": "icmp", + "endpoint": "8.31.160.1" + } + ], + "success": true, + "errors": [], + "messages": [] +} +``` + +2. Take note of the `id` value for the endpoint you want to get alerts for. +3. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account. +4. Go to **Notifications** > **Add**. +5. From the drop down menu, select *Magic Transit*. +6. Select **Magic Endpoint Health Check Alert**. +7. Provide a name for your new notification and optionally provide a description. +8. In the *Service Level Objective (SLO)* dropdown, select the SLO threshold for your notification. The SLO defines the percentage of endpoint health checks that should be passing. If the number of endpoint health checks passing is less than the SLO, then an alert is generated: + - **High** - 99% of endpoint health checks + - **Medium** - 98% of endpoint health checks + - **Low** - 97% of endpoint health checks +9. In the dropdown menu below SLOs, select the `id` value that matches the `id` you got through the API in step one. This `id` should match the endpoint health check you want to get notifications for. +10. Select your preferred notification method (like email or Webhooks). +11. Select **Save**. + +You will now receive notifications via your preferred method whenever the SLO for your endpoint health checks falls below your chosen threshold. From 943122069966b444adb4d28d891dab97110a3cfe Mon Sep 17 00:00:00 2001 From: Marcio Date: Fri, 18 Jul 2025 12:08:52 +0100 Subject: [PATCH 3/7] added curl component --- .../magic-transit/network-health/run-endpoint-health-checks.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx index c3a873927e065f4..208f99d2f5e438f 100644 --- a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx +++ b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx @@ -9,6 +9,8 @@ sidebar: --- +import { CURL } from '~/components'; + Magic Transit uses endpoint health checks to determine the overall health of your [inter-network connections](/magic-transit/reference/gre-ipsec-tunnels/). Probes originate from Cloudflare infrastructure, outside customer network namespaces, and target IP addresses deep within your network, beyond the tunnel-terminating border router. These "long distance" probes are purely diagnostic. When choosing which endpoint IP addresses to monitor with health checks, use these guidelines: From 4e963717510d35d1e5382449887343351c4c1290 Mon Sep 17 00:00:00 2001 From: Marcio Date: Fri, 18 Jul 2025 14:21:09 +0100 Subject: [PATCH 4/7] added api partial info --- .../network-health/run-endpoint-health-checks.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx index 208f99d2f5e438f..f42298129cb1a2a 100644 --- a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx +++ b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx @@ -9,7 +9,7 @@ sidebar: --- -import { CURL } from '~/components'; +import { CURL, Render } from '~/components'; Magic Transit uses endpoint health checks to determine the overall health of your [inter-network connections](/magic-transit/reference/gre-ipsec-tunnels/). Probes originate from Cloudflare infrastructure, outside customer network namespaces, and target IP addresses deep within your network, beyond the tunnel-terminating border router. These "long distance" probes are purely diagnostic. @@ -37,6 +37,8 @@ Endpoint health checks can only be configured via the Cloudflare API. Endpoint h Refer to the [API documentation](/api/resources/diagnostics/) to learn how to create, list, and delete endpoint health checks. Here is an example of a request to the Cloudflare API to create a new endpoint health check. + + Date: Thu, 24 Jul 2025 09:16:30 +0100 Subject: [PATCH 5/7] updated url --- .../magic-transit/network-health/run-endpoint-health-checks.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx index f42298129cb1a2a..1ed2d1b0bd699a4 100644 --- a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx +++ b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx @@ -35,7 +35,7 @@ You can learn how to configure and query endpoint health checks. Configuring hea Endpoint health checks can only be configured via the Cloudflare API. Endpoint health checks can not be configured via the dashboard, and they are not shown in the dashboard. -Refer to the [API documentation](/api/resources/diagnostics/) to learn how to create, list, and delete endpoint health checks. Here is an example of a request to the Cloudflare API to create a new endpoint health check. +Refer to the [API documentation](/api/resources/diagnostics/subresources/endpoint-healthchecks/) to learn how to create, list, and delete endpoint health checks. Here is an example of a request to the Cloudflare API to create a new endpoint health check. From d5887bddacc0cd896d5987bcfe4c9e29d21d31bf Mon Sep 17 00:00:00 2001 From: Marcio Date: Thu, 24 Jul 2025 09:20:05 +0100 Subject: [PATCH 6/7] refined text --- .../network-health/run-endpoint-health-checks.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx index 1ed2d1b0bd699a4..eab8915a8d8ae8b 100644 --- a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx +++ b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx @@ -29,11 +29,9 @@ When configuring an endpoint health check for an IP prefix, you need to select a Refer to [Tunnel health checks](/magic-transit/reference/tunnel-health-checks/) for more information on this topic. -You can learn how to configure and query endpoint health checks. Configuring health checks is a beta feature. +## Configure endpoint health checks (beta) -## Configure endpoint health checks - -Endpoint health checks can only be configured via the Cloudflare API. Endpoint health checks can not be configured via the dashboard, and they are not shown in the dashboard. +Endpoint health checks can only be configured via the Cloudflare API. Endpoint health checks can not be configured via the dashboard, and they are not shown in the dashboard. Currently, configuring health checks is a beta feature. Refer to the [API documentation](/api/resources/diagnostics/subresources/endpoint-healthchecks/) to learn how to create, list, and delete endpoint health checks. Here is an example of a request to the Cloudflare API to create a new endpoint health check. From 1728135fd1c209b2842928c7a82149a0232d926e Mon Sep 17 00:00:00 2001 From: marciocloudflare <83226960+marciocloudflare@users.noreply.github.com> Date: Thu, 24 Jul 2025 09:46:14 +0100 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: Jun Lee --- .../network-health/run-endpoint-health-checks.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx index eab8915a8d8ae8b..9a35a66033c22d8 100644 --- a/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx +++ b/src/content/docs/magic-transit/network-health/run-endpoint-health-checks.mdx @@ -33,7 +33,7 @@ Refer to [Tunnel health checks](/magic-transit/reference/tunnel-health-checks/) Endpoint health checks can only be configured via the Cloudflare API. Endpoint health checks can not be configured via the dashboard, and they are not shown in the dashboard. Currently, configuring health checks is a beta feature. -Refer to the [API documentation](/api/resources/diagnostics/subresources/endpoint-healthchecks/) to learn how to create, list, and delete endpoint health checks. Here is an example of a request to the Cloudflare API to create a new endpoint health check. +Refer to the [API documentation](/api/resources/diagnostics/subresources/endpoint-healthchecks/) to learn how to create, list, and delete endpoint health checks. Here is an example of an API request which sends a request to the Cloudflare API to create a new endpoint health check. @@ -141,7 +141,7 @@ You can set up alerts to be notified when the state of your endpoint's health is 5. From the drop down menu, select *Magic Transit*. 6. Select **Magic Endpoint Health Check Alert**. 7. Provide a name for your new notification and optionally provide a description. -8. In the *Service Level Objective (SLO)* dropdown, select the SLO threshold for your notification. The SLO defines the percentage of endpoint health checks that should be passing. If the number of endpoint health checks passing is less than the SLO, then an alert is generated: +8. In the *Service Level Objective (SLO)* dropdown, select the SLO threshold for your notification. The SLO defines the percentage of endpoint health checks that should be passing. If the number of endpoint health checks passing is less than the SLO, an alert is generated: - **High** - 99% of endpoint health checks - **Medium** - 98% of endpoint health checks - **Low** - 97% of endpoint health checks