Access Kubernetes privately with NetBird

Operating Kubernetes without exposing its API and internal services publicly? WZ-IT connects clusters, sites and authorized users through self-hosted NetBird, including network design, policies, SSO and ongoing operations. Kubernetes networking and secure access

A private Kubernetes cluster presents three distinct access questions:

1. How do administrators use kubectl without exposing the cluster API publicly?
2. How do users or systems reach selected internal applications, databases and dashboards?
3. How does an individual workload initiate a connection from the cluster to a private site or service?

NetBird provides separate patterns for these tasks. It creates a WireGuard-based overlay across users, devices, sites and clusters. The Kubernetes Operator manages the integration declaratively through custom resources. The important part is not to solve every task with the same tunnel: API Server Proxy, routing peer and client sidecar answer different questions.

Contents

• What NetBird adds to Kubernetes
• The four integration patterns
• Pattern 1: API Server Proxy for kubectl
• Pattern 2: routing peer for internal services
• Pattern 3: sidecar for workload identity
• Pattern 4: Gateway API as a Beta path
• Policies and identity
• High availability and failure behavior
• Self-hosted and sovereign operations
• Reference architecture
• A six-step introduction

What NetBird adds to Kubernetes

NetBird does not replace Kubernetes networking. The CNI plugin remains responsible for Pod-to-Pod communication, Service routing and NetworkPolicies inside the cluster. Ingress or Gateway API still exposes regular application traffic when it should be public or reachable from a corporate network.

NetBird adds another layer:

• encrypted WireGuard connections between authorized peers,
• identities and groups rather than broad network access,
• policies for defined sources, destinations, ports and protocols,
• outbound-only connectivity for users and sites behind NAT,
• private DNS names for shared resources,
• an optional self-hosted control plane.

What is NetBird? explains the general model. In Kubernetes, it becomes a controlled management and service access layer.

The four integration patterns

The current NetBird Kubernetes documentation distinguishes four patterns:

The patterns do not compete. One cluster can use the API Server Proxy for administration while routing peers expose Grafana, an internal API or PostgreSQL.

Pattern 1: API Server Proxy for kubectl

The Kubernetes API is the cluster's most powerful interface. A public endpoint protected only by credentials increases attack surface and makes a clear network boundary harder to maintain.

The NetBird API Server Proxy exposes the API over the private NetBird network. Administrators use their NetBird identity while the integration connects access and permission information to the API request. This enables remote cluster operations without exposing the normal API endpoint generally to the internet.

Two levels remain important:

• NetBird policy: who may use the network path to this cluster at all?
• Kubernetes authorization: which verbs and resources may that identity access inside the cluster?

Least privilege means not granting every NetBird user cluster-admin permissions. Operating roles, read-only access, deployments and break-glass administration should be separate. NetBird and Kubernetes audit logs should make the same identity traceable.

Pattern 2: routing peer for internal services

For a stable internal service reached by several authorized peers, NetBird recommends a routing peer by default. The operator combines two resources:

• NetworkRouter: creates or references a NetBird Network and starts routing-peer Pods in the cluster.
• NetworkResource: attaches a Kubernetes Service as an exposed resource to that router.

According to the routing-peer documentation, the Service ClusterIP becomes the resource address. A name following service.namespace.zone is added to the assigned private DNS zone. A client can therefore reach Grafana or an internal API without making the Service a LoadBalancer or adding public ingress.

This pattern fits:

• Grafana, Argo CD and internal administration interfaces,
• databases and message brokers for defined operating groups,
• internal APIs between sites and a platform,
• staging and test environments without public endpoints,
• services in several clusters with separate DNS zones.

A routing peer gives external NetBird peers a path to the Service. It does not automatically give every Pod in the cluster an outbound path into the complete NetBird network.

Pattern 3: sidecar for workload identity

When a Pod itself must initiate overlay connections or appear as a distinct identity in policy and audit, the operator uses a client sidecar. A NetBird container is injected into matching Pods and each Pod becomes a separate peer.

Common cases include:

• an ephemeral CI job accessing a private destination,
• an integration service reaching a customer site data source,
• workloads requiring separate policy rather than one gateway identity,
• a Pod that must be directly addressable by another NetBird peer.

The benefit is more granular identity. The cost is additional resource and management overhead for each Pod. A shared routing peer is therefore normally leaner for one service reached by many users. The NetBird sidecar documentation describes assignment through sidecar profiles and Pod selectors.

Pattern 4: Gateway API as a Beta path

NetBird also integrates with Kubernetes Gateway API. Services are connected to the overlay through Gateway resources and hostnames. Gateway API is developing into the common successor or complement to classic Ingress interfaces.

NetBird documentation marks this integration as Beta as of July 8, 2026 and recommends routing peers or sidecars for paths on which production depends today. The current maturity must be reviewed before implementation. Architecture decisions should not rely solely on an expected future status.

Policies and identity

The technical connection is only transport. The security model comes from unambiguous identities and narrow policies.

Dedicated groups

Routing peers, cluster administrators, developers and service identities belong in separate groups. NetBird documentation explicitly advises against broadly assigning operator resources to the All group. The operator also does not write access policies automatically. Without a deliberately defined policy, the model is incomplete.

Separate access classes

For example:

• k8s-prod-operators may access the production API,
• observability-readers reaches Grafana over HTTPS,
• ci-deploy-prod may reach a GitOps or deployment endpoint,
• support-customer-a sees only services released for that tenant,
• break-glass access follows a separate monitored process.

SSO, MFA and lifecycle

NetBird can connect to an identity provider, tying user access to SSO, MFA and groups. Kubernetes RBAC and potentially OIDC should follow the same role model. Offboarding must include peers, users, setup keys, service accounts and existing kubeconfigs.

Defense in depth

NetBird policies do not replace Kubernetes NetworkPolicies. The overlay path restricts who reaches the cluster. NetworkPolicies restrict which Pods may communicate inside it. Application authentication, TLS and Kubernetes RBAC remain independent controls.

High availability and failure behavior

A private access path can itself become a critical component. Production planning should answer:

• Do several routing-peer replicas run on independent workers?
• Do anti-affinity and Pod Disruption Budgets prevent a common maintenance failure?
• Is sufficient cluster capacity available for rescheduling?
• How do direct WireGuard connections and relay fallback behave during network faults?
• Is the NetBird control plane redundant and monitored?
• Which services should continue using established connections during a control-plane outage?

NetBird provides dedicated guidance for highly available routing peers. Independent of the specific manifest, connectivity, DNS, policy distribution and recovery belong in operating and failure tests.

Self-hosted and sovereign operations

NetBird can be consumed as a cloud service or self-hosted. In a sovereign model, management, signal and relay components run on private or selected European infrastructure. The cluster can likewise run on Proxmox, bare metal or European cloud servers.

Self-hosting transfers responsibility to the operator:

• updates and security patches for NetBird components,
• availability of management, signal, relay and the identity provider,
• configuration backup and recovery,
• certificates, DNS and any publicly required control-plane endpoints,
• monitoring, logs and capacity,
• secure handling of API tokens and setup keys.

Sovereignty is not created merely by running your own container. It requires controlled infrastructure and a dependable lifecycle.

Reference architecture

Administrators / developers / CI
              │
              │ NetBird identity + policy
              ▼
        self-hosted control plane
              │
      WireGuard overlay / relay fallback
              │
    ┌─────────┴──────────────────────┐
    │                                │
API Server Proxy             routing-peer Pods
    │                                │
Kubernetes API           selected ClusterIP Services
                                     │
                    Grafana · Argo CD · API · database

Separately: Pod + NetBird sidecar ──► private site / service

The regular application can still use public ingress or Gateway in parallel. NetBird protects administration and selected internal services. It does not have to become the data path for every public user.

A six-step introduction

1. Capture access classes: separate API administration, internal services and outbound workload connections.
2. Validate network namespaces: Pod, Service, site and NetBird address ranges must not overlap.
3. Define identity: establish IdP, MFA, groups, service accounts, setup keys and offboarding.
4. Choose one pattern per objective: API Server Proxy, routing peer or sidecar, not everything by default.
5. Connect policy layers: test NetBird access policies, RBAC, NetworkPolicies and application authentication together.
6. Prove operations: test routing-peer failure, node maintenance, DNS, policy changes, token rotation and emergency access.

Conclusion

NetBird prevents a private Kubernetes cluster from becoming an isolated island. Authorized people, sites and workloads receive exactly the path they need without publishing the API, dashboards and databases to the general internet.

The key is composition: API Server Proxy for cluster administration, routing peers for shared services and sidecars for individual workload identity. CNI, RBAC, NetworkPolicies and application security remain in place and gain an identity-aware access layer.

WZ-IT designs and operates this chain end to end, from Kubernetes infrastructure through self-hosted NetBird to SSO, policies, monitoring and incident response.

Sources

• NetBird documentation: Kubernetes Operator and pattern selection
• NetBird documentation: Routing peer
• NetBird documentation: Client sidecar
• NetBird documentation: API Server Proxy
• NetBird documentation: Gateway API
• Kubernetes documentation: Network Policies
• Kubernetes documentation: RBAC