Netbird

Netbird is the WireGuard-based mesh VPN that gates access to every *.internal.stefanzhelev.com service in the cluster. Each connected device joins an overlay network and can reach internal services as if they were on the same LAN; nothing is exposed on the public internet beyond the Netbird signal/management endpoints themselves.

Deployment

Field	Value
Flux path	flux-clusters/stefanzhelev/apps/netbird
Base path	flux-apps/netbird
Namespace	netbird
Sync wave	6
Depends on	cloudnative-pg-config, external-secrets-config, authentik-app-netbird

What it deploys

• netbird-config — HelmRelease for the upstream netbird chart, plus an IngressRoute for the gRPC management endpoint
• netbird-database — Terraform CR that provisions the Netbird PostgreSQL database on the shared CNPG cluster
• netbird-external-secrets — ExternalSecret rendering OIDC + DB credentials into the namespace
• netbird-vault-secrets — Terraform CR generating the management secret at secret/netbird
• netbird-internal-dns — Terraform CR maintaining the Cloudflare DNS A record for vpn.stefanzhelev.com against the Hetzner LB
• netbird-pat-creation — one-shot Job that mints a service-user PAT in Authentik for the IDP manager
• netbird-route-config — Terraform CR that registers the cluster network as a Netbird routing peer so VPN traffic can reach in-cluster Services

Endpoint

Hostname	vpn.stefanzhelev.com
Public on	Hetzner LB (signal + management endpoints)
TLS	cert-manager, letsencrypt-prod (HTTP-01)
SSO	OIDC via Authentik — sign-in inherits Authentik group membership

How it works

Developer machine (Netbird agent)
  ↔ WireGuard tunnel
Cluster routing peer (in-cluster Netbird agent)
  ↔ Internal Services (Vault UI, Grafana, Forgejo, Harbor, ClickHouse, …)

The cluster runs its own Netbird agent (the route-config peer) that exposes the cluster’s internal Service CIDR to the mesh. Any laptop logged in via netbird up can resolve and reach *.internal.stefanzhelev.com over the encrypted overlay; without the VPN, those hostnames don’t resolve and the LB doesn’t accept the traffic.

Integrations

• Authentik: OIDC provider; group membership controls which peers a user is allowed to see
• CloudNative-PG: Netbird’s PostgreSQL database lives on the shared cluster
• Vault + Tofu Controller: OIDC and DB credentials originate in Vault and are written by Terraform CRs
• Cloudflare: the vpn.stefanzhelev.com A record is reconciled by netbird-internal-dns

Client setup

# Install the Netbird client
brew install netbirdio/tap/netbird

# Connect (opens an Authentik browser flow on first run)
netbird up

# Check connection status
netbird status

# List connected peers + their assigned overlay IPs
netbird status --detail

# Disconnect
netbird down

After netbird up, services like vault.internal.stefanzhelev.com, grafana.internal.stefanzhelev.com, harbor.internal.stefanzhelev.com, and clickhouse.internal.stefanzhelev.com resolve and route over the tunnel.