Skip to main content

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

ToolOpen SourceFull FeaturesNotes
Tailscale OperatorYes (client)YesSimilar overlay network; proprietary control plane
HeadscaleYesPartialSelf-hosted Tailscale control plane; no k8s operator
Wireguard + KiloYesYesPure 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.

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

Cluster Deployment​

NetBird Operator — Talos cluster

Cluster-specific notes only. General product info, "why we use it", and alternatives live in docusaurus/docs/platform/netbird-operator.mdx.

Deviations from defaults​

Defaults live in docusaurus/docs/platform/netbird-operator.mdx — document anything this cluster does differently here, with a one-line reason.

Kubernetes Metadata
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