From 9448ae30dd1167f84d69509c5b1b39b09db285fb Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Fri, 3 Jul 2026 12:26:48 +0200 Subject: [PATCH] docs: add "Choosing a pattern" section to K8s getting started (#811) * 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 --- .../manage/integrations/kubernetes/index.mdx | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/src/pages/manage/integrations/kubernetes/index.mdx b/src/pages/manage/integrations/kubernetes/index.mdx index cf75050c..662337a8 100644 --- a/src/pages/manage/integrations/kubernetes/index.mdx +++ b/src/pages/manage/integrations/kubernetes/index.mdx @@ -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.`) | 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) | 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. + + +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. +