[marcschaeferger]

Ready for review. ghcr.io/fosrl/pangolin-kube-controller:0.1.0-alpha.2 is still unpublished (ghcr.io returns 404), so the registry gate now tolerates that one image, and only on dev - a pull request into dev or a push to dev. main, and every other default image, stay fatal. The exception carries a TODO and comes out as soon as the controller release lands.

Stacked on #27, which is stacked on #26. The six commits belonging to this PR are 59f8584..53b4888.

Addresses #20 in two parts: one fix, and one explicitly transitional workaround. The issue should stay open — the portable multi-node data path is not solved here.

The part that is genuinely fixed

Pangolin renders Badger's apiBaseUrl from server.badger_override || http://<server.internal_hostname>:<server.internal_port>/api/v1. It is not hardcoded, as the issue assumed — the bug was this chart's default, which was the bare Service name pangolin.

Badger runs inside the Traefik Pod and resolves that name from there. deployment.traefikNamespace exists precisely so Traefik can live elsewhere, and from another namespace a bare Service name does not resolve at all: Badger answers 404 page not found for every request while the Traefik dashboard still reports the router as Success. That matches the second symptom in the issue, and the reporter's ExternalName workaround is no longer needed.

internal_hostname now defaults to the derived in-cluster FQDN. Because the same value also drives the Pangolin UI URL and the AI gateway URL in the same generated Traefik config, this fixes all three at once. An explicit value still wins, and global.clusterDomain covers clusters that do not use cluster.local.

Gerbil's --reachableAt/--remoteConfig and the controller's CONFIG_ENDPOINT are qualified too. They resolve today only via the cluster search path, which stops applying the moment Gerbil runs with hostNetwork.

The part that is a workaround

gerbil.hostGateway.enabled=true (opt-in, never implicit) runs Gerbil with hostNetwork, so wg0 and its connected route are created in the node network namespace and Pods on that node reach the tunnel through the node routing table. Traefik must then be co-located: the chart-managed one is pinned by a required podAffinity (traefik.colocateWithGerbil), and for an external Traefik helm get notes prints the exact snippet with the real release name and namespace filled in.

I want to be blunt about what this does not solve, because it is easy to read a green install as "#20 is done":

Limitation	Consequence
Only the Gerbil node holds the route	Tunnel backends stay unreachable from Pods on every other node.
Affinity is IgnoredDuringExecution	A Gerbil reschedule leaves running Traefik Pods returning 502 until restarted.
Depends on CNI egress masquerading	Default for Flannel, Calico natOutgoing, Cilium. Without that SNAT the remote peer sees the Traefik Pod IP as source and drops the reply. The chart can neither detect nor fix this.
Gerbil binds node ports	One per node, replicaCount pinned to 1 — no Gerbil HA.
Needs privileged PSA	baseline forbids hostNetwork. NET_ADMIN is still required.
Not available in single mode	Gerbil shares a Pod there, so hostNetwork would bind every component's ports on the node.

PANGOLIN-071…075 reject each combination that cannot work — single mode, Gerbil disabled, more than one replica, a chart-created namespace that forbids hostNetwork, and the Traefik subchart, where Helm cannot inject affinity at render time — rather than letting them surface as a Pending Pod or a silent 502.

Why not the alternatives

• Gerbil 1.5.0's /router/ endpoint is header-driven (p-dest-header) and unauthenticated, and Pangolin's Traefik config schema (server/routers/traefik/configSchema.ts) models only plugin middlewares — it cannot emit the addPrefix+headers pair needed to drive it. Wiring it up requires controller changes, not chart changes.
• A Traefik sidecar in the Gerbil Pod would be the true network_mode: service:gerbil equivalent, but it only helps when the chart manages Traefik, and deployment.traefikNamespace is an explicitly supported topology.

NetworkPolicy

Rebased onto the source-scoped AI gateway rule from #27; host gateway mode does not change it, because the gateway is reached by Traefik rather than by Gerbil.

A hostNetwork Pod is not matched by a podSelector on any mainstream CNI — its traffic sources from the node IP. In host gateway mode the Gerbil → Pangolin internal-API rule therefore switches to node address blocks (networkPolicy.gerbil.hostGateway.nodeCIDRs, no default: PANGOLIN-075 fails the render until you set your node addresses). Without that, the chart's own default policy would blackhole Gerbil's --remoteConfig polling — a failure the existing WIP approaches to this issue missed.

Testing, and its ceiling

scripts/e2e/assert-tunnel-backends.sh fails when the controller publishes an EndpointSlice address inside the tunnel subnet while no data path is configured — the precise condition behind #20.

It is self-tested against committed fixtures on every PR, so it is proven to reject an unroutable address rather than passing vacuously. That is the part I could verify without a cluster, and I did: all four fixture cases behave correctly.

The kind job is label-gated and checks what a cluster can confirm without a live Pangolin/Newt pair — that Gerbil really lands in the node network namespace, that wg0 and its route exist there, and that Traefik shares the node. Both pod lookups fail loudly on an empty selector match, because the chart labels its own Traefik traefik-standalone and a wrong selector would have made the comparison prove nothing.

It does not drive a request through the tunnel. That needs a real Newt credential and a registered site, so the 502 → 200 assertion is out of reach here and the workflow header says so. Do not read a green run as proof the tunnel works.

Unit coverage: 18 cases for host gateway mode, including a cross-template contract test asserting the affinity's labelSelector against the same literal map as the Gerbil workload's own spec.selector.matchLabels, so drift in the selector labels breaks exactly one of the two.

Validation

• helm unittest --strict charts/pangolin: 34 suites, 524 tests.
• scripts/test.sh --with-kubeconform: lint, unittest, render, yamllint and kubeconform against Kubernetes 1.30–1.35 all pass.
• All 14 Pangolin examples render, including the new values-host-gateway.yaml.
• Every default image tag resolved against its registry: Pangolin 1.22.2, Gerbil 1.5.1, Newt 1.16.0 and curlimages/curl:8.8.0 all return 200; only the controller 0.1.0-alpha.2 returns 404, which is the intended blocker.
• pre-commit run --all-files clean.

Not run: kind (no container runtime available locally). The E2E is authored for CI and will first execute here.

Refs #20

---

Update - merged with dev, follow-ups included

dev was merged into this branch and six conflicts resolved, so nothing has to be pushed straight to dev after this lands.

• networkpolicy.yaml - dev's chart-managed-Traefik rule is a sibling of the $renderGerbil block, not nested inside it; nesting it would have scoped the rule to whether Gerbil renders and left if $renderGerbil unclosed. The RFC1918/CGNAT fallback for nodeCIDRs is removed: PANGOLIN-075 already fails hard on an empty list, so it was unreachable code that would have become a cluster-wide allow-list to Pangolin's internal API if the guard were ever bypassed.
• _helpers.tpl - pangolin.traefik.configEndpoint built a bare Service name, which is exactly the failure 61b2fc7 exists to fix; it now uses pangolin.pangolin.serviceFQDN. standalone_traefik_wiring_test.yaml asserted the old form and was updated with it.
• charts/newt/templates/deployment.yaml - takes dev's side, verified to be a strict superset here: all three native/preferEndpoint guards plus the updown.enabled guard, the metrics listen-port helper and the health emptyDir.
• README.md.gotmpl - two factual corrections: nodeCIDRs has no default, and PANGOLIN-075 is that check, not a Traefik-subchart affinity limitation (no such guard exists).
• CHANGELOG.md / VERSION_MATRIX.md - both bullet sets kept; controller tag stays 0.1.0-alpha.2.

Verified locally with the pinned toolchain (helm 3.20.2, unittest 1.1.2 - the versions CI pins)

• helm unittest --strict charts/pangolin - 35 suites, 536 tests, all pass
• helm unittest --strict charts/newt - 21 suites, 156 tests, all pass
• helm lint both charts clean; values.schema.json regenerates byte-identical; README regenerated with helm-docs
• helm template renders for the default values and for gerbil.hostGateway.enabled=true; PANGOLIN-075 confirmed to fire on an empty nodeCIDRs
• PANGOLIN-071...075 each defined exactly once; no CRLF introduced

Not verifiable on this machine (no Docker): every kind E2E leg and the live registry probe.