Skip to content

Commit acaffb4

Browse files
committed
docs(gateway): name child tenants in the listener attach set
The Layer 1 description listed two writers of the gateway label and omitted the largest: the tenant chart stamps it on every inheriting child namespace, so the attach set is the whole tenant subtree rather than the tenant plus admin-listed namespaces. The closing note that writing the label needs patch on Namespace reinforced the narrower reading, since a child receives it at creation without patching. This is the paragraph a reader consults before pointing a passthrough listener at a database, so it should state the full set. Assisted-By: Claude <[email protected]> Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 219c33d commit acaffb4

1 file changed

Lines changed: 2 additions & 2 deletions

File tree

‎packages/extra/gateway/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ There are two distinct passthrough forms, and they do not replace each other. Th
7171

7272
Each entry names a listener, a port, and an SNI hostname. The port must be free (80 and 443 belong to the Gateway's own listeners) and distinct from every other entry; the hostname must fall within the tenant apex. Those rules are enforced at admission by CEL on the CRD, so a bad entry is refused on write rather than stalling the tenant's reconcile.
7373

74-
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 namespaces carrying `namespace.cozystack.io/gateway` for this tenant may attach, and only `TLSRoute`.
74+
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.
7575

7676
This field is set on the `TenantGateway` resource directly; the chart exposes no corresponding value yet.
7777

@@ -95,7 +95,7 @@ The protections below split into three groups by who they defend against:
9595
- **Defense-in-depth** — Layers 1, 2, 5, 6, 7, 8. These do not protect against tenant-user input (tenants don't hold the relevant RBAC). They guard against bugs in cozystack-controller / Flux, supply-chain compromise of an app chart that emits Gateway API or Ingress resources, and confused-deputy mistakes by a cluster admin. Fail-closed via `failurePolicy: Fail` + `validationActions: [Deny]`. Layers 1-7 cover the opt-in Gateway API dataplane; Layer 8 covers the legacy Ingress dataplane, which is the default (Gateway API is off by default).
9696
- **Admin-against-themselves** — Layer 3 (`cozystack-gateway-attached-namespaces-policy`). Rejects a `kubectl edit packages.cozystack.io` that would slip a `tenant-*` entry into the platform Package's `gateway.attachedNamespaces`. Layer 6 catches the same misconfiguration at helm render time.
9797

98-
1. **Namespace whitelist on listeners.** Every listener carries an `allowedRoutes.namespaces.from: Selector`, but the two listener classes select on different labels. The plain-HTTP listener (port 80) pins an explicit `kubernetes.io/metadata.name` allow-list (written by kube-apiserver, unspoofable) covering only the tenant namespace itself (where the controller-owned http→https redirect HTTPRoute lives) and `cozy-cert-manager` (HTTP-01 ACME challenge HTTPRoutes) — so app HTTPRoutes attaching by hostname cannot bind to port 80 and serve plaintext. Every other listener — HTTPS-terminate, the port-443 TLS-passthrough listeners, and the native-port layer-4 listeners from `tlsPassthroughListeners` — selects on `namespace.cozystack.io/gateway`, the label the controller stamps on the publishing tenant's namespace and on each `gateway.attachedNamespaces` entry from the platform chart (default includes the `cozy-*` namespaces for platform services and `default` for the Kubernetes API TLSRoute). A namespace without that label literally cannot attach any `HTTPRoute` or `TLSRoute` to those listeners; writing it requires `patch` on `Namespace`, which tenants do not hold. HTTPS listeners additionally restrict `allowedRoutes.kinds` to `HTTPRoute` (and TLS-passthrough listeners to `TLSRoute`), preventing GRPCRoute / TCPRoute / UDPRoute from attaching outside the route-hostname VAP's coverage.
98+
1. **Namespace whitelist on listeners.** Every listener carries an `allowedRoutes.namespaces.from: Selector`, but the two listener classes select on different labels. The plain-HTTP listener (port 80) pins an explicit `kubernetes.io/metadata.name` allow-list (written by kube-apiserver, unspoofable) covering only the tenant namespace itself (where the controller-owned http→https redirect HTTPRoute lives) and `cozy-cert-manager` (HTTP-01 ACME challenge HTTPRoutes) — so app HTTPRoutes attaching by hostname cannot bind to port 80 and serve plaintext. Every other listener — HTTPS-terminate, the port-443 TLS-passthrough listeners, and the native-port layer-4 listeners from `tlsPassthroughListeners` — selects on `namespace.cozystack.io/gateway`. That label has three writers, and the third is the one to keep in mind when sizing the blast radius: the controller stamps it on the publishing tenant's namespace and on each `gateway.attachedNamespaces` entry from the platform chart (default includes the `cozy-*` namespaces for platform services and `default` for the Kubernetes API TLSRoute), and the tenant chart stamps it on **every inheriting child tenant namespace**, pointing at the nearest ancestor that owns a Gateway. So the attach set is not just the tenant plus admin-listed namespaces — it is the whole inheriting tenant subtree. A namespace without the label cannot attach any `HTTPRoute` or `TLSRoute` to those listeners, but a child tenant receives it automatically at creation rather than by patching anything. HTTPS listeners additionally restrict `allowedRoutes.kinds` to `HTTPRoute` (and TLS-passthrough listeners to `TLSRoute`), preventing GRPCRoute / TCPRoute / UDPRoute from attaching outside the route-hostname VAP's coverage.
9999
2. **`cozystack-gateway-hostname-policy`** — `ValidatingAdmissionPolicy` on `gateway.networking.k8s.io/v1 Gateway` CREATE/UPDATE. Reads `namespaceObject.metadata.labels["namespace.cozystack.io/host"]` and rejects any listener hostname that is not equal to that value or a subdomain of it. `matchConditions` gate the VAP to cozystack-managed namespaces only — Gateways in unrelated namespaces (e.g. `kube-system`) are not touched.
100100
3. **`cozystack-gateway-attached-namespaces-policy`** — VAP on `cozystack.io/v1alpha1 Package` CREATE/UPDATE. Rejects any `tenant-*` entry in `spec.components.platform.values.gateway.attachedNamespaces`. Catches direct `kubectl edit packages.cozystack.io` that would bypass the helm render-time guard in layer 6.
101101
4. **`cozystack-tenant-host-policy`** — VAP on `apps.cozystack.io/v1alpha1 Tenant` CREATE/UPDATE. Rejects setting or changing `spec.host` unless the caller's groups contain `system:masters`, `system:serviceaccounts:cozy-system`, `system:serviceaccounts:cozy-cert-manager`, `system:serviceaccounts:cozy-fluxcd` or `system:serviceaccounts:kube-system`. Closes the path where a tenant user sets `spec.host=dashboard.example.org` on their own tenant to have the tenant chart write a hijacked label into the namespace.

0 commit comments

Comments
 (0)