PSA/ee/docs/extension-system/knative-app-domains.md

# Per-Extension App Domains (Knative) — Ops & RBAC

This document captures the operational pieces needed to support per-install application domains using Knative DomainMapping, provisioned by the Temporal worker.

Scope: We track changes here; the actual Helm/Kubernetes wiring is handled in the infra repo.

## Environment Variables

- Temporal worker
  - `EXT_DOMAIN_ROOT`: Root wildcard domain for extension apps (e.g., `ext.example.com`).
  - `RUNNER_NAMESPACE`: Kubernetes namespace where the Runner KService lives (defaults to `default`).
  - `RUNNER_KSERVICE`: Name of the Knative Service for the Runner (defaults to `runner`).
  - Standard Temporal env: `TEMPORAL_ADDRESS`, `TEMPORAL_NAMESPACE`, `TEMPORAL_TASK_QUEUE`.

- Runner KService
  - `BUNDLE_STORE_BASE`: Base URL for bundle objects (e.g., `http://minio:9000/alga-ext/`).
  - `REGISTRY_BASE_URL`: Base URL of the EE server (used for host lookup + validation).
  - `EXT_CACHE_MAX_BYTES`: Optional cache/file size limit for static assets.
  - `EXT_STATIC_STRICT_VALIDATION`: `true|false` to enforce strict tenant/contentHash validation.
  - `EXT_EGRESS_ALLOWLIST`: Optional comma-separated host allowlist for guest HTTP egress.
  - S3/MinIO creds if needed by origin access (typically not needed if using HTTP gateway with public read): `S3_ENDPOINT`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_BUCKET`.

## DNS / Ingress

- Configure wildcard DNS: `*.${EXT_DOMAIN_ROOT}` to Knative Ingress.
- If not using wildcard, automate DNS records for each provisioned domain.

## RBAC (Temporal Worker ServiceAccount)

Grant the Temporal worker permission to manage DomainMappings in the target namespace:

```
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: temporal-worker-knative
  namespace: ${RUNNER_NAMESPACE}
rules:
  - apiGroups: ["serving.knative.dev"]
    resources: ["domainmappings"]
    verbs: ["get", "list", "watch", "create", "patch", "update"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: temporal-worker-knative
  namespace: ${RUNNER_NAMESPACE}
subjects:
  - kind: ServiceAccount
    name: temporal-worker
    namespace: ${TEMPORAL_WORKER_NAMESPACE}
roleRef:
  kind: Role
  apiGroup: rbac.authorization.k8s.io
  name: temporal-worker-knative
```

Ensure the Temporal worker Deployment/Pod uses `serviceAccountName: temporal-worker` and set environment variables `RUNNER_NAMESPACE`, `RUNNER_KSERVICE`, `EXT_DOMAIN_ROOT`.

## Temporal Activity Behavior

- `computeDomain(tenantId, extensionId, EXT_DOMAIN_ROOT)` returns `${t8}--${e8}.${EXT_DOMAIN_ROOT}` where:
  - `t8` is the first 8 hex chars if `tenantId` looks like a UUID, otherwise first 12 slug chars
  - `e8` is calculated similarly for `extensionId`
  - Rationale: keep `metadata.name` within Kubernetes 63-char limit for DomainMapping resources.
- `ensureDomainMapping({ domain, namespace, kservice })`:
  - Preflight checks:
    - Verifies Knative Service exists: `serving.knative.dev/v1`, resource `services`, name `${kservice}` in `${namespace}`
    - Ensures ClusterDomainClaim exists for `${domain}` (`networking.internal.knative.dev/v1alpha1`).
      - If env `KNATIVE_AUTO_CREATE_CDC=true`, the worker attempts to create the CDC.
      - Otherwise, it fails with a clear message including a ready-to-apply CDC manifest.
  - Creates or patches `DomainMapping`:
    - `apiVersion: serving.knative.dev/v1beta1`, `kind: DomainMapping`, `metadata.name: ${domain}`
    - `spec.ref: { apiVersion: 'serving.knative.dev/v1', kind: 'Service', name: ${kservice} }`
- On success, status in DB is updated to `{ state: 'ready' }` and `runner_ref` stores a small reference object.

## Runner

- Exposes `GET /` which reads Host → calls `REGISTRY_BASE_URL/api/installs/lookup-by-host` (API wrapper around the `installs.lookupByHost` server action) → redirects to `/ext-ui/{extensionId}/{content_hash}/index.html`.
- Continues to enforce strict validation in `/ext-ui` route via `/api/installs/validate`.

## Next.js (EE Server)

- Server actions-first (business logic):
  - `installs.lookupByHost(host: string)` → `{ tenant_id, extension_id, content_hash }`.
  - `installs.validate(tenant: string, extension: string, hash: string)` → `{ valid: boolean }`.
  - `installs.provisionDomain(installId: string)` / `installs.reprovision(installId: string)` → triggers Temporal workflow.
- Thin API wrappers for external consumers (delegate to actions only):
  - `GET /api/installs/lookup-by-host?host=...`
  - `GET /api/installs/validate?tenant=...&extension=...&hash=...`
  - `POST /api/installs/:id/reprovision`

### Lookup and Validate Contracts

- LookupByHost response: `{ tenant_id: string, extension_id: string, content_hash: string }`.
- Validate response: `{ valid: boolean }`.

## Helm Values Hints (Infra Repo)

- temporal-worker chart:
  - `serviceAccount.name: temporal-worker`
  - env:
    - `RUNNER_NAMESPACE: <ns>`
    - `RUNNER_KSERVICE: runner`
    - `EXT_DOMAIN_ROOT: ext.example.com`
    - `KNATIVE_AUTO_CREATE_CDC: "true"` (optional; requires ClusterRole to manage ClusterDomainClaims)
  - RBAC templates include Role/RoleBinding above when enabled.

## RBAC for ClusterDomainClaim (optional)

To auto-create ClusterDomainClaims, grant the Temporal worker a ClusterRole with read/create/patch on `clusterdomainclaims.networking.internal.knative.dev` and bind it via ClusterRoleBinding to the worker ServiceAccount.

---
Change history: Introduced with per-install app domains (Plan 1.f).