Kubernetes

Document ID: DEP-003
File Path: docs/12-deployment/kubernetes.md
Version: 1.1.0
Status: Draft — describes the long-term, aspirational multi-service topology (independent api-gateway/agent-runtime/workflow-engine/… services, each with its own HPA, plus a tool-worker DaemonSet with gVisor/Kata sandbox pools). Not built. The platform today is one binary (wovyr-cli). For what actually deploys, see deployment/helm/wovyr/README.md — a real Helm chart for the single-binary + Postgres + Qdrant topology (the same shape as deployment/docker-compose.yml), authored 2026-07-05, validated offline (helm lint/helm template/kubeconform) but never applied to a live cluster. Owner: Platform Operations Team
Last Updated: 2026-07-05

1. Purpose

This document describes deploying the Wovyr AI Platform on Kubernetes — the recommended production topology with independent scaling, health-gated rollouts, and isolated tool execution.

2. Workload Mapping

Service	Workload	Scaling
API Gateway	Deployment	HPA (CPU/RPS)
Agent Runtime	Deployment	HPA
Workflow Engine	Deployment	HPA
LLM Gateway	Deployment	HPA
Memory Engine	Deployment	HPA (read-heavy)
Tool Runtime (control)	Deployment	HPA
Tool Runtime (workers)	Deployment / DaemonSet	HPA + node pools
Plugin Engine	Deployment	HPA
Dashboard	Deployment	HPA

Stateful backends (PostgreSQL, Redis, Qdrant, NATS) run as operators/StatefulSets or managed services (see Terraform).

3. Probes

Every service exposes standard endpoints; map them to probes:

livenessProbe:  { httpGet: { path: /healthz, port: 8080 }, periodSeconds: 10 }
readinessProbe: { httpGet: { path: /readyz,  port: 8080 }, periodSeconds: 5 }

Readiness gates traffic until dependencies (DB, NATS) are reachable.

4. Deployment Example

apiVersion: apps/v1
kind: Deployment
metadata: { name: api-gateway }
spec:
  replicas: 3
  selector: { matchLabels: { app: api-gateway } }
  template:
    metadata: { labels: { app: api-gateway } }
    spec:
      securityContext: { runAsNonRoot: true, readOnlyRootFilesystem: true }
      containers:
        - name: api-gateway
          image: wovyr/api-gateway:1.0.0
          ports: [{ containerPort: 8080 }, { containerPort: 9090 }]
          envFrom: [{ secretRef: { name: wovyr-config } }]
          resources:
            requests: { cpu: "500m", memory: "256Mi" }
            limits:   { cpu: "2",    memory: "512Mi" }

5. Autoscaling

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata: { name: tool-runtime-worker }
spec:
  scaleTargetRef: { kind: Deployment, name: tool-runtime-worker }
  minReplicas: 2
  maxReplicas: 50
  metrics:
    - type: Pods
      pods: { metric: { name: tool_queue_seconds }, target: { type: AverageValue, averageValue: "0.05" } }

Tool worker pools autoscale on queue wait (Worker Pool §6); the cluster autoscaler adds nodes for the untrusted/microVM pool separately.

6. Tool Worker Isolation

Untrusted tool workers run on dedicated node pools (taints/tolerations) with gVisor/Kata runtime classes for strong isolation (Sandbox backends).
runtimeClassName: gvisor (or kata) is set on untrusted worker pods.

spec:
  runtimeClassName: gvisor
  nodeSelector: { wovyr.io/pool: untrusted }
  tolerations: [{ key: wovyr.io/untrusted, operator: Exists }]

7. Networking

An Ingress (or Gateway API) routes external traffic to the API Gateway and Dashboard (deployment architecture).
mTLS between services via a service mesh or native TLS.
NetworkPolicies enforce least-privilege east-west traffic; tool egress is controlled per Tool Runtime network isolation.

8. Configuration & Secrets

Config via ConfigMaps; secrets via Kubernetes Secrets backed by an external vault (e.g. CSI secrets driver).
Provider keys and DB credentials are mounted as secret references, never in manifests.

9. Rollouts

Rolling updates with maxUnavailable: 0, gated by readiness probes.
Workers drain in-flight executions before termination (terminationGracePeriodSeconds aligned to max tool timeout).
DB migrations run as a pre-deploy Job/initContainer.

10. Observability

ServiceMonitors scrape /metrics; OpenTelemetry collector gathers traces.
Dashboards/alerts per Observability (planned).

12. Revision History

Version	Date	Description
1.1.0	2026-07-05	Added a status note pointing to `deployment/helm/wovyr/` — a real chart for the actual single-binary topology, distinct from this doc’s aspirational multi-service split
1.0.0	2026-06-27	Initial Kubernetes deployment guide