svcforge: reference implementation

Complete working build of the system learn-python/ teaches.
164 tests, mypy --strict clean, domain coverage 99%.

deploy/chart/values.yaml

@@ -0,0 +1,174 @@
+# svcforge chart values.
+#
+# The digests below are the deployment. CI builds each image once, pushes it, reads the
+# digest back with `docker buildx imagetools inspect`, and `yq -i`s it into this file as
+# its last act. ArgoCD notices the commit and syncs. Nothing else deploys svcforge.
+#
+# Tags are banned. A tag is a mutable pointer, which means "what is running" and "what
+# this file says" can silently diverge. A digest cannot.
+
+nameOverride: ""
+fullnameOverride: ""
+
+image:
+  registry: gitea.oci-oci.duckdns.org
+  pullPolicy: IfNotPresent
+  pullSecrets: []
+  # One repo + one digest per service: CI's matrix builds three images, so there are three
+  # digests. The zeros are placeholders — a fresh clone must be bumped by CI before it can
+  # deploy, which is the intended failure mode. Never hand-edit these.
+  api:
+    repo: gitea.oci-oci.duckdns.org/gitea_admin/svcforge-api
+    digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+  worker:
+    repo: gitea.oci-oci.duckdns.org/gitea_admin/svcforge-worker
+    digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+  reconciler:
+    repo: gitea.oci-oci.duckdns.org/gitea_admin/svcforge-reconciler
+    digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+
+api:
+  replicas: 2
+  # One process per pod. Module 7 took the "scale with replicas" fix over
+  # PROMETHEUS_MULTIPROC_DIR, so `uvicorn --workers N` here would corrupt the metrics.
+  resources:
+    requests: {cpu: 50m, memory: 128Mi}
+    limits: {memory: 256Mi}
+  service:
+    type: ClusterIP
+    port: 80
+    targetPort: 8000
+  ingress:
+    enabled: true
+    className: nginx
+    annotations:
+      cert-manager.io/cluster-issuer: letsencrypt-prod
+    host: svcforge.oci-oci.duckdns.org
+    tls:
+      enabled: true
+      secretName: svcforge-tls
+
+worker:
+  # Plain replicas. No HPA: the day `replicas: 2` stops keeping up, not before.
+  replicas: 2
+  concurrency: 4
+  resources:
+    requests: {cpu: 100m, memory: 192Mi}
+    limits: {memory: 512Mi}
+
+reconciler:
+  # A singleton, and not by convention — the four checks are not safe to run twice
+  # concurrently. replicas is deliberately not a value: there is nothing to tune.
+  intervalSeconds: 60
+  resources:
+    requests: {cpu: 50m, memory: 128Mi}
+    limits: {memory: 256Mi}
+
+# Postgres pool sizing. replicas × maxSize is spent against the Supabase pooler budget:
+# api(2 × 5) + worker(2 × 5) + reconciler(1 × 2) = 22 connections. Raise with care.
+pool:
+  minSize: 1
+  maxSize: 5
+
+migrate:
+  # backoffLimit: 0 — a failed migration must fail the release, not retry into a
+  # half-applied schema. Migrations run here and only here; never on app startup.
+  enabled: true
+  resources:
+    requests: {cpu: 50m, memory: 128Mi}
+    limits: {memory: 256Mi}
+
+auth:
+  jwksUrl: https://auth.oci-oci.duckdns.org/realms/svcforge/protocol/openid-connect/certs
+  issuer: https://auth.oci-oci.duckdns.org/realms/svcforge
+  audience: svcforge
+
+otel:
+  enabled: true
+  endpoint: http://alloy.observability.svc.cluster.local:4317
+
+log:
+  level: info
+
+# The DSNs are pulled from Vault by external-secrets into a Secret the pods envFrom.
+# No DSN is ever a chart value, a ConfigMap key, or a CI variable.
+externalSecret:
+  enabled: true
+  secretStoreRef:
+    name: vault
+    kind: ClusterSecretStore
+  refreshInterval: 1h
+  # target Secret name; keys land as SVCFORGE_PG_DSN / SVCFORGE_PG_DSN_SESSION / SVCFORGE_REDIS_DSN
+  targetName: svcforge-secrets
+  remoteRefs:
+    - secretKey: SVCFORGE_PG_DSN
+      key: svcforge/postgres
+      property: dsn_pooler
+    - secretKey: SVCFORGE_PG_DSN_SESSION
+      key: svcforge/postgres
+      property: dsn_session
+    - secretKey: SVCFORGE_REDIS_DSN
+      key: svcforge/redis
+      property: dsn
+
+rbac:
+  # The worker helm-installs tenant releases into namespaces it creates. `namespaces` is a
+  # cluster-scoped resource, so `create namespaces` cannot be granted by a namespaced Role
+  # — this has to be a ClusterRole. It is still least-privilege: named resources, named
+  # verbs, no `*`, no cluster-admin, and no rbac.authorization.k8s.io group at all, so the
+  # worker cannot grant itself anything further.
+  create: true
+
+serviceAccount:
+  create: true
+  annotations: {}
+
+# Chart-native only. A hand-authored ServiceMonitor/PrometheusRule CR is banned — the
+# chart owns these, gated by these flags.
+serviceMonitor:
+  enabled: true
+  interval: 30s
+
+prometheusRule:
+  enabled: true
+  rules:
+    - alert: SvcforgeQueueDepthRising
+      expr: deriv(svcforge_queue_depth[10m]) > 0
+      for: 10m
+      labels:
+        severity: warning
+      annotations:
+        summary: svcforge queue depth is rising and not draining
+        runbook_url: https://gitea.oci-oci.duckdns.org/gitea_admin/svcforge/src/branch/master/RUNBOOK.md#queue-stuck
+    - alert: SvcforgeProvisionSlow
+      expr: histogram_quantile(0.95, sum by (le) (rate(svcforge_provision_duration_seconds_bucket[30m]))) > 300
+      for: 15m
+      labels:
+        severity: warning
+      annotations:
+        summary: svcforge p95 provision time is over 5 minutes
+        runbook_url: https://gitea.oci-oci.duckdns.org/gitea_admin/svcforge/src/branch/master/RUNBOOK.md#provision-failing
+    - alert: SvcforgeTaskFailed
+      expr: sum(svcforge_tasks_failed_total) > 0
+      labels:
+        severity: warning
+      annotations:
+        summary: a svcforge task exhausted its retries
+        runbook_url: https://gitea.oci-oci.duckdns.org/gitea_admin/svcforge/src/branch/master/RUNBOOK.md#provision-failing
+    - alert: SvcforgeReconcilerStale
+      expr: time() - svcforge_reconciler_last_tick_timestamp_seconds > 300
+      labels:
+        severity: critical
+      annotations:
+        summary: the svcforge reconciler has not ticked in 5 minutes
+        runbook_url: https://gitea.oci-oci.duckdns.org/gitea_admin/svcforge/src/branch/master/RUNBOOK.md#orphaned-release
+
+# Not in the spec. Off by default: on a three-node k3s a PDB that cannot be satisfied
+# blocks drains, which is worse than the disruption it prevents.
+podDisruptionBudget:
+  enabled: false
+  minAvailable: 1
+
+nodeSelector: {}
+tolerations: []
+affinity: {}