feat: an app UI instance per tenant

[TheMeinerLP]

Every tenant gets its own deployed instance of the tenant application, served at
https://<host>/t/<tenant>/. One image, N deployments, one environment variable.

This is the second of four subsystems the larger goal decomposes into. The first —
per-tenant options with lock and override — shipped in 0.8.0. Teams and users through Entra,
and impersonation, are still out of scope here and get their own specs.

Design: docs/superpowers/specs/2026-08-16-per-tenant-app-instance-design.md
Plan: docs/superpowers/plans/2026-08-16-per-tenant-app-instance.md

What the operator creates

When tenantUi.host is set — and it is empty by default, which switches the whole feature off —
TenantReconciler adds three objects to each tenant's own namespace:

Resource	Notes
Deployment	one replica, the apus/ui image, NUXT_APP_BASE_URL=/t/<name>/
Service	ClusterIP, http → 8080
Ingress	<host> + path /t/<name>, pathType: Prefix

The Ingress has to be per-tenant and in the tenant's namespace: an Ingress may only
reference a Service in its own namespace. A single operator-owned Ingress listing every tenant
was never an option.

Nothing in apps/app changed. buildOidcRedirectUris(origin, baseURL) already derives the
callback from the runtime base path, and its tests already covered a nested prefix.

Four findings that shaped this, two of which contradicted the first draft

One image serves any prefix. NUXT_APP_BASE_URL=/t/acme/ → the built Nitro server serves its
shell and deep links under that prefix, emits assets at /t/acme/_nuxt/…, and 404s on the bare
root. Verified against the actual image before any of this was designed.

Entra permits a wildcard redirect URI here — and it would break the login. Microsoft's docs:
"when a configured wildcard URI matches a redirect URI, query strings and fragments in the
redirect URI are stripped". The authorization code lives in that query string. So two explicit
URIs per tenant, and the 256-URI registration limit is the real ceiling: ~128 tenants.

An earlier attempt to settle this empirically appeared to succeed — and so did the control case
against an unrelated host, because Entra renders its sign-in page before validating the redirect
URI at all. That test proved nothing; the documentation is what settles it.

Path ordering is safe, but not for the reason the platform chart's comment gives. The ingress
class here is cloudflare-tunnel, not nginx. That controller flattens every Ingress in the
cluster into one rule list and sorts it globally by path length descending
(sortIngressRules in pkg/cloudflare-controller/tunnel-client.go), so /t/acme lands ahead of
/ no matter which object declared it. Read from the controller's source, since no host in this
cluster is currently served by two Ingress objects.

A pod in a tenant namespace must declare resource requests or it is never created. The
namespace's ResourceQuota constrains requests.cpu/requests.memory and the LimitRange
beside it is empty (spec={"limits":null} on the live cluster). A Deployment without requests is
accepted and then produces no pod — a healthy-looking Deployment stuck at zero replicas.

Proven with kubectl apply --dry-run=server against a real tenant namespace, which runs the
admission plugins and creates nothing:

pods "..." is forbidden: failed quota: apus-tenant:
  must specify requests.cpu for: ui; requests.memory for: ui

A defect that verification caught

The same dry-run warned that the probe pod violated PodSecurity "restricted". The platform chart
hardens its own ui Deployment — runAsNonRoot, uid 65532, RuntimeDefault seccomp, no
privilege escalation, read-only root, all capabilities dropped — and the first version of this
builder applied none of it to the same image.

Only a warning on this cluster, so nothing would have broken. It would simply have been the same
software running less restricted because a controller created it rather than Helm, and it would
have become a hard rejection the moment tenant namespaces were set to enforce. Fixed, and the
hardened shape now passes the same dry-run with no warning at all.

The manual step, said out loud in three places

Each instance needs two redirect URIs registered before anyone can sign in:

https://<host>/t/<tenant>/auth/callback
https://<host>/t/<tenant>/auth/silent-renew

The operator cannot add them — that needs Microsoft Graph application permissions on the app
registration. And a missing registration does not fail at deploy time: it fails at someone's first
sign-in, at the identity provider (AADSTS50011), with nothing whatsoever in this cluster's logs.

So it is stated where someone will actually meet it: on Tenant.status.redirectUris, in the
chart's NOTES.txt (only when a host is configured), and on the console's tenant page with a copy
action — in front of the person who just created the tenant.

Verification

:operator:test	passes — 12 builder cases, 5 new reconciler cases, 5 config cases
:api:test	passes, incl. the two redirectUris cases
spotlessCheck	clean
pnpm lint / typecheck	clean
pnpm test	172 (143 core + 18 app + 11 console)
Chart	rendered both ways with helm template; values.schema.json rejects an apiBaseUrl ending in /api — the exact mistake that cost a debugging session once
Quota + PodSecurity	--dry-run=server against a real tenant namespace, in all three shapes

One gap, stated rather than hidden: the new k3s integration test — which waits for a Pod
rather than a Deployment, since only a cluster with quota admission can fail that — compiles but
has not been executed. There is no Docker on this machine, and *IntegrationTest classes run in
neither check nor CI (pre-existing for the two that were already there). The claim it would
prove was instead verified directly against the live cluster, as above.

🤖 Generated with Claude Code

https://claude.ai/code/session_019Bff5mpWkUnZA77jys8DiR

[github-actions]

Test results

603 tests   603 ✅  50s ⏱️
 86 suites    0 💤
 86 files      0 ❌

Results for commit 05bb0fb.