docs: add "Choosing a pattern" section to K8s getting started by SunsetDrifter · Pull Request #811 · netbirdio/docs

SunsetDrifter · 2026-06-23T15:51:44Z

Summary

Adds a Choosing a pattern section to the Kubernetes operator Getting Started page. After installing the operator, readers face several ways to connect a cluster (routing peer, client sidecar, API server proxy, Gateway API) and currently have no guidance on which to pick. This section makes that choice explicit.

It adds:

A decision table comparing Routing Peer / Client Sidecar / API Server Proxy / Gateway API (Beta) across what they expose, identity, how you reach them, and what they're best for — each linked to its reference page.
Rules of thumb, including the common point of confusion: a sidecar (not a routing peer) is the answer when a pod needs its own identity or to originate traffic onto the overlay, and a routing peer exposes services to peers rather than giving in-cluster pods a path out.
A deny-by-default note (the operator does not write your access policies).

Changes

src/pages/manage/integrations/kubernetes/index.mdx — new ## Choosing a pattern section (+23 lines).

Note

The routing-peer row links to the use-cases/route-to-a-kubernetes-service how-to, which is added in a separate PR. Merge that one first (or together) so the link resolves.

Summary by CodeRabbit

Documentation
- Added guidance on Kubernetes operator connection patterns, including a comparison table and recommendations for when to use each pattern (Routing Peer, Client Sidecar, API Server Proxy, Gateway API).
- Clarified that NetBird is deny-by-default and users must create appropriate access policies.

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.

coderabbitai · 2026-06-23T15:54:31Z

📝 Walkthrough

Walkthrough

A new "Choosing a pattern" section is added to the Kubernetes operator integration documentation. It includes a comparison table of the four connection patterns, a rules-of-thumb bullet list for selecting among them, and a note about NetBird's deny-by-default behavior requiring users to create an explicit access policy.

Changes

Kubernetes Operator Integration Docs

Layer / File(s)	Summary
Pattern selection guidance and access policy note `src/pages/manage/integrations/kubernetes/index.mdx`	Adds a "Choosing a pattern" subsection with a four-column comparison table (Routing Peer, Client Sidecar, API Server Proxy, Gateway API), a rules-of-thumb list for default pattern selection, and a note clarifying deny-by-default behavior with instructions to use a dedicated peer group and create an allow policy.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

A bunny hops through Kubernetes land,
With patterns and tables close at hand 🐇
Routing peers, sidecars — which to pick?
The rules of thumb do the trick!
Deny by default, don't forget —
Create your policy, no regret! 🌿

🚥 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 accurately and specifically describes the main change: adding a 'Choosing a pattern' section to Kubernetes documentation.
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 cc/k8s-choosing-a-pattern

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/manage/integrations/kubernetes/index.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.}

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/pages/manage/integrations/kubernetes/index.mdx (1)
50-52: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Minor: Consider tightening the introductory sentence.

Line 52 uses "rather than competing with each other," which is clear but slightly verbose. Given the "Chill" review strictness and the phrasing's pedagogical value (emphasizing complementarity), this is optional—feel free to keep it as-is for readability.
🤖 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/integrations/kubernetes/index.mdx` around lines 50 - 52, In
the "Choosing a pattern" section, the introductory sentence contains the verbose
phrase "rather than competing with each other" which could be tightened for
clarity. Consider removing or rephrasing this phrase while preserving the key
pedagogical message that these are complementary approaches that answer
different questions based on what you're exposing and whether each workload
needs its own identity.

🤖 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/integrations/kubernetes/index.mdx`:
- Around line 54-59: The Badge component used on line 59 in the diff is
currently imported from an incorrect source according to coding guidelines.
Locate the import statement for the Badge component (currently importing from
`@/components/Badge`) on line 29 and update it to import from `@/components/mdx`
instead. This ensures all component imports comply with the established coding
standards for this project.

---

Nitpick comments:
In `@src/pages/manage/integrations/kubernetes/index.mdx`:
- Around line 50-52: In the "Choosing a pattern" section, the introductory
sentence contains the verbose phrase "rather than competing with each other"
which could be tightened for clarity. Consider removing or rephrasing this
phrase while preserving the key pedagogical message that these are complementary
approaches that answer different questions based on what you're exposing and
whether each workload needs its own identity.

🪄 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: 198d9194-0fe2-40ca-a0b0-43064470aa8d

📥 Commits

Reviewing files that changed from the base of the PR and between 6b4aa80 and 9fcc7ad.

📒 Files selected for processing (1)

src/pages/manage/integrations/kubernetes/index.mdx

phillebaba · 2026-06-29T12:53:47Z

+
+| Pattern | Exposes | Identity | Reach it via | Best for |
+|---|---|---|---|---|
+| [Routing Peer](/manage/integrations/kubernetes/routing-peer) | a `ClusterIP` Service | a shared routing peer | DNS name (`service.namespace.zone`) | stable internal services (databases, APIs) that many peers reach |


The resource in the operator is called a NetworkRouter. Maybe good to stick with that?

Also the dns name is not correct. It is the zone set in the Network router itself.

coderabbitai Bot reviewed Jun 23, 2026

View reviewed changes

Comment thread src/pages/manage/integrations/kubernetes/index.mdx

phillebaba reviewed Jun 29, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

docs: add "Choosing a pattern" section to K8s getting started#811
SunsetDrifter wants to merge 1 commit into
mainfrom
cc/k8s-choosing-a-pattern

SunsetDrifter commented Jun 23, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 23, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

phillebaba Jun 29, 2026

Uh oh!

phillebaba Jun 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

SunsetDrifter commented Jun 23, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Note

Summary by CodeRabbit

Uh oh!

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

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

phillebaba Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

phillebaba Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SunsetDrifter commented Jun 23, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 23, 2026 •

edited

Loading