remora/docs/spec/deployment.md

Kubernetes Deployment

deploy/charts/remora runs API, Worker, and WebClient with its WebBFF 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 the centrally owned ordered migration set; Workers wait for its complete schema generation.
• Dragonfly uses a deployment-unique namespace. REMORA_GLOBAL_ATTEMPT_LIMIT and REMORA_WORKER_LOCAL_ATTEMPT_LIMIT remain independent.
• The WebBFF stores ephemeral WebSessions through a WebBFF-only Dragonfly credential and namespace. Its credential Secret is not shared with API or Worker coordination access. Loss of that namespace signs browser users out without affecting durable application state.
• ZITADEL supplies the issuer, project audience, exact project-role claim, and a confidential WebBFF client whose secret is mounted from a Secret.
• 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. The WebBFF may reach only the API, identity provider, and its session store. 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.

TLS ingress redirects HTTP to HTTPS and emits HSTS. The WebBFF session cookie is always Secure; unencrypted origins are unsupported outside loopback test environments.

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.