API Reference

API Reference

Reference for the helm/agent-manager umbrella chart: structure, values conventions, subchart dependencies, and the migrator Job hook pattern.

Chart structure

helm/agent-manager/
  Chart.yaml          # apiVersion, name, version, appVersion, dependencies[]
  Chart.lock          # pinned dependency digests; committed; regenerated by helm dep update
  values.yaml         # canonical defaults — every key present here
  values-dev.yaml     # dev overlay (Kind cluster)
  values-prod.yaml    # production overlay
  charts/             # vendored local subcharts (tarballs + extracted)
  templates/          # umbrella-owned Kubernetes objects
    _helpers.tpl
    *-app-db-url-secret.yaml   # one per service; cross-service Secret injection

values.yaml conventions

Top-level keys

Each key at the root of values.yaml corresponds to either a shared infrastructure component or a service subchart. The umbrella owns the global block; everything else is passed through to the matching subchart under its own scope.

global:
  namespace: paper-board          # Kubernetes namespace for all objects
  domain: paperboard.app          # external domain; used by Ingress (Phase 7+)
  imageRegistry: ghcr.io/paper-board
  imagePullPolicy: IfNotPresent

Service subchart block

Every service subchart block follows this shape:

<svc>:
  enabled: false              # feature-flag; default false until the phase activates it
  secrets:
    create: true              # umbrella creates Secrets in dev; false in prod (ESO owns them)
    <key>: ""                 # placeholder; real values supplied via --set or ESO
  server:
    config:
      env: dev                # propagated as SERVER_ENV env var inside the container
  networkPolicy:
    enabled: true             # NetworkPolicy default-deny per ADR-0005

Infrastructure components

Key	Type	Default	Notes
postgres.enabled	bool	true	Disable only on clusters with an external Postgres
pgbouncer	object	always on	No enabled toggle — mandatory Phases 1-4 (see Chart.yaml)
cert-manager.enabled	bool	false	Phase 5+ (mTLS via cert-manager)
redis.enabled	bool	false	Phase 1.5+ (event bus)

Database users (PoLP)

postgres.appUsers lists one entry per service. Each entry creates a Postgres role with USAGE on its own schema and ALL PRIVILEGES on its own tables. Passwords are injected at init time from environment variables; they are never committed.

postgres:
  appUsers:
    - name: identity_app
      schema: identity
    - name: agents_app
      schema: agents
    - name: billing_app
      schema: billing
    - name: platform_app
      schema: platform

Subchart dependencies

Local subcharts (charts/)

Vendored directly in this repo. Managed by the infra team.

Chart	Version	Condition	Notes
postgres	0.2.0	postgres.enabled	Single-cluster Postgres with init-db
pgbouncer	0.1.0	none	Always rendered; transaction pool mode
cert-manager	0.1.0	cert-manager.enabled	Phase 5+ only
redis	0.1.0	redis.enabled	Phase 1.5+

OCI subcharts (oci://ghcr.io/paper-board/helm)

Each service repo owns and publishes its chart. The umbrella declares the pinned version; helm dep update pulls the OCI artifact and writes the digest to Chart.lock.

Chart	Current version	Condition
identity	0.2.1	identity.enabled
agents	0.2.3	agents.enabled

Future services (runtime, compute, billing, platform) follow the same pattern: the service repo tags a new OCI chart version, the umbrella bumps the pinned version in Chart.yaml, and helm dep update regenerates Chart.lock.

Migrator Job hook pattern

Every service with a schema ships a cmd/migrator binary (a ~30-line shim over paper-board/sdk/migrator). The service’s Helm chart includes a Kubernetes Job annotated as a Helm pre-install / pre-upgrade hook. The umbrella triggers this Job automatically on every helm upgrade --install.

Hook annotations

# Inside the service subchart templates/migrator-job.yaml
metadata:
  annotations:
    "helm.sh/hook": pre-install,pre-upgrade
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded

hook-delete-policy: before-hook-creation,hook-succeeded ensures the Job is cleaned up after a successful run and does not block the next deploy.

Connection requirements

The migrator Job must connect to Postgres directly (port 5432), not through PgBouncer (port 6432). PgBouncer’s transaction pool mode breaks the advisory-lock session required by golang-migrate.

env:
  - name: MIGRATION_DB_URL    # port 5432 — direct Postgres
    valueFrom:
      secretKeyRef:
        name: <svc>-migration-db-url
        key: url

The application Deployment uses a separate Secret:

env:
  - name: DATABASE_URL        # port 6432 — PgBouncer
    valueFrom:
      secretKeyRef:
        name: <svc>-app-db-url
        key: url

Never mount MIGRATION_DB_URL into the application container, and never use DATABASE_URL in the migrator Job.

Advisory lock IDs

Each service uses a distinct advisory lock ID, allowing parallel migrations across services without contention:

Service	Lock ID
identity	1
billing	2
agents	3
platform	4

Migrator subcommands

The migrator binary (cobra CLI) supports:

Subcommand	Effect
up	Apply all pending migrations
up --dry-run	Print pending SQL without executing
down N	Roll back N migrations
force VERSION	Force-set the migration version (recovery only)
version	Print current applied version
drop	Drop all tables — requires MIGRATOR_ENV=dev