remora/docs/spec/deployment.md

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.

make check-deployment

This installs the chart on fresh kind, runs a cargo-nextest Job, rolls each workload, wipes Dragonfly, and verifies queue reconstruction.