Skip to content

Add Load Balancing documentation updates#31583

Open
ngayerie wants to merge 3 commits into
productionfrom
ngayerie/DEE-3631
Open

Add Load Balancing documentation updates#31583
ngayerie wants to merge 3 commits into
productionfrom
ngayerie/DEE-3631

Conversation

@ngayerie

@ngayerie ngayerie commented Jun 19, 2026

Copy link
Copy Markdown
Collaborator

Summary

Documentation updates covering undocumented behaviors and configuration guidance across Load Balancing, monitors, health checks, pools, and Spectrum.

Source: Wiki review page

Changes (9 files, +64/-1)

Topic File Change
Pool endpoint uniqueness load-balancing/pools/create-pool.mdx Endpoints can share an IP if differentiated by port or virtual network
Custom rules with header field references load-balancing/additional-options/load-balancing-rules/index.mdx Clarify behavior for load-balancing rules referencing header fields
Planned Maintenance load-balancing/additional-options/planned-maintenance.mdx Document planned-maintenance behavior
Retry timing load-balancing/monitors/create-monitor.mdx Retries fire immediately on timeout (not after interval); 'five' rather than '5'; active voice
Monitor limits load-balancing/monitors/index.mdx Document monitor-related limits
Spectrum session affinity spectrum/about/load-balancer.mdx Use 'Session affinity with Spectrum' framing; reference 'session affinity by cookie and client IP fallback'
Private Network Load Balancing load-balancing/private-network/index.mdx Clean up private-network guidance (no redundant Tunnel off-ramp section)
Adaptive routing — HTTP/2 GOAWAY load-balancing/understand-basics/adaptive-routing.mdx Document HTTP/2 GOAWAY handling
Health checks health-checks/index.mdx Minor clarification

Review feedback addressed

  • ✅ All 11 inline comments from @ncrouch-cflare applied (create-pool, lb-rules, spectrum, private-network, health-checks, create-monitor)
  • ✅ Per reviewer feedback, removed the DNS-only HTTP-layer-rules note (inaccurate)
  • ✅ All ask-bonk anchor/separator suggestions applied

Stats

9 files changed, +64 insertions, -1 deletion

Resolves DEE-3631

@github-actions github-actions Bot added product:load-balancing Related to Load Balancing product product:spectrum Related to Spectrum product product:health-checks size/s labels Jun 19, 2026
@github-actions

Copy link
Copy Markdown
Contributor

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern Owners
/src/content/docs/health-checks/ @cloudflare/product-owners, @ncrouch-cflare
/src/content/docs/load-balancing/ @cloudflare/cf1-reviewers, @elithrar, @cloudflare/product-owners, @ncrouch-cflare
/src/content/docs/spectrum/ @cloudflare/appsec-reviewers, @elithrar, @cloudflare/product-owners, @cansu

@ask-bonk ask-bonk Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

4 issues need addressing before merge: 1 broken link and 3 inconsistent horizontal rules.

Comment thread src/content/docs/load-balancing/private-network/index.mdx
Comment thread src/content/docs/health-checks/index.mdx Outdated
Comment thread src/content/docs/load-balancing/additional-options/load-balancing-rules/index.mdx Outdated
Comment thread src/content/docs/load-balancing/understand-basics/adaptive-routing.mdx Outdated
@ask-bonk ask-bonk Bot added documentation Documentation edits triage Waiting for a docs team review. labels Jun 19, 2026
@ask-bonk

ask-bonk Bot commented Jun 19, 2026

Copy link
Copy Markdown
Contributor

PR Review Summary

Verdict: 4 issues need fixing before merge. Posted inline suggestions for all.

Issues Flagged

HIGH — Broken link in src/content/docs/load-balancing/private-network/index.mdx (line 32):
/cloudflare-one/connections/connect-networks/ does not exist. The correct path is /cloudflare-one/networks/connectors/cloudflare-tunnel/.

LOW — Inconsistent horizontal rules:

  • src/content/docs/health-checks/index.mdx (line 56): Uses ---, but the rest of the file uses ***.
  • src/content/docs/load-balancing/additional-options/load-balancing-rules/index.mdx (lines 34–36): Adds a --- separator, but the rest of the file does not use them.
  • src/content/docs/load-balancing/understand-basics/adaptive-routing.mdx (lines 35–37): Adds a --- separator, but the rest of the file does not use them.

What the PR Changes

Adds 12 documentation clarifications across 9 files covering:

  • Connection persistence during endpoint unhealthiness
  • IPv4/IPv6 probe and retry timing behavior
  • Geo-steering failover boundaries
  • Endpoint uniqueness constraints
  • HTTP/2 GOAWAY handling
  • Spectrum session affinity limitations
  • Load-balancing rule proxy-mode side effects
  • Public LB + Tunnel off-ramp guidance
  • Health-check interval best-effort behavior

Labels Applied

product:load-balancing, product:health-checks, product:spectrum, documentation, triage

github run

@ngayerie ngayerie force-pushed the ngayerie/DEE-3631 branch 2 times, most recently from 72b2bb3 to 69bef14 Compare June 19, 2026 13:19
Document undocumented behaviors and configuration guidance across
Load Balancing, health monitors, and Spectrum:

1. Planned maintenance: existing connections not terminated on unhealthy
2. Monitors: IPv4/IPv6 probe behavior
3. Adaptive routing: failover across pools geo-steering limitation
4. Monitor retries: immediate retry timing, not interval-based
5. Pools: endpoint address uniqueness constraint
6. Adaptive routing: HTTP/2 GOAWAY frame handling
7. FAQ: analytics 5s cache behavior with and without custom rules
8. Spectrum: session affinity workaround (IP fallback)
9. Private network: public LB with Tunnel off-ramp pattern
10. Custom rules: pool override failover behavior
11. Health checks: interval timing grouping behavior
12. Custom rules: DNS-only LB forced to proxied with HTTP rules

Resolves DEE-3631
@ngayerie ngayerie force-pushed the ngayerie/DEE-3631 branch from 69bef14 to 001955e Compare June 19, 2026 13:30
@github-actions

github-actions Bot commented Jun 19, 2026

Copy link
Copy Markdown
Contributor

Preview URL: https://a6734198.preview.developers.cloudflare.com
Preview Branch URL: https://ngayerie-dee-3631.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link Updated Link
https://developers.cloudflare.com/load-balancing/understand-basics/adaptive-routing/ https://ngayerie-dee-3631.preview.developers.cloudflare.com/load-balancing/understand-basics/adaptive-routing/
https://developers.cloudflare.com/spectrum/about/load-balancer/ https://ngayerie-dee-3631.preview.developers.cloudflare.com/spectrum/about/load-balancer/
https://developers.cloudflare.com/load-balancing/monitors/create-monitor/ https://ngayerie-dee-3631.preview.developers.cloudflare.com/load-balancing/monitors/create-monitor/
https://developers.cloudflare.com/load-balancing/monitors/ https://ngayerie-dee-3631.preview.developers.cloudflare.com/load-balancing/monitors/
https://developers.cloudflare.com/health-checks/ https://ngayerie-dee-3631.preview.developers.cloudflare.com/health-checks/
https://developers.cloudflare.com/load-balancing/additional-options/planned-maintenance/ https://ngayerie-dee-3631.preview.developers.cloudflare.com/load-balancing/additional-options/planned-maintenance/
https://developers.cloudflare.com/load-balancing/pools/create-pool/ https://ngayerie-dee-3631.preview.developers.cloudflare.com/load-balancing/pools/create-pool/
https://developers.cloudflare.com/load-balancing/private-network/ https://ngayerie-dee-3631.preview.developers.cloudflare.com/load-balancing/private-network/
https://developers.cloudflare.com/load-balancing/additional-options/load-balancing-rules/ https://ngayerie-dee-3631.preview.developers.cloudflare.com/load-balancing/additional-options/load-balancing-rules/

@ngayerie ngayerie marked this pull request as ready for review June 19, 2026 14:24
@ngayerie ngayerie requested review from a team, elithrar and ncrouch-cflare as code owners June 19, 2026 14:24
@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Jun 19, 2026

Copy link
Copy Markdown
Contributor

Review

⏸️ Automatic reviews for this PR are paused.

This PR has already received 2 automatic reviews. To run another review, a codeowner can comment /review or /full-review. To permanently lift the limit for this PR, a codeowner can comment /ignore-review-limit.

Tip: Keep PRs in draft mode until they are ready for review — the bot skips draft PRs automatically.


✅ No issues found in commit 2e980eb.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

✅ No code review issues found.

Style Guide Review

✅ No style-guide issues found.

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command Description
/review Runs a review now. Incremental if a prior review exists, full if not.
/full-review Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.

@ngayerie

Copy link
Copy Markdown
Collaborator Author

Hi @ncrouch-cflare
Could you please review this PR? (and merge if it's fine?)
Thanks!

Comment thread src/content/docs/load-balancing/pools/create-pool.mdx Outdated
Comment thread src/content/docs/load-balancing/additional-options/load-balancing-rules/index.mdx Outdated
Comment thread src/content/docs/spectrum/about/load-balancer.mdx Outdated
Comment thread src/content/docs/load-balancing/private-network/index.mdx Outdated
Comment thread src/content/docs/spectrum/about/load-balancer.mdx Outdated
Comment thread src/content/docs/health-checks/index.mdx Outdated
Comment thread src/content/docs/load-balancing/private-network/index.mdx Outdated
Comment thread src/content/docs/load-balancing/monitors/create-monitor.mdx Outdated
Comment thread src/content/docs/load-balancing/monitors/create-monitor.mdx Outdated
Comment thread src/content/docs/load-balancing/monitors/create-monitor.mdx Outdated
ngayerie added 2 commits June 24, 2026 14:07
- create-pool: clarify endpoint uniqueness (port or virtual network)
- load-balancing-rules: remove inaccurate pool override failover section
- spectrum: rename 'Session affinity workaround' and align phrasing with
  'session affinity by cookie and client IP fallback' feature name
- private-network: remove redundant Tunnel off-ramp section (already
  covered in the existing Tunnels section below)
- health-checks: remove vague interval timing paragraph
- create-monitor: active voice, 'five' not '5', timeout-only triggers
Per reviewer feedback, this behavior description was inaccurate.
@ngayerie ngayerie closed this Jun 24, 2026
@ngayerie

Copy link
Copy Markdown
Collaborator Author

re-opening to trigger CI tests

@ngayerie ngayerie reopened this Jun 24, 2026
@ngayerie ngayerie requested a review from ncrouch-cflare June 25, 2026 08:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Documentation edits product:health-checks product:load-balancing Related to Load Balancing product product:spectrum Related to Spectrum product size/s triage Waiting for a docs team review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants