Ship production deployment and runtime observability

docs/spec/architecture.md

@@ -255,3 +255,6 @@ flowchart TD
 - Deployment configuration supplies service credentials and endpoints, configures allowed source reachability, and provides infrastructure-level egress enforcement.
 - Deployment configuration reserves and protects Remora's internal target namespace, excludes it from independent lifecycle deletion, and establishes either exclusive write ownership or immutable version addressing.
 - Deployment configuration selects secret-store topology and policies while preserving the application-level grant-bound credential-resolution contract.
+
+The maintained realization of these responsibilities is defined by
+[`Kubernetes Deployment`](deployment.md).

docs/spec/deployment.md

@@ -0,0 +1,56 @@
+# Kubernetes Deployment
+
+`deploy/charts/remora` runs API, Worker, and WebClient as separate Deployments.
+CloudNativePG, Dragonfly, Vault, ZITADEL, and VersityGW remain externally
+managed.
+
+## Identity and configuration
+
+- Each workload has a distinct service account; automatic token mounting is
+  disabled.
+- The public API uses port 8080. The Worker API uses port 8443 with
+  chart-managed mTLS retained across upgrades.
+- Vault Agent uses bounded projected tokens and separate API-write and
+  Worker-read Kubernetes roles. Applications see only the memory-backed Vault
+  token sink.
+- CloudNativePG supplies its read-write URL through a Secret. API replicas run
+  migrations; Workers wait for the core schema.
+- Dragonfly uses a deployment-unique namespace.
+  `REMORA_GLOBAL_ATTEMPT_LIMIT` and `REMORA_WORKER_LOCAL_ATTEMPT_LIMIT` remain
+  independent.
+- ZITADEL supplies the issuer, project audience, client identifier, and exact
+  project-role claim.
+- VersityGW uses dedicated credentials and a bucket whose `_remora` namespace
+  excludes other writers and lifecycle expiry. Deployments unable to establish
+  both properties are unsupported.
+
+## Security
+
+NetworkPolicies default-deny each workload, isolate the Worker and management
+ports, and allow dependencies by selector or CIDR. Public source egress excludes
+non-global and metadata-capable IPv4 ranges. Private sources require matching
+application and NetworkPolicy CIDR allowances.
+
+Containers run non-root with read-only roots, dropped capabilities, resource
+limits, and no service links. Worker temporary storage is bounded.
+
+## Operations
+
+API and Worker expose liveness, dependency-aware readiness, and Prometheus
+metrics on port 9090. WebClient exposes equivalent endpoints. Optional
+ServiceMonitor and PrometheusRule resources cover readiness, recovery failures,
+and WebClient availability.
+
+Processes emit JSON logs and W3C trace context. Access logs omit query strings,
+headers, and bodies. Deployments use surge-first rollout, readiness gates,
+disruption budgets, topology spreading, and bounded termination.
+
+API background loops reconcile attempts, Dragonfly projection, credential
+intents, staging cleanup, deletion, and event retention.
+
+```sh
+make check-deployment
+```
+
+This installs the chart on fresh kind, runs a cargo-nextest Job, rolls each
+workload, wipes Dragonfly, and verifies queue reconstruction.