Repository navigation
Commit b4d413c
committed
docs(gateway-api): align with TenantGateway CRD + 7-layer security model
Major rewrite of the Gateway API page to reflect the architecture
shipped in cozystack/cozystack#2470:
- Add TenantGateway CRD + cozystack-controller reconciliation flow.
The chart no longer renders Gateway / Issuer / Certificate
directly — those come from the controller reconciling a per-tenant
TenantGateway CR. Adds a reconciliation-flow mermaid alongside the
traffic-path one.
- Add HTTP-01 (default) vs DNS-01 (opt-in) cert-mode section. HTTP-01
is the new default with per-listener Certificates and listeners
added dynamically per HTTPRoute hostname. DNS-01 is the wildcard
opt-in with parametrized provider — full provider matrix
(cloudflare, route53, digitalocean, rfc2136). Document that the
same provider config drives both per-tenant Issuers and the
cluster-wide ClusterIssuers used by the legacy ingress flow.
- Renumber the security model from 5 layers to 7 layers and add the
missing layers:
- Layer 3 (cozystack-gateway-attached-namespaces-policy) was
previously listed as Layer 5; recategorised to match the
in-repo README ordering.
- Layer 7 (cozystack-route-hostname-policy) — the HTTPRoute /
TLSRoute hostname VAP scoped to tenant-* namespaces — was
missing entirely. This is the layer that closes the cross-apex
hostname surface a tenant user with HTTPRoute RBAC could
otherwise exploit. Document its fail-closed behavior on missing
namespace.cozystack.io/host label.
- Document the narrow port-80 listener allowedRoutes (only the
tenant namespace + cozy-cert-manager) — the Layer 1 hardening
that prevents app HTTPRoutes attaching by hostname from binding
to port 80 and serving plaintext.
- Document the HTTPS listener allowedRoutes.kinds=[HTTPRoute]
restriction (TLSRoute for passthrough listeners) — prevents
GRPCRoute / TCPRoute / UDPRoute from bypassing the route-hostname
VAP.
- Add HostnameConflict resolution section: cozy-* > tenant-*
priority, lexicographic tiebreak, status condition under the
controller's name in Status.Parents.
- Add Foreign-takeover guards section listing all five reconcile
paths (Gateway, redirect HTTPRoute, Issuer, wildcard Certificate,
per-listener Certificate) that refuse to silently take over
pre-existing objects without an OwnerReference back to the
TenantGateway.
- Add cilium-lb-pool empty-IPs exception note: in loadBalancer mode
with empty publishing.externalIPs the chart skips the per-tenant
pool render rather than failing — this is the legitimate operator
pattern for clusters running BGP / L2-announce pools managed
outside the chart.
- Refresh listener-naming docs: per-app listeners use a sha256
suffix (`https-<first-label>-<8-hex>`) so two hostnames sharing
the first label (harbor.foo.example.com vs harbor.alice.example.com)
produce distinct names.
- Refresh troubleshooting: TenantGateway Ready=False with
ReconcileError points at foreign-takeover refusals; route VAP
rejection messages.
Plus platform-package.md: extend publishing.certificates table with
the dns01.* provider matrix so operators can find the wiring keys
in one place.
Signed-off-by: Aleksei Sviridkin <[email protected]>1 parent 6888f84 commit b4d413c
2 files changed
Lines changed: 209 additions & 55 deletions
0 commit comments