[Spectrum] Document IP Access Rules blocking health checks

[stechedo]

Summary

Split out of #30683 at the reviewer's request — see this comment:

Could we just hold the IP Access Rules + health checks section? I need a bit more time to verify the mechanism, but I don't want to block everything else.

Changes

• spectrum/reference/troubleshooting.mdx — New "Health checks fail when IP Access Rules are enabled" section (symptoms/cause/solution) covering the allowlist-model blocking Cloudflare's health check probes.
• spectrum/reference/configuration-options.mdx — Caution callout under IP Access rules warning about health check impact, plus a note that Custom Rules (WAF) do not apply to TCP/UDP Spectrum applications.
• load-balancing/additional-options/spectrum.mdx — Matching caution callout in the Monitors step of the Spectrum load balancing setup guide.

Content area

Spectrum, Load Balancing

[cloudflare-docs-bot]

AI Review

✅ Reviewed 41c80ff · 0 findings · incremental

Commands

• /review Run a review now.
• /full-review Review the entire PR diff.
• /disable-auto-review Stop automatic reviews.
• /rebase Rebase against production.

[msimoncf]

Suggested fixes for IP Access Rules + health checks content

The current troubleshooting section says: "consider configuring health checks to use a TCP check type... and manage your access control at the origin level instead." That appears to be technically misleading. IP Access Rules on a Spectrum application evaluate every incoming TCP connection based on source IP, so switching from HTTP to TCP health checks does not bypass the block — the probe's TCP connection is still rejected before the health-check protocol is negotiated.

1. spectrum/reference/troubleshooting.mdx
   Replace the current "Health checks fail when IP Access Rules are enabled" section with:

Health checks fail when IP Access Rules are enabled

Applies to

This issue applies when a Spectrum application is the target of a health check:

• A standalone Cloudflare Health Check is configured against the Spectrum application, or
• A Load Balancer monitor uses the Spectrum application as an endpoint (the Spectrum app is the target of the Load Balancer).

This issue does not apply when the Spectrum application's origin is a Load Balancer hostname. In that architecture, the Load Balancer monitor probes the origin servers directly, not through the Spectrum application, so IP Access Rules on the Spectrum app do not affect the monitor.

Symptoms

• Cloudflare Health Checks or Load Balancer monitors report the Spectrum endpoint as unhealthy.
• Removing IP Access Rules from the Spectrum application causes health checks to succeed.
• The Spectrum application works correctly for client traffic that is allowed by the IP Access Rules.

Cause

When you turn on IP Access Rules on a Spectrum application, all incoming connections are evaluated against your rules based on source IP — including connections from Cloudflare's own health check probes. If your rules use an allowlist model (allow specific IPs, block all others), Cloudflare's health check source IPs will be blocked.

Switching the health check from HTTP to TCP does not bypass IP Access Rules, because the rules evaluate the incoming connection before the health-check protocol is negotiated.

Solution

Add Cloudflare's IP ranges to your IP Access Rules allowlist. You can find the current list of Cloudflare IP addresses at cloudflare.com/ips.

If you need to restrict client access but cannot allowlist Cloudflare IPs on the Spectrum application, move access control to your origin instead of using IP Access Rules on the Spectrum app. If IP Access Rules remain enabled without allowing Cloudflare probe IPs, health checks will continue to fail.
2. load-balancing/additional-options/spectrum.mdx
Update the caution callout in the Monitors step to clarify the architecture context:
:::caution[IP Access Rules and health checks]
If your Spectrum application is used as a Load Balancer endpoint and has IP Access Rules enabled, Cloudflare's health check probes must be allowed by your rules. Otherwise, health checks will be blocked and all endpoints will be marked as unhealthy. To resolve this, add Cloudflare IP addresses to your IP Access Rules allowlist. Refer to Spectrum Troubleshooting for details.

This does not apply when the Spectrum application's origin is a Load Balancer hostname. In that architecture, the monitor probes the origin directly and is not affected by IP Access Rules on the Spectrum app.
:::
3. spectrum/reference/configuration-options.mdx
The caution callout here is fine as-is, but optionally add the same qualifier so the limitation is not overstated:
:::caution[Health checks and IP Access Rules]
When IP Access Rules are enabled with an allowlist model (allow specific IPs, block all others), health checks targeting the Spectrum application may be blocked, causing endpoints to appear unhealthy. This applies when the Spectrum application is the target of a Cloudflare Health Check or a Load Balancer monitor. To prevent this, add Cloudflare IP addresses to your allowlist. Refer to Spectrum Troubleshooting for details.
:::
The Custom Rules note immediately below this can stay unchanged.

[github-actions]

Hey there, we've marked this pull request as stale because there's no recent activity on it. This label helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant).