netbird-server
Skill4 starsChanged 5 months agoMITView on GitHub
Self-hosted NetBird control plane on Kubernetes — the netbirdio/netbird-server combined management/signal/relay/STUN server + dashboard. Covers the helmforge/netbird chart, config.yaml, PostgreSQL store, embedded Dex IdP, gRPC/HTTP routing, STUN, and ESO secret delivery.
- 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-operatorSkill
- 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
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 174
Default dashboard auth matches the embedded issuer: clientId: netbird-dashboard, audience: netbird-dashboard, scopes openid profile email …
- Very specific: line 176
Dashboard + server must share one public hostname: when using the embedded provider.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
netbird-server — Self-Hosted Control Plane
Scope: This skill documents the helmforge/netbird chart (
repo.helmforge.dev,helmforge/netbird) deployment of the self-hosted control plane — the pattern used by the production talos-stack deployment. NetBird also ships an official self-hosted setup (docker-compose with optional Traefik); if you're following that path, the components are the same but the chart-specific values (database subchart, existingSecret keys, GRPCRoute wiring) don't apply. For the docker-compose variant see docs.netbird.io/selfhosted.
For the client agent see netbird-cli. For Terraform provider see netbird-terraform. For the K8s operator see netbird-operator (the operator consumes an EXISTING control plane — it does not deploy one).
What You're Deploying
The control plane is a single combined server (netbirdio/netbird-server) running management API, gRPC, signal, relay, metrics, health, and embedded STUN in one container, plus a separate dashboard (netbirdio/dashboard).
| Component | Image | Role |
| server | netbirdio/netbird-server | management + signal + relay + STUN + embedded IdP (Dex) |
| dashboard | netbirdio/dashboard | web UI (embedded nginx) |
Configured by a single config.yaml (replaces old management.json + relay.env). All services listen on HTTP inside the cluster; TLS terminates at your ingress/gateway — the proxy MUST support HTTP/2 / gRPC (h2c).
Ports to Expose
| Port | Proto | Purpose |
| 443 | TCP | dashboard, API, gRPC, signal, relay (via ingress/gateway) |
| 3478 | UDP | STUN (NAT traversal — CANNOT be proxied by HTTP reverse proxies) |
Install (helmforge/netbird chart)
helm repo add helmforge https://repo.helmforge.dev
helm upgrade --install netbird helmforge/netbird \
--namespace netbird --create-namespaceMinimal production values:
server:
publicUrl: https://netbird.example.com
replicaCount: 1 # sqlite requires 1; postgres can scale
auth:
issuer: https://netbird.example.com/oauth2 # embedded IdP issuer
config:
existingSecret: netbird-config # full config.yaml from secret
existingSecretKey: config.yaml
service:
annotations:
external-dns.alpha.kubernetes.io/hostname: netbird.example.com
dashboard:
replicaCount: 1
database:
mode: external # auto | external | sqlite
external:
engine: postgres # postgres | mysql
host: netbird-db-rw.netbird.svc
port: 5432
name: netbird
username: netbird
existingSecret: netbird-db
existingSecretPasswordKey: password # CNPG uses `password`, chart default is `database-password`
postgresql:
enabled: false # disable bundled subchart when database.mode=externalDatabase modes
| Mode | Use | Notes |
auto (default) | bundled HelmForge PostgreSQL subchart | production default |
external | your own DB (CNPG, managed PG) | engine: postgres or mysql |
sqlite | lab/disposable | MUST keep server.replicaCount: 1 |
Production = PostgreSQL (concurrent access, HA). The DSN lives in the config secret, not in values.
config.yaml delivery (ESO)
Chart renders a default config.yaml from values, OR use server.config.existingSecret for the full upstream config. Sensitive parts (authSecret, sessionCookieEncryptionKey, store DSN + encryptionKey, owner email/password, IdP seed) belong in an external secret store:
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
name: netbird-config
namespace: netbird
spec:
secretStoreRef: { name: vault, kind: ClusterSecretStore }
target: { name: netbird-config, creationPolicy: Owner }
data:
- secretKey: config.yaml
remoteRef: { key: kv/apps/netbird/config, property: config.yaml }
- secretKey: idp-seed
remoteRef: { key: kv/apps/netbird/config, property: idp-seed }Key config.yaml fields:
server:
listenAddress: ":443"
exposedAddress: "https://netbird.example.com:443" # public address peers use
stunPorts: [3478] # or `stuns:` for external
authSecret: "..." # required for local relay
dataDir: "/var/lib/netbird/"
auth:
issuer: "https://netbird.example.com/oauth2"
sessionCookieEncryptionKey: "" # 16/24/32 bytes or base64
dashboardRedirectURIs: ["https://app.example.com/nb-auth"]
cliRedirectURIs: ["http://localhost:53000/"]
owner: { email: "...", password: "..." } # initial admin
store:
engine: "postgres" # sqlite | postgres | mysql
dsn: "..." # from secret
encryptionKey: "" # from secretRouting (Cilium Gateway / any Gateway API)
gRPC must be routed via GRPCRoute (or an h2c backend). Plain HTTPRoute forwarding 404s GetServerKey — match by RPC service name (see netbirdio/netbird#5542):
apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
name: netbird-rpc
namespace: netbird
spec:
parentRefs:
- name: cilium-gateway
kind: Gateway
namespace: cilium-gateway
sectionName: https
hostnames: [netbird.example.com]
rules:
- matches:
- { method: { service: management.ManagementService } }
- { method: { service: signalexchange.SignalExchange } }
backendRefs: [{ name: netbird-server, port: 80 }]HTTP paths on the server: /api, /oauth2, /relay, /ws-proxy. Dashboard UI is everything else:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: netbird
namespace: netbird
spec:
parentRefs:
- name: cilium-gateway
kind: Gateway
namespace: cilium-gateway
sectionName: https
hostnames: [netbird.example.com]
rules:
- matches:
- { path: { type: PathPrefix, value: /api } }
- { path: { type: PathPrefix, value: /oauth2 } }
- { path: { type: PathPrefix, value: /relay } }
- { path: { type: PathPrefix, value: /ws-proxy } }
backendRefs: [{ name: netbird-server, port: 80 }]
- backendRefs: [{ name: netbird-dashboard, port: 80 }]Identity (embedded Dex + external IdP)
- Embedded IdP (Dex) is always enabled and serves
/oauth2/*(OIDC discovery at{issuer}/.well-known/openid-configuration). - Default dashboard auth matches the embedded issuer:
clientId: netbird-dashboard,audience: netbird-dashboard, scopesopenid profile email groups, redirects/nb-auth+/nb-silent-auth. - External IdP (ZITADEL, Keycloak, Okta): register a web app with PKCE (public client,
auth_method_type NONE), redirect URI = the Dex connector callbackhttps://<public-url>/oauth2/callback. Seed the Dex connector into the embedded IdP at startup viaIDP_SEED_INFOenv (base64 dex.Connector JSON from a secret). - Dashboard + server must share one public hostname when using the embedded provider. With an external OIDC provider, override ALL dashboard auth values (
AUTH_AUTHORITY,AUTH_CLIENT_ID,AUTH_AUDIENCE,AUTH_SUPPORTED_SCOPES).
Terraform + Operator Integration
- Manage account topology (groups, peers, routes, networks, policies, setup keys, DNS) via the
netbird-terraformskill, pointingmanagement_urlat the in-cluster API (https://netbird.example.comornetbird-server.netbird.svc:80from inside the cluster). - The
netbird-operator(separate chartnetbirdio/helm-charts) connects to this control plane viamanagementURL+ a service-user PAT (NB_API_KEY). It does NOT deploy the server.
Common Mistakes
- Plain HTTPRoute for gRPC —
GetServerKey404s. Use GRPCRoute matched by RPC service name (management.ManagementService, signalexchange.SignalExchange) or an h2c backend. - Missing UDP 3478 — STUN can't be HTTP-proxied. P2P NAT traversal breaks → all peers relay.
existingSecretPasswordKeymismatch — CNPG initdb secret uses keypassword; chart default expectsdatabase-password. Set the override or the server can't reach the DB.- Forgetting
postgresql.enabled: false— bundled subchart conflicts withdatabase.mode: external(chart validate). - sqlite with replicaCount > 1 — SQLite store is single-instance; scale only on PostgreSQL.
- IdP connector type immutability — after creation the NetBird API rejects type/schema changes on the identity provider. Delete+recreate (import afterwards in Terraform) rather than edit.
- Dashboard external OIDC partial override — mixing embedded defaults with an external IdP breaks login. Override all
AUTH_*values. disableGeoliteUpdate: false+ air-gapped — server pod downloads GeoLite DBs at boot; health endpoint can be slow to open. Leave disabled unless the cluster allows egress.- STUN deferred on Cilium — Cilium UDP listener support for the STUN Service may be unproven; verify UDP Service exposure before relying on P2P.
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.

