netbird-operator
Skill4 starsChanged 5 months agoMITView on GitHub
NetBird Kubernetes operator (netbirdio/kubernetes-operator) — CRDs for exposing cluster services on the NetBird mesh, managing peers/routes/groups from inside K8s. Covers SetupKey, Group, NetworkRouter, NetworkResource, NetworkEgress, SidecarProfile, ClusterProxy.
- Reads credentials
In this repository74 other files it gives its agents.
- AGENTS.mdAGENTS.md
- atlasSkill
- cert-managerSkill
- cilium-gatewaySkill
- cilium-networkSkill
- cnpgSkill
- dragonflySkill
- external-dnsSkill
- external-secretsSkill
- flaggerSkill
- fluxSkill
- gitea-apiSkill
- gitea-registrySkill
- gitea-runnerSkill
- giteaSkill
- gitea-teaSkill
- gitea-webhooksSkill
- harbor-apiSkill
- harbor-helmSkill
- harborSkill
- harbor-terraformSkill
- helm-chartSkill
- helm-opsSkill
- helmSkill
- higress-helmSkill
- higress-operatorSkill
- higressSkill
- kserve-helmSkill
- kserve-operatorSkill
- kserveSkill
- kubeflow-pipelinesSkill
- kubeflowSkill
- kubeflow-trainerSkill
- kubeflow-training-operatorSkill
- mariadb-helmSkill
- mariadb-operatorSkill
- mariadbSkill
- netbird-cliSkill
- netbird-serverSkill
- netbirdSkill
- netbird-terraformSkill
- nextcloud-apiSkill
- nextcloud-helmSkill
- nextcloudSkill
- nvidia-device-pluginSkill
- rook-ceph-operatorSkill
- rook-cephSkill
- rook-ceph-toolboxSkill
- sealed-secretsSkill
- stakater-reloaderSkill
- tailscaleSkill
- tailscale-talosSkill
- talosconfigSkill
- talosctlSkill
- talosSkill
- talos-terraformSkill
- tekton-operatorSkill
- tekton-pacSkill
- tekton-pipelinesSkill
- tektonSkill
- The first 60 shown.
The file
Files
netbird-operator — Kubernetes Operator
For client CLI see netbird-cli. For Terraform provider see netbird-terraform.
Repo: github.com/netbirdio/kubernetes-operator
Chart: ghcr.io/netbirdio/helm-charts/netbird-operator (latest 0.8.0)
API group: netbird.io/v1alpha1
Automates NetBird provisioning for services in your cluster: peers, routes, groups declared as CRs. Setup keys and credentials auto-stored/rotated as Kubernetes Secrets. Works with NetBird Cloud and self-hosted.
Install
# 1. cert-manager (for admission webhooks) — recommended
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.0/cert-manager.yaml
# 2. Namespace + API secret (NetBird PAT for the Management API)
kubectl create namespace netbird
kubectl -n netbird create secret generic netbird-mgmt-api-key \
--from-literal=NB_API_KEY=${NB_API_KEY}
# 3. Install operator
helm upgrade --install --create-namespace -n netbird \
netbird-operator oci://ghcr.io/netbirdio/helm-charts/netbird-operator
# 4. Verify
kubectl get pods -n netbird # all Running before creating CRsPAT: create a service user in the NetBird dashboard and generate a Personal Access Token.
CRDs (netbird.io/v1alpha1)
| Kind | Purpose |
SetupKey | Declarative setup key (auto-groups, expiry, ephemeral, extra DNS labels) |
Group | Group (by name, id, or localRef to another Group CR) |
NetworkRouter | Expose a ClusterIP Service via a shared routing peer + DNS zone |
NetworkResource | Expose an address/domain as a Network resource (networkRouterRef) |
NetworkEgress | Give a pod's network egress onto the NetBird overlay |
SidecarProfile | Per-pod identity: inject netbird sidecar so the pod becomes its own peer |
ClusterProxy | Proxy the Kubernetes API server for netbird kubernetes + kubectl |
Patterns (choose by what you're exposing)
| Pattern | Exposes | Identity | Reach it via | Best for |
NetworkRouter | a ClusterIP Service | shared routing peer | service.namespace.<zone> DNS | stable internal services (DBs, APIs) many peers reach |
SidecarProfile (client sidecar) | the pod itself | pod = own peer | pod's overlay IP | workloads needing own identity / outbound overlay access |
ClusterProxy (API server proxy) | the Kubernetes API | your NetBird user | netbird kubernetes + kubectl | operating remote clusters |
| Gateway API (Beta) | Services via Gateway CRDs | gateway routing peer | route hostname / overlay | teams standardizing on Gateway API |
Rule of thumb: routing peer (NetworkRouter) for "peers reach my service" — one peer fronts many services. Sidecar for "this pod initiates traffic onto the overlay / needs per-pod identity" (cost: one peer per pod). A routing peer exposes services TO your peers; it does NOT give other pods a path OUT onto the overlay — that needs a sidecar.
SetupKey Example
apiVersion: netbird.io/v1alpha1
kind: SetupKey
metadata:
name: my-setup-key
namespace: netbird
spec:
name: my-setup-key # key name in NetBird
ephemeral: false
allowExtraDnsLabels: false
duration: 24h # validity (pattern: 1h, 30m, 24h…)
autoGroups: # auto-assign peers using this key
- name: my-group # localRef to a Group CR in same namespaceThe operator stores the generated setup key in a Secret (status tracks it) for consumption by workloads.
NetworkRouter Example (expose a Service)
apiVersion: netbird.io/v1alpha1
kind: NetworkRouter
metadata:
name: my-db-router
namespace: netbird
spec:
networkRouterRef: # the NetBird network + router to attach to
name: my-network
namespace: netbird
serviceRef: # ClusterIP Service to expose
name: my-db
groups: # who can reach it (NetBird groups)
- name: my-group
# zone: <DNSZoneReference> # optional DNS zone by domain nameResult: peers in my-group reach the service at my-db.<namespace>.<zone> DNS name through the shared routing peer.
NetworkResource Example
apiVersion: netbird.io/v1alpha1
kind: NetworkResource
metadata:
name: my-resource
namespace: netbird
spec:
networkRouterRef:
name: my-network
namespace: netbird
serviceRef: # or a raw address
name: my-service
groups:
- name: my-group
# address: 10.0.0.5 # single IP alternativeNetworkEgress (pod egress onto overlay)
Gives the pod's network a path out onto the NetBird network (opposite direction of NetworkRouter). Uses NetworkResourceSpec-style address/destination config.
ClusterProxy (kubectl access to remote clusters)
apiVersion: netbird.io/v1alpha1
kind: ClusterProxy
metadata:
name: my-cluster
namespace: netbird
spec:
clusterName: my-cluster # required
apiServer: https://kubernetes.default.svc.cluster.local/ # required
serviceAccountName: my-impersonation-sa # required (impersonation)
groups: # NetBird groups allowed to access
- name: adminsUser side:
netbird kubernetes list
netbird kubernetes write-kubeconfig my-cluster
kubectl get nodes # through the NetBird tunnelOperations
kubectl get setupkeys,groups,networkrouters,networkresources,networkegresses,sidecarprofiles,clusterproxies -A
kubectl get secret -n netbird # setup keys + API key secrets
kubectl describe networkrouter my-db-router # status + conditionsNamespace-scoped or cluster-wide deployment; per-namespace for multi-tenant clusters.
Common Mistakes
- Two sources of truth for the same key —
SetupKeyCRD vs Terraformnetbird_setup_key: pick ONE per key or they drift. - Routing peer ≠ pod egress — NetworkRouter exposes services to peers; it does NOT let pods reach the overlay. Pods need
SidecarProfile/NetworkEgress. - NetworkRouter reach vs routing-peer-host reach — the resource policy reaches services BEHIND the routing peer; reaching services ON the routing peer host needs a separate peer-to-peer policy (input chain).
- Forgetting cert-manager — webhook-backed CRDs fail without it;
helm installlooks fine but CR validation/admission breaks. netbird-mgmt-api-keysecret name mismatch — the chart expects this exact secret name +NB_API_KEYkey. Change either and the operator can't authenticate.- Service user PAT, not personal PAT — operator auth uses service-user tokens; personal tokens may lack account-level permissions.
- Gateway API still Beta — prefer NetworkRouter/SidecarProfile for anything you depend on today.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

