For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/operations/kubernetes.md.
  • English
  • Kubernetes Multi-Replica Production Deployment

    Yearning v4 is a completely stateless Go monolith backed by PostgreSQL for shared leases, sessions, scheduled jobs, and SSE fan-out, ready for multi-replica Kubernetes deployments with zero Pod-local state.

    Standard manifests live under backend/deploy/k8s/:

    • backend/deploy/k8s/control-plane.yaml: Stateless multi-replica Deployment, Service, probes, and hardened securityContext
    • backend/deploy/k8s/migration-workloads.yaml: Isolated schema migration Job and temporary migration review Deployment
    • backend/deploy/k8s/network-policy.yaml: Least-privilege NetworkPolicy

    Security Hardening & 3-Role PostgreSQL Isolation

    • Distroless Non-Root Containers: linux/amd64 and linux/arm64, UID 65532, readOnlyRootFilesystem: true, allowPrivilegeEscalation: false, capabilities.drop: ["ALL"].
    • Mandatory 3-Role Isolation (db/roles/grants.sql):
      • yearning_migrator: Used exclusively by yearning-schema-migration Job to apply db/migrations/*.sql (no keyring access).
      • yearning_app: Non-superuser runtime role used by yearning Deployment (verified on boot by database_role_self_check in production mode).
      • yearning_retention: Injected via YEARNING_RETENTION_DATABASE_DSN for 90-day audit and 7-day raw payload retention cleanup.

    Four Production Readiness Probes

    Pods receive traffic only when all four readiness checks succeed:

    1. metadata_postgresql: Live PostgreSQL pool health.
    2. key_provider: Valid 6-purpose AEAD keyring.json readable.
    3. schema_ledger: schema_migrations exists with zero failed rows.
    4. exact_schema_version + database_role_self_check: Applied schema version exactly matches the image's /usr/share/yearning/db-migrations and the runtime role satisfies non-superuser least-privilege checks.

    Standard Rollout Sequence

    kubectl apply -f backend/deploy/k8s/network-policy.yaml
    kubectl apply -f backend/deploy/k8s/migration-workloads.yaml
    kubectl wait --for=condition=complete job/yearning-schema-migration -n yearning --timeout=300s
    kubectl apply -f backend/deploy/k8s/control-plane.yaml
    kubectl rollout status deployment/yearning -n yearning --timeout=300s