History

e3mrah 9a2f423ab7 fix: mark bp-dmz-vcluster + bp-netbird default-off for smoke-render gate (#1286 ) * fix(bp-keycloak): truncate catalyst-api-server description <255 chars (Postgres limit) Keycloak DB column CLIENT.DESCRIPTION = varchar(255). Previous value was 458 chars, causing realm-config-cli post-install hook to fail with PSQLException value too long. Caught on omantel provision #6 iter-13 chart roll — keycloak-config-cli Job CrashLoop, bp-keycloak HR False, upstream HRs blocked. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(bp-keycloak): truncate catalyst-api-server desc <255 chars (Postgres limit) Keycloak DB column CLIENT.DESCRIPTION = varchar(255). Previous value was 458 chars (since Fix #23 / commit `febd5fef`), causing realm-config-cli post-install hook to fail with PSQLException 'value too long for type character varying(255)' on every fresh Sovereign provision. Caught on omantel provision #6 — keycloak-config-cli Job CrashLoop, bp-keycloak HR False, all upstream HRs blocked from converging. Backport to 1.4.x (1.5.0 had a separate breaking realm-rename change reverted via PR #1282). Bootstrap-kit pin updated to 1.4.2. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(bp-dmz-vcluster, bp-netbird): mark default-off so smoke-render gate accepts 1-line manifests Both blueprints are scratch charts (no upstream subchart) gated default-off. helm-template smoke renders <2 lines, hitting the platform-wide 'Empty render' gate added in #181. Adding the documented annotation 'catalyst.openova.io/smoke-render-mode: "default-off"' for both — same mechanism bp-qa-app uses (catalyst.openova.io/no-upstream). Caught on omantel provision #6 — bp-dmz-vcluster + bp-netbird HelmRelease permanently failing chart pull because Blueprint Release CI never published their charts (smoke gate failure). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: alierenbaysal <alierenbaysal@openova.io> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>		2026-05-10 15:57:18 +04:00
..
templates	feat(epic-5): NetBird mesh + ClusterMesh activator + DMZ vCluster scaffolds (#1100 ) (#1171 )	2026-05-09 12:14:56 +04:00
tests	feat(epic-5): NetBird mesh + ClusterMesh activator + DMZ vCluster scaffolds (#1100 ) (#1171 )	2026-05-09 12:14:56 +04:00
Chart.yaml	fix: mark bp-dmz-vcluster + bp-netbird default-off for smoke-render gate (#1286 )	2026-05-10 15:57:18 +04:00
README.md	feat(epic-5): NetBird mesh + ClusterMesh activator + DMZ vCluster scaffolds (#1100 ) (#1171 )	2026-05-09 12:14:56 +04:00
values.yaml	fix(infra): wire NetBird, DMZ vCluster, Hubble UI, BGP, Gitea client — qa-loop iter-12 Fix #53B+C (#1275 )	2026-05-10 10:50:36 +04:00

README.md

bp-netbird

Catalyst-authored Blueprint chart for NetBird — a WireGuard-based zero-trust mesh + remote-access overlay. Operators, engineers, and customer admins enroll devices via Keycloak SSO and reach Sovereign-internal services from any laptop or mobile device.

What ships

Resource	Purpose
`Deployment/<rel>-management` + `PersistentVolumeClaim`	NetBird management API + UI; SQLite-backed state on hcloud-volumes PVC
`Deployment/<rel>-signal`	WebRTC signaling for WireGuard handshake brokering
`Deployment/<rel>-coturn`	TURN/STUN server for NAT traversal fallback
`Service/<rel>-{management,signal,coturn}`	ClusterIP fronts; coturn flips to LoadBalancer per Sovereign overlay
`HTTPRoute/<rel>`	Cilium Gateway exposure (mgmt UI + signal gRPC)
`NetworkPolicy/<rel>-management-egress`	Default-deny + selective egress to Keycloak / signal / coturn / NATS
`ConfigMap/bp-netbird-realm-patch`	`catalyst.openova.io/keycloak-config: realm-patch` — adds NetBird OIDC client + realm role
`SealedSecret/<oidc>` + `SealedSecret/<coturn-auth>`	Placeholders for OIDC client secret + coturn static-auth secret

Default-OFF gate

netbird.enabled: false in values.yaml. helm template renders zero resources by default. Operator opts in via per-Sovereign overlay at clusters/<sovereign>/bootstrap-kit/<NN>-netbird.yaml once the dependencies (bp-keycloak + bp-cilium + bp-sealed-secrets) are ready.

SHA-pinned images

All three container images are upstream:

netbirdio/management
netbirdio/signal
coturn/coturn

Per docs/INVIOLABLE-PRINCIPLES.md #4a, image.tag is empty in values.yaml and the helm-template render fails-fast when a Sovereign overlay leaves them empty (see _helpers.tpl::bp-netbird.imageRef). CI populates the SHA tags via yq eval -i .image.tag = "<sha>" when promoting a build into clusters/<sovereign>/.

Keycloak OIDC integration

The bp-netbird-realm-patch ConfigMap is consumed by bp-keycloak's post-deploy keycloak-config-cli Job (sorted by name; the bp- prefix groups Catalyst-owned patches together). It adds:

the netbird OIDC client (confidential, with audience-netbird and groups protocol mappers)
the netbird-user and netbird-admin realm roles
default netbird-users and netbird-admins groups bound to the matching realm roles

This mirrors the Guacamole pattern from slice K+P+X1+G #1164. Two-step bootstrap: chart applies → operator extracts the generated client-secret from KC admin API → kubeseal → re-apply. The first user to land an OIDC handshake against the NetBird management API becomes the account owner (per oidc.adminUserIdClaim: sub).

Setup-key flow

NetBird's per-org join tokens (setup-keys) flow through the catalyst-api → Keycloak OIDC chain for seamless onboarding. New operators authenticate to NetBird via Keycloak SSO, request a setup-key from the management UI (or via the catalyst-api REST proxy under /api/v1/sovereigns/{id}/netbird/setup-keys), then enroll their device with netbird up --setup-key <key> --management-url https://netbird.<sovereign-fqdn>.

NAT-traversal

The coturn Deployment defaults to ClusterIP. Per-Sovereign overlays should flip netbird.coturn.service.type: LoadBalancer once the cloud LB is available so peers behind symmetric NATs can reach the TURN server from the public internet. The static-auth secret is shared with the NetBird management Deployment via netbird-coturn-auth SealedSecret.

Tests

bash tests/render.sh exercises three contracts:

Default-OFF: zero K8s resources rendered (CC3 default-OFF gate).
Fail-fast on empty image tag: render aborts with the exact bp-netbird: ... image tag is empty message when enabled: true without a SHA stamp.
Full-ON canonical bundle: every required kind appears at least once and the realm-config wires the OIDC client.

helm lint clean.