NetBird Operator

Kubernetes operator for managing NetBird peers and network access via CRDs.

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.

Alternatives considered

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 from https://netbirdio.github.io/helms, version pinned via Renovate. 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. The chart version is semver-pinned in the HelmRelease.

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.

Cluster-specific deviations from the above live in the per-cluster README — see k8s/platform/netbird-operator/talos/README.md.

Cluster Deployment

NetBird Operator — Talos cluster

Kubernetes Metadata

• HelmRelease: kubernetes-operator@0.3.1
• HelmRepo: netbird-operator (https://netbirdio.github.io/helms)

Rendered manifests (kustomize build)

apiVersion: v1
data:
  values.yaml: |
    ingress:
      enabled: true

    router:
      enabled: true

    cluster:
      dns: svc.cluster.local
      name: talos

    netbirdAPI:
      keyFromSecret:
        name: "netbird-operator-secret"
        key: "NETBIRD_API_KEY"
kind: ConfigMap
metadata:
  name: netbird-operator-values-76gb7g24c2
  namespace: netbird