NetBird Operator
Kubernetes operator for managing NetBird peers and network access via CRDs.
About
NetBird Kubernetes Operator automates the management of NetBird peers and network access policies within a Kubernetes cluster. It connects cluster workloads to a NetBird overlay network, enabling secure, peer-to-peer WireGuard-based connectivity between the cluster and external devices or other clusters. It is used in this cluster to declaratively manage cluster egress via the NetBird network, with API credentials stored in a SOPS-encrypted Secret.
AlternativeTo
Self Hosted
| Tool | Open Source | Full Features | Notes |
|---|---|---|---|
| Tailscale Operator | Yes (client) | Yes | Similar overlay network; proprietary control plane |
| Headscale | Yes | Partial | Self-hosted Tailscale control plane; no k8s operator |
| Wireguard + Kilo | Yes | Yes | Pure WireGuard mesh; no managed control plane |
Installation
Architecture
HelmRelease netbird-operator in namespace netbird, chart kubernetes-operator version 0.2.0 from https://netbirdio.github.io/helms. Ingress and router enabled in values. Cluster DNS set to svc.cluster.local, cluster name talos. NetBird API key loaded from a SOPS-encrypted Secret (netbird-operator-secret).
Security
NetBird API key is stored in a SOPS-encrypted Secret (age-encrypted). The operator reads the key via keyFromSecret. No custom securityContext in HelmRelease values. RBAC is namespaced to the netbird namespace for operator resources, with cluster-level access for managing peers.
Updates
Managed by Renovate. Chart version is semver-pinned (0.2.0).
Administration
Usage
Operators create NetBirdPeer or equivalent CRDs to register cluster workloads as peers in the NetBird network. The router component enables traffic routing between the cluster network and the NetBird overlay. This allows external NetBird peers (laptops, home servers) to reach cluster-internal services securely over WireGuard without exposing them on the public internet.
Metadata
- HelmRelease:
kubernetes-operator@0.2.2