Documented NetBird-Only Access and Proxy Cluster features in reverse … by mlsmaycon · Pull Request #767 · netbirdio/docs

mlsmaycon · 2026-05-24T15:03:51Z

…proxy settings. Updated authentication methods, backend configuration guides, and cluster capability requirements.

Summary by CodeRabbit

Documentation
- Added comprehensive docs for NetBird-Only Access: WireGuard peer verification, access-group requirement, mutual exclusivity with operator auth, automatic NetBird-range allow baseline, and UI flow for enabling/disabling.
- Documented Proxy Cluster target type, Direct Upstream behavior for private services, BYOP feature-badge meanings, and capability flag in cluster UI.
- Described NetBird identity headers (X-NetBird-User, X-NetBird-Groups) with anti-spoof guidance and example.
- Expanded reverse-proxy routing examples and full environment-variable reference.

…proxy settings. Updated authentication methods, backend configuration guides, and cluster capability requirements.

coderabbitai · 2026-05-24T15:04:10Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 70d121c2-b62d-4ff1-a5c5-faba8345240a

📥 Commits

Reviewing files that changed from the base of the PR and between f78f73d and 522b097.

⛔ Files ignored due to path filters (1)

public/docs-static/img/manage/reverse-proxy/byop/byop-setup-modal-install.png is excluded by !**/*.png

📒 Files selected for processing (2)

src/pages/selfhosted/external-reverse-proxy.mdx
src/pages/selfhosted/migration/enable-reverse-proxy.mdx

📝 Walkthrough

Walkthrough

Documentation updates add NetBird-Only Access (private HTTP service auth), a Private cluster capability and Proxy Cluster target, UI and quick-start adjustments, automatic NetBird-range access rules and Direct Upstream behavior, and backend identity headers (X-NetBird-User, X-NetBird-Groups) with anti-spoof guidance.

Changes

NetBird-Only Access for Private Services

Layer / File(s)	Summary
NetBird-Only Access foundation and mechanics `src/pages/manage/reverse-proxy/authentication.mdx`	Introduces two-family auth model: operator auth (SSO/password/PIN/header) and NetBird-Only Access (requires `Private`). Documents WireGuard peer verification, access-group gating, operator-auth combination wording, access-restriction label change to “Any operator auth,” header stamping/stripping, and setup/removal walkthrough.
Feature badges and BYOP Private behavior `src/pages/manage/reverse-proxy/bring-your-own-proxy.mdx`	Adds a Features badge meaning table (including `Private`) and documents when BYOP clusters advertise `Private`, which service options are unlocked, and UI behavior when `Private` is absent.
Proxy Cluster target and Quick Start updates `src/pages/manage/reverse-proxy/index.mdx`, `src/pages/manage/reverse-proxy/bring-your-own-proxy.mdx`	Adds Proxy Cluster target type (requires `Private`), clarifies host resolvability from the embedded proxy’s host stack, updates Quick Start to include Proxy Cluster, and adds NetBird-Only Access to authentication method lists and bullets.
Access control and Direct Upstream behavior `src/pages/manage/reverse-proxy/index.mdx`	Notes NetBird-Only services automatically get a NetBird-range allow baseline, overlay country/CrowdSec checks are skipped, and documents Direct Upstream advanced setting differences between Peer/Resource and Proxy Cluster targets.
Backend identity headers and anti-spoof guidance `src/pages/manage/reverse-proxy/service-configuration.mdx`	Adds `X-NetBird-User` and `X-NetBird-Groups` headers stamped by the proxy, warns that client-supplied values are stripped, and provides a FastAPI example that rejects requests missing `X-NetBird-User`.
External reverse-proxy routing updates `src/pages/selfhosted/external-reverse-proxy.mdx`	Adds routing and template rules for `management.ProxyService` across combined-container and legacy multi-container examples (Traefik, Nginx, Caddy, Nginx Proxy Manager).
Reverse proxy environment variable reference `src/pages/selfhosted/migration/enable-reverse-proxy.mdx`	Reorganizes and expands env var documentation into grouped tables: core, TLS certificates, ACME, networking, observability, CrowdSec, geolocation, and advanced tunnel tuning variables.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

netbirdio/docs#762: Modifies BYOP/Manage clusters area; related to cluster capability and wording changes.

Suggested reviewers

SunsetDrifter
lixmal

Poem

🐰 I hopped the tunnel, ears held high,
Stamped users and groups as clouds went by,
Docs now whisper which gates to keep,
Private paths where only peers may peep,
Hop in — the headers guide your leap.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly summarizes the main changes: it documents two key features (NetBird-Only Access and Proxy Cluster) in reverse-proxy documentation, which aligns with the PR's primary objective and the bulk of file changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch private-services

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

src/pages/selfhosted/external-reverse-proxy.mdx

Oops! Something went wrong! :(

ESLint: 9.39.4

TypeError: Converting circular structure to JSON
--> starting at object with constructor 'Object'
| property 'configs' -> object with constructor 'Object'
| property 'flat' -> object with constructor 'Object'
| ...
| property 'plugins' -> object with constructor 'Object'
--- property 'react' closes the circle
Referenced from:
at JSON.stringify ()
at file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/shared/config-validator.js:308:45
at Array.map ()
at ConfigValidator.formatErrors (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/shared/config-validator.js:299:23)
at ConfigValidator.validateConfigSchema (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/shared/config-validator.js:330:84)
at ConfigArrayFactory._normalizeConfigData (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/config-array-factory.js:676:19)
at ConfigArrayFactory._loadConfigData (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/config-array-factory.js:641:21)
at ConfigArrayFactory._loadExtendedShareableConfig (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/config-array-factory.js:946:21)
at ConfigArrayFactory._loadExtends (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/config-array-factory.js:814:25)
at ConfigArrayFactory._normalizeObjectConfigDataBody (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/config-array-factory.js:752:25)

src/pages/selfhosted/migration/enable-reverse-proxy.mdx

Oops! Something went wrong! :(

ESLint: 9.39.4

TypeError: Converting circular structure to JSON
--> starting at object with constructor 'Object'
| property 'configs' -> object with constructor 'Object'
| property 'flat' -> object with constructor 'Object'
| ...
| property 'plugins' -> object with constructor 'Object'
--- property 'react' closes the circle
Referenced from:
at JSON.stringify ()
at file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/shared/config-validator.js:308:45
at Array.map ()
at ConfigValidator.formatErrors (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/shared/config-validator.js:299:23)
at ConfigValidator.validateConfigSchema (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/shared/config-validator.js:330:84)
at ConfigArrayFactory._normalizeConfigData (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/config-array-factory.js:676:19)
at ConfigArrayFactory._loadConfigData (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/config-array-factory.js:641:21)
at ConfigArrayFactory._loadExtendedShareableConfig (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/config-array-factory.js:946:21)
at ConfigArrayFactory._loadExtends (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/config-array-factory.js:814:25)
at ConfigArrayFactory._normalizeObjectConfigDataBody (file:///node_modules/.pnpm/@eslint+eslintrc@3.3.5/node_modules/@eslint/eslintrc/lib/config-array-factory.js:752:25)

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/pages/manage/reverse-proxy/authentication.mdx`:
- Around line 278-279: Update the wording in the modal steps (the text
describing step 5 in authentication.mdx) to clarify that selected access groups
allow access not only to peers whose owning user is in those groups but also to
user-less peers that are members of those same peer groups (e.g., cluster
proxies); change the sentence that currently reads "Only peers whose owning user
is in one of these groups can reach the service" to include the caveat about
user-less peers and peer-group membership so the guidance is consistent with
earlier documentation.

In `@src/pages/manage/reverse-proxy/bring-your-own-proxy.mdx`:
- Line 208: Update the anchor in the link whose text is "**NetBird-Only
Access**" by replacing the incorrect slug
"`#net-bird-only-access-private-services`" with the exact heading slug used on the
target authentication page; locate the anchor in bring-your-own-proxy.mdx (the
Markdown link that currently contains "`#net-bird-only-access-private-services`")
and change it to the correct slug copied from the Authentication page's heading
so the in-page navigation works.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 79e4521e-93a0-46c2-b688-1cc8f32c359f

📥 Commits

Reviewing files that changed from the base of the PR and between a28e476 and 4a43dcb.

⛔ Files ignored due to path filters (5)

public/docs-static/img/manage/reverse-proxy/authentication/auth-netbird-only-modal.png is excluded by !**/*.png
public/docs-static/img/manage/reverse-proxy/authentication/reverse-proxy-add-service-auth.png is excluded by !**/*.png
public/docs-static/img/manage/reverse-proxy/byop/byop-clusters-private-feature.png is excluded by !**/*.png
public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-auth.png is excluded by !**/*.png
public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-target.png is excluded by !**/*.png

📒 Files selected for processing (4)

src/pages/manage/reverse-proxy/authentication.mdx
src/pages/manage/reverse-proxy/bring-your-own-proxy.mdx
src/pages/manage/reverse-proxy/index.mdx
src/pages/manage/reverse-proxy/service-configuration.mdx

…rol baseline behavior, added details on Direct Upstream and Proxy Cluster features, and refined cluster capability descriptions.

coderabbitai

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/pages/manage/reverse-proxy/index.mdx (1)

252-252: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Broken anchor in Private services link.

The heading in bring-your-own-proxy.mdx is "## Private services (NetBird-Only Access)" which generates #private-services-netbird-only-access, but the link uses #private-services-net-bird-only-access (extra hyphen).

-For **Proxy Cluster** targets, the host field accepts any hostname or IP the cluster's embedded proxy can resolve from its own host stack — see [Private services](/manage/reverse-proxy/bring-your-own-proxy#private-services-net-bird-only-access) for details.
+For **Proxy Cluster** targets, the host field accepts any hostname or IP the cluster's embedded proxy can resolve from its own host stack — see [Private services](/manage/reverse-proxy/bring-your-own-proxy#private-services-netbird-only-access) for details.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/pages/manage/reverse-proxy/index.mdx` at line 252, The "Private services"
anchor in the link is broken because the heading in bring-your-own-proxy.mdx is
"## Private services (NetBird-Only Access)" which generates the slug
"`#private-services-netbird-only-access`" but the current link uses
"`#private-services-net-bird-only-access`"; update the link target in
src/pages/manage/reverse-proxy/index.mdx (the link text "Private services") to
use "`#private-services-netbird-only-access`" so it matches the generated heading
slug.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/pages/manage/reverse-proxy/index.mdx`:
- Line 252: The "Private services" anchor in the link is broken because the
heading in bring-your-own-proxy.mdx is "## Private services (NetBird-Only
Access)" which generates the slug "`#private-services-netbird-only-access`" but
the current link uses "`#private-services-net-bird-only-access`"; update the link
target in src/pages/manage/reverse-proxy/index.mdx (the link text "Private
services") to use "`#private-services-netbird-only-access`" so it matches the
generated heading slug.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 08b02afa-89da-475b-a196-b59081f2beb5

📥 Commits

Reviewing files that changed from the base of the PR and between 4a43dcb and 7d5e1c6.

⛔ Files ignored due to path filters (4)

public/docs-static/img/manage/reverse-proxy/byop/byop-clusters-private-feature.png is excluded by !**/*.png
public/docs-static/img/manage/reverse-proxy/reverse-proxy-access-control-modal.png is excluded by !**/*.png
public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-settings.png is excluded by !**/*.png
public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-target.png is excluded by !**/*.png

📒 Files selected for processing (3)

src/pages/manage/reverse-proxy/authentication.mdx
src/pages/manage/reverse-proxy/bring-your-own-proxy.mdx
src/pages/manage/reverse-proxy/index.mdx

…ion details

Documented NetBird-Only Access and Proxy Cluster features in reverse …

4a43dcb

…proxy settings. Updated authentication methods, backend configuration guides, and cluster capability requirements.

This was referenced May 24, 2026

[management, client, proxy] add expose NetBird-only services over tunnel peers netbirdio/netbird#6226

Merged

Feature/private service expose netbirdio/dashboard#646

Merged

coderabbitai Bot reviewed May 24, 2026

View reviewed changes

Comment thread src/pages/manage/reverse-proxy/authentication.mdx

Comment thread src/pages/manage/reverse-proxy/bring-your-own-proxy.mdx

Expanded documentation for NetBird-Only services, updated Access Cont…

7d5e1c6

…rol baseline behavior, added details on Direct Upstream and Proxy Cluster features, and refined cluster capability descriptions.

coderabbitai Bot reviewed May 25, 2026

View reviewed changes

add private services diagrams and update auth screenshot

f78f73d

mlsmaycon mentioned this pull request Jun 4, 2026

Update reverse proxy modals netbirdio/dashboard#661

Merged

2 tasks

Document ProxyService gRPC routes and expand reverse proxy configurat…

522b097

…ion details

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documented NetBird-Only Access and Proxy Cluster features in reverse …#767

Documented NetBird-Only Access and Proxy Cluster features in reverse …#767
mlsmaycon wants to merge 4 commits into
mainfrom
private-services

mlsmaycon commented May 24, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented May 24, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

mlsmaycon commented May 24, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mlsmaycon commented May 24, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 24, 2026 •

edited

Loading