sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-10-25 14:09:04 +01:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* Documented NetBird-Only Access and Proxy Cluster features in reverse proxy settings. Updated authentication methods, backend configuration guides, and cluster capability requirements.

* Expanded documentation for NetBird-Only services, updated Access Control baseline behavior, added details on Direct Upstream and Proxy Cluster features, and refined cluster capability descriptions.

* add private services diagrams and update auth screenshot

* Document ProxyService gRPC routes and expand reverse proxy configuration details

---------

Co-authored-by: TechHutTV <brandon@techhut.tv>
This commit is contained in:
Maycon Santos
2026-06-05 08:16:03 -07:00
committed by GitHub
co-authored by TechHutTV
parent 4ea4552b18
commit c2ccdf43e0
17 changed files with 295 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/pages/manage/reverse-proxy/bring-your-own-proxy.mdx
+36 -2
View File
@@ -41,7 +41,14 @@ NetBird recognises two cluster types, distinguished by the `type` field on the `
| **Visible to other accounts** | Yes, as an available cluster in their service-creation flow | No — only the owning account sees it |
| **Delete from dashboard** | Not allowed | Allowed (account owner only) |
Both cluster types appear together on the **Clusters** page. The **Type** badge next to the cluster name marks each row as **shared** or **account**, the **Status** column shows whether at least one proxy in the cluster has heartbeated within the last two minutes, and the **Features** column lists the capabilities reported by the connected proxies (custom-port L4 support, subdomain requirement, CrowdSec IP-reputation enforcement).
Both cluster types appear together on the **Clusters** page. The **Type** badge next to the cluster name marks each row as **shared** or **account**, the **Status** column shows whether at least one proxy in the cluster has heartbeated within the last two minutes, and the **Features** column lists the capabilities reported by the connected proxies:
| Feature badge | Meaning |
|---------------|---------|
| **Custom Ports** | The cluster can bind arbitrary TCP/UDP listen ports for L4 services. |
| **Subdomain Required** | Services on this cluster must use a subdomain — the bare cluster apex is not addressable. |
| **CrowdSec** | The cluster has CrowdSec IP-reputation configured across all active proxies. |
| **Private** | The cluster can publish services that are only reachable from peers in your NetBird network. Required to enable [NetBird-Only Access](/manage/reverse-proxy/authentication#netbird-only-access-private-services) and the **Proxy Cluster** target type on services. Activated when at least one connected proxy in the cluster runs as an embedded NetBird peer (`netbird proxy`). |
When creating a service you pick a base domain from any cluster you can reach: shared clusters are always available; account clusters appear only for the account that owns them. There is no functional difference at the data-plane — services on either cluster type behave identically once a request lands. The choice is operational: shared clusters are zero-effort, account clusters give you control over location, TLS, and the data path.
@@ -194,6 +201,33 @@ Once the cluster is connected, your BYOP domain shows up in the service creation
Traffic to `subdomain.proxy.company.com` is now received by your BYOP proxy, terminated locally with a Let's Encrypt certificate, and forwarded over WireGuard to the target peer or network resource.
## Private services (NetBird-Only Access)
A BYOP cluster whose proxy runs embedded as a NetBird peer (`netbird proxy` mode — the default for the `netbirdio/reverse-proxy` image) reports the `Private` capability if started with the flag `--private` or environment variable `NB_PROXY_PRIVATE=true`. With that capability set, the cluster unlocks two new options anywhere it is selected:
- **NetBird-Only Access** on the service's **Authentication** tab — turn the service into a *private service* that only peers in your NetBird network can reach. See [NetBird-Only Access](/manage/reverse-proxy/authentication#net-bird-only-access-private-services) for the full behaviour, identity-header semantics, and access-group rules.
- **Proxy Cluster** in the target picker — point the service at a hostname or IP that the embedded proxy can resolve directly from its own host stack (without WireGuard), with **Direct Upstream** locked on. Useful when the upstream is co-located with the BYOP proxy and you do not need (or want) to route it through the mesh.
With a **Proxy Cluster** target (or **Direct Upstream** enabled on a peer/resource target), the service is still reachable only over the NetBird tunnel and still gated by group membership, but the proxy reaches the upstream directly via its host network stack — no WireGuard peer is required between the proxy and the backend:
<p>
<img src="/docs-static/img/manage/reverse-proxy/byop/netbird-only-direct-upstream-diagram.png" alt="Diagram of a NetBird-Only service with Direct Upstream: the device tunnels to the proxy cluster, the management service checks group membership, and the proxy reaches the backend service directly over the host network stack with no WireGuard peer" className="imagewrapper-big"/>
</p>
NetBird Cloud's shared clusters do not currently advertise `Private`. Running your own BYOP cluster is the supported way to enable private services for an account on Cloud. For self-hosted, the same applies — the proxy must be running with the flag set.
When the selected base domain does *not* advertise the `Private` capability:
- The **NetBird-Only Access** row on the Authentication tab is greyed out, with a tooltip explaining the requirement.
- The **Proxy Cluster** option is hidden from the target picker.
- **Direct Upstream** is locked off in service settings.
To verify the capability is set, check the cluster row on the **Clusters** page — a **Private** badge appears in the Features column when at least one connected proxy is running in embedded mode.
<p>
<img src="/docs-static/img/manage/reverse-proxy/byop/byop-clusters-private-feature.png" alt="Clusters page row showing the Private feature badge in the Features column" className="imagewrapper-big"/>
</p>
## High availability
Run multiple proxy replicas with the **same** `NB_PROXY_TOKEN` and **same** `NB_PROXY_DOMAIN` to form an HA cluster within your account. Each replica:
@@ -264,7 +298,7 @@ docker run -d \
### Manage clusters
The **Clusters** page lists each cluster reachable from your account, its **Online** status, the count of currently connected proxies, and the feature flags (custom ports, subdomain requirement, CrowdSec) reported by its proxies. The same data is available via `GET /api/reverse-proxies/clusters` — each entry carries a `type` field (`"account"` for BYOP clusters you own, `"shared"` for platform-managed clusters). The **Delete** action is only available on account clusters. From the page you can:
The **Clusters** page lists each cluster reachable from your account, its **Online** status, the count of currently connected proxies, and the feature flags (custom ports, subdomain requirement, CrowdSec, private) reported by its proxies. The same data is available via `GET /api/reverse-proxies/clusters` — each entry carries a `type` field (`"account"` for BYOP clusters you own, `"shared"` for platform-managed clusters). The **Delete** action is only available on account clusters. From the page you can:
- **Refresh** to pull fresh status.
- **Delete** an account cluster — this removes the cluster's database record and hides it from the API and dashboard. The same is exposed as `DELETE /api/reverse-proxies/clusters/{clusterAddress}`. Note that any proxy process still running with the cluster's token keeps its gRPC stream open until you stop it or revoke the token. To fully tear down an account cluster, delete it *and* either stop the proxy container or revoke its token.