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

docs: add "Choosing a pattern" section to K8s getting started (#811)

Browse Source 
* docs: add 'Choosing a pattern' overview to K8s getting started

Add a decision table and rules of thumb covering routing peer vs client
sidecar vs API server proxy vs Gateway API, so readers can pick the right
operator pattern. Clarifies that a sidecar (not a routing peer) is the
answer when a pod needs its own identity or to originate traffic onto the
overlay.

* docs: name the NetworkRouter CRD and clarify its DNS zone in the pattern table
This commit is contained in:
Jack Carter
2026-07-03 12:26:48 +02:00
committed by GitHub
parent 955ba43566
commit 9448ae30dd
1 changed files with 23 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
src/pages/manage/integrations/kubernetes/index.mdx
View File

@@ -46,3 +46,26 @@ All pods should be in a `Running` state before continuing.
NAME READY STATUS RESTARTS AGE
netbird-operator-b74984867-d68c8 1/1 Running 0 98s
```
## Choosing a pattern
The operator supports several ways to connect a cluster, and they answer **different questions** rather than competing with each other. Pick by **what you're exposing** and **whether each workload needs its own identity**.
| Pattern | Exposes | Identity | Reach it via | Best for |
|---|---|---|---|---|
| [NetworkRouter](/manage/integrations/kubernetes/routing-peer) | a `ClusterIP` Service | a shared routing peer | a DNS name in the NetworkRouter's zone (`service.namespace.<zone>`) | stable internal services (databases, APIs) that many peers reach |
| [Client Sidecar](/manage/integrations/kubernetes/client-sidecar) | the pod itself | the pod becomes its own peer | the pod's overlay IP | workloads that need their own identity or per-pod access rules (ephemeral CI jobs, per-pod audit) |
| [API Server Proxy](/manage/integrations/kubernetes/api-server-proxy) | the Kubernetes API | your NetBird user | `netbird kubernetes` + `kubectl` | operating remote clusters with `kubectl` |
| [Gateway API](/manage/integrations/kubernetes/gateway-api) <Badge status="experimental" text="Beta" /> | Services via Gateway CRDs | a gateway routing peer | route hostname / overlay | teams standardizing on Gateway API CRDs |
### Rules of thumb
- **Default to a routing peer** for "let my peers reach a service in this cluster." One routing peer fronts many services and is the cheapest to operate — see the [Route to a Kubernetes service](/manage/integrations/kubernetes/use-cases/route-to-a-kubernetes-service) how-to, including how to run it highly available.
- **Reach for a client sidecar** only when per-pod identity matters. The pod becomes a first-class peer: it can be reached directly *and* originate connections out onto the NetBird network as itself. That's why a sidecar — not a routing peer — is the answer when a workload needs to *initiate* traffic onto the overlay. The cost is one peer per pod, so it's more to manage than a shared gateway.
- **A routing peer exposes in-cluster services to your peers; it does not give other pods in the cluster a path out onto the overlay.** If an in-cluster workload needs to reach the NetBird network, give that pod a sidecar.
- **The API Server Proxy is orthogonal** — it's about *operating* the cluster, not reaching the apps inside it. Combine it with any of the others.
- **Gateway API is the future-standard surface but still Beta** — prefer the routing peer or sidecar for anything you depend on today.
<Note>
NetBird is deny-by-default and the operator does **not** write your access policies. Whichever pattern you choose, put your peers in a dedicated group (never `All`) and create a policy that allows the access you want.
</Note>