Helm

Document ID: DEP-004
File Path: docs/12-deployment/helm.md
Version: 1.1.0
Status: Draft — describes the long-term, aspirational multi-chart/ multi-service packaging. Not built. A real, working chart exists today at deployment/helm/wovyr/ — one chart for the actual single-binary + Postgres + Qdrant topology (mirrors deployment/docker-compose.yml), not the per-service chart split this doc describes. See that chart’s README.md for what it does and doesn’t prove (validated offline with helm lint/helm template/kubeconform; never applied to a live cluster). Owner: Platform Operations Team
Last Updated: 2026-07-05

1. Purpose

This document describes the Wovyr AI Platform Helm chart — the packaged, configurable way to install and upgrade the platform on Kubernetes.

2. Chart Layout

wovyr/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── api-gateway/        # deployment, service, hpa
│   ├── agent-runtime/
│   ├── workflow-engine/
│   ├── llm-gateway/
│   ├── memory-engine/
│   ├── tool-runtime/       # control + worker pools
│   ├── plugin-engine/
│   ├── dashboard/
│   ├── ingress.yaml
│   ├── networkpolicies.yaml
│   └── migrations-job.yaml
└── charts/                 # optional subcharts: postgres, redis, qdrant, nats

Backends can be installed as subchart dependencies (dev) or pointed at managed services (production, via Terraform).

3. Install

helm repo add wovyr https://charts.wovyr.example.com
helm install wovyr wovyr/wovyr -n wovyr --create-namespace -f my-values.yaml

4. Values (excerpt)

global:
  image: { registry: ghcr.io/wovyr-ai, tag: "1.0.0" }
  domain: wovyr.example.com
  mtls: true

backends:
  postgres: { managed: true, url: "secret://wovyr/pg-url" }
  redis:    { managed: true, url: "secret://wovyr/redis-url" }
  qdrant:   { managed: true, url: "http://qdrant:6333" }
  nats:     { managed: true, url: "nats://nats:4222" }

services:
  apiGateway:   { replicas: 3, hpa: { min: 3, max: 20 } }
  memoryEngine: { replicas: 2, hpa: { min: 2, max: 10 } }
  toolRuntime:
    control: { replicas: 2 }
    workers:
      trusted:   { hpa: { min: 2, max: 20 } }
      untrusted: { runtimeClass: gvisor, nodePool: untrusted, hpa: { min: 1, max: 30 } }

dashboard: { enabled: true, replicas: 2 }
ingress:   { enabled: true, className: nginx, tls: true }

Values mirror the Kubernetes workload mapping and tool-worker isolation.

5. Secrets

The chart consumes secret references, not literals:

secrets:
  backend: external          # external | k8s
  refs:
    databaseUrl: secret://wovyr/pg-url
    providerKeys: secret://wovyr/llm-keys

With external, the chart wires the CSI secrets driver / vault; with k8s, it expects pre-created Secrets.

6. Upgrades

helm upgrade wovyr wovyr/wovyr -n wovyr -f my-values.yaml
helm history wovyr -n wovyr
helm rollback wovyr <revision> -n wovyr

Pre-upgrade hook runs DB migrations.
Rolling updates honor readiness probes and worker draining (K8s §9).
helm rollback reverts to a prior release revision.

7. Environments

Maintain per-environment values files (values-dev.yaml, values-prod.yaml) or use a GitOps tool (Argo CD/Flux) to apply the chart declaratively.

8. Uninstall

helm uninstall wovyr -n wovyr      # leaves PVCs by default

Persistent data (PostgreSQL/Qdrant PVCs, object storage) is retained unless explicitly removed.

10. Revision History

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