Skip to content

Commit 3958dd1

Browse files
committed
docs(gateway): state the passthrough limitations and upgrade effects
Three things an operator could previously only discover by hitting them: one listener per port, so two instances of one engine cannot share its native port by SNI; the field is chart-rendered, so a kubectl edit adding listeners is drift Flux reverts; and the schema tightening on apex and tlsPassthroughServices applies on the next write of objects that already exist, so a hand-edited upper-case apex fails its release on upgrade rather than at install. Both restrictions trace to the pinned Cilium selecting a passthrough backend by SNI alone, so both are noted as revisitable when the pin moves. Assisted-By: Claude <[email protected]> Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent e806319 commit 3958dd1

1 file changed

Lines changed: 5 additions & 1 deletion

File tree

‎packages/extra/gateway/README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,11 @@ No two passthrough listeners may match the same SNI, counting the port-443 liste
7575

7676
The listener is all this field creates. Nothing is routed until a `TLSRoute` attaches to it by `sectionName: tls-<name>` and names a backend Service, and because a passthrough listener never terminates TLS, the backend — not the Gateway — must hold the certificate for the listener's hostname. Route attachment is bounded the same way as every other listener: only `TLSRoute`, and only from namespaces carrying `namespace.cozystack.io/gateway` for this tenant — which, as in the security model above, means the tenant's own namespace, the admin-listed attached namespaces, and every child tenant inheriting this Gateway. Point a passthrough listener at a database with that full set in mind, not just the tenant's own namespace.
7777

78-
This field is set on the `TenantGateway` resource directly; the chart exposes no corresponding value yet.
78+
Two current limitations are worth knowing before designing around this. Each entry must occupy its own port, so two instances of the same engine cannot both sit on the engine's native port distinguished only by SNI — that restriction is a deliberate narrowing for this phase rather than a Gateway API rule, and lifting it is a validation change with no API impact. And the SNI-overlap rule above exists because the pinned Cilium (1.19.5) selects a passthrough backend by SNI alone; the fix landed upstream in 1.19.6, so both restrictions should be revisited when the Cilium pin moves.
79+
80+
This field is set on the `TenantGateway` resource directly; the chart exposes no corresponding value yet. That matters operationally: the `TenantGateway` object is rendered and owned by this chart, so a `kubectl edit` adding `tlsPassthroughListeners` is drift that Flux reverts on its next reconcile of the release. Until the chart exposes a value, treat the field as reachable only for experimentation on a suspended release.
81+
82+
Two schema constraints tightened alongside this field apply to objects that already exist, since they are enforced on the next write rather than retroactively: `apex` must now be a lowercase hostname of at most 253 characters, and `tlsPassthroughServices` entries must be unique DNS-1123 labels. The shipped defaults and the chart's own `fail` on an empty host already conform, so an upgrade is a no-op in practice — but a cluster carrying a hand-edited upper-case apex will see its gateway release fail on the next apply rather than silently render a Gateway that Gateway API would reject anyway.
7983

8084
## Parameters
8185

0 commit comments

Comments
 (0)