docs: explain what Cloudflare can and cannot sit in front of - #60
Merged
Conversation
Proxying the whole control plane through a CDN is the obvious first instinct, and half of it is right: Cloudflare in front of 443 removes the need to run ACME for the dashboard entirely. The hub is the other half and it has to be grey-clouded. Port 8443 is on Cloudflare's proxied HTTPS list, so this reads as supported and is not: an L7 proxy resets a bidirectional stream well before its 100-120s read timeout, client certificates do not survive termination, and workers end up verifying the edge certificate rather than the one they were given to pin — so --ca-cert quietly stops pinning anything. None of that fails at setup time. It shows up later as workers that reconnect constantly and an mTLS mode that cannot be turned on. Also records that a certificate is still required either way. The startup check is about the hub, not the dashboard, so putting a CDN in front of 443 does not remove it — which is not obvious from the error text. Two settings people will get wrong: RSAGENT_TRUSTED_PROXY_HOPS has to count the CDN as well as the local proxy, or every audit row records an edge IP instead of a person; and 8080 needs restricting to the CDN's ranges, or the dashboard is reachable over plain HTTP at the origin address, where credential onboarding silently does not work. Generalised into the gotchas list as well, because the reasoning is not specific to Cloudflare — any WAF, ingress controller or application gateway in front of the hub fails the same way. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AyYg2j8FVkLjiaVcj5HCkj
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a Behind Cloudflare, or any CDN proxy section to
docs/deployment.md, from a question that came up trying the Azure VM route.Proxying the whole control plane through a CDN is the obvious first instinct, and half of it is right: Cloudflare in front of 443 removes the need to run ACME for the dashboard at all.
The hub is the other half, and it has to be grey-clouded.
Why this is worth writing down
Port 8443 is on Cloudflare's proxied HTTPS list, so this reads as supported. It isn't:
--ca-certquietly stops pinning anythingNone of that fails at setup time. It shows up later as workers reconnecting constantly and an mTLS mode that can't be turned on.
Also recorded
A hub certificate is still required either way.
RSAGENT_GRPC_REQUIRE_TLSis about the hub, not the dashboard, so putting a CDN in front of 443 doesn't remove it — which isn't obvious from the error text.Two settings people will get wrong:
RSAGENT_TRUSTED_PROXY_HOPS2for Cloudflare → Caddy → server. Otherwise every audit row records an edge IP instead of a personPlus: use Full (strict), not Flexible; and DNS-01 is the way to get a public certificate for a grey-clouded name. Cloudflare Origin Certificates are explicitly ruled out — only Cloudflare's edge trusts them, and workers aren't Cloudflare's edge.
Generalised into the gotchas list too, since the reasoning isn't Cloudflare-specific — any WAF, ingress controller or application gateway in front of the hub fails the same way.
Docs only, no code. Anchors and relative links verified.
🤖 Generated with Claude Code
https://claude.ai/code/session_01AyYg2j8FVkLjiaVcj5HCkj