Feat/aiworks

[nickottocode]

Add deepgram-aiworks Helm chart

New chart at charts/deepgram-aiworks/ for deploying VoiceWorks
(AIWorks) self-hosted on Kubernetes. Parallel to deepgram-self-hosted,
independently versioned, backend-only (no frontend) for v1.

Summary

• New chart with full template set: Deployment, Service, ConfigMap
  (renders config.toml from values), Secret (creds + optional TLS
  material), PVC, plus optional Ingress / HPA / NetworkPolicy /
  ServiceMonitor each gated on its own values flag.
• Helm helm test post-install Pod that curls /api/health (branches
  on server.tls.enabled to use http vs https).
• CI matrix at .github/workflows/aiworks-chart-ci.yml — runs
  helm lint + helm template + kubeconform across three values
  scenarios (default, files-mode, ingress + mTLS).
• publish.yml extended so version bumps on either deepgram-self-hosted
  OR deepgram-aiworks trigger a release; handles the "new chart on
  first merge" edge case (no prior Chart.yaml in HEAD^).
• Chart README with prerequisites, quick start, four example deployments
  (files+open mode, ingress, in-process TLS, postgres), upgrade /
  uninstall recipes, and a values reference table.

Quick-start example

helm repo add deepgram https://deepgram.github.io/self-hosted-resources
helm install aiworks deepgram/deepgram-aiworks \
  --set license.apiKey=<deepgram-license-uuid> \
  --set selfHosted.apiKey=<40+-char-shared-secret> \
  --set selfHosted.bootstrapSubject=$(uuidgen | tr A-Z a-z)

Connect clients via:

ws://<service-or-ingress>/api/repos/<any-uuid>/flows/<flow-slug>/execute
Authorization: Token <selfHosted.apiKey>

Architectural notes for reviewers

• License-proxy is NOT bundled. The chart's license.serverUrl
  defaults to http://license-proxy.deepgram.svc.cluster.local:8080
  with https://license.deepgram.com as fallback. Operators reuse the
  license-proxy from an existing deepgram-self-hosted install or
  point at a standalone deployment.
• ${VW_API_KEY} flows through pod env. Helm can't inline Secret
  values at template time, so the ConfigMap renders
  [self_hosted].api_key = "${VW_API_KEY}" as a literal placeholder.
  Voiceworks's config loader resolves it from std::env::var at
  startup — the corresponding backend change shipped in voiceworks
  commit 9302010. The chart README documents this contract in the
  values reference.
• /api/health is used for all three probes (readiness / liveness /
  startup). It's unconditionally registered in both files and
  postgres storage modes, so probe config doesn't need to branch on
  storage.mode.
• Security defaults: non-root UID 10001, readOnlyRootFilesystem,
  all caps dropped. Matches the voiceworks-self-hosted image's user.
• updateStrategy.rollingUpdate.maxUnavailable: 0 by default —
  keeps at least one pod serving during rolling upgrades. Long-lived
  WebSocket sessions drain over terminationGracePeriodSeconds.

What's intentionally out of scope

• Self-hosted frontend (Next.js editor). Backend-only for v1.
• Bundled license-proxy. Operators bring their own (existing
  deepgram-self-hosted install or standalone).
• ACME / Let's Encrypt in-process. Use an ingress controller for
  public-internet TLS termination.
• SNI-based multi-cert. Single cert per listener.

Companion voiceworks work

This PR is the chart half of a four-plan effort to make AIWorks
production-ready for self-hosted. The matching backend changes ship
on the feat/self-hosted branch of github.com/deepgram/voiceworks —
that branch will land separately.

Design spec lives at
voiceworks/docs/superpowers/specs/2026-05-18-aiworks-self-hosted-production-readiness-design.md.

Test plan

• helm lint clean against all three CI values files
  (default-values.yaml, files-mode-values.yaml, ingress-mtls-values.yaml)
• helm template produces well-formed manifests for each scenario
• CI workflow YAML parses; kubeconform step uses
  -ignore-missing-schemas to allow CRDs (ServiceMonitor)
• First merge to main triggers chart release via publish.yml
  (verify after merge — the "new chart on first merge" branch is
  exercised here for the first time)
• helm install against a real cluster pointing at an existing
  deepgram-self-hosted license-proxy
• helm test aiworks returns success in both TLS-on and TLS-off
  configurations

Required follow-ups (out of this PR)

• voiceworks feat/self-hosted branch must land before the chart is
  usable end-to-end (provides the backend image and the
  ${VW_API_KEY} env-var resolution this chart relies on).
• developers.deepgram.com should get an "AIWorks (Self-Hosted)"
  section that links into the chart README and the in-product docs
  shipping in voiceworks.

[mattsloan-dg]

I will be taking a look at this!

[jkroll-deepgram]

Solid bones — sensible security defaults (non-root 10001, read-only rootfs, drop ALL caps), checksum-pinned configmap restart, three meaningful CI scenarios, decent values-reference docs. Inline comments cover the specific bugs / footguns I'd want addressed; this top-level note is for the cross-cutting convention gaps with deepgram-self-hosted's CI.

Missing repo conventions:

• No CHANGELOG.md. The existing chart has one and ci.yml fails the PR if a non-doc change to the chart skips the changelog. The new aiworks-chart-ci.yml doesn't enforce this. Either add a CHANGELOG.md + the equivalent CI check, or accept the inconsistency knowingly.
• No helm-docs. ci.yml regenerates the deepgram-self-hosted README from values.yaml comments and fails on drift. The new chart's README is hand-written and unenforced — server.prefix, server.wsIdleTimeout, storage.postgres.dsnExistingSecret, storage.postgres.dsnExistingSecretKey are already missing from the values-reference table. Recommend adopting helm-docs for parity.
• No chart-version-bump CI check. Existing CI fails a PR if appVersion bumped without version bumping. New CI has no equivalent — only publish.yml enforces it at release time. Cheap to add and prevents a "merged but didn't publish" surprise.

Risks worth flagging (already acknowledged in the PR body but restating for the record):

• Chart depends on voiceworks feat/self-hosted landing first for ${VW_API_KEY} env resolution. Recommend either holding merge until that lands, or tagging this release in a way publish.yml won't pick up automatically.
• The "first chart release" branch of publish.yml (empty OLD_VERSION ⇒ treated as bump) is exercised here for the first time. A dry-run with act or workflow_dispatch against a throwaway repo would derisk it.

[jkroll-deepgram]

clientCaBundleExistingSecret is honored here but nowhere else in the chart — secret.yaml only writes ca.crt from the inline clientCaBundle, and deployment.yaml only mounts one TLS volume (the chart-managed or server.tls.existingSecret-referenced Secret). If an operator sets clientCaBundleExistingSecret, config.toml will reference /etc/voiceworks/tls/ca.crt but no such file is mounted, and voiceworks will fail to start.

Two ways out:

• Drop clientCaBundleExistingSecret and require the CA bundle to live in the same TLS Secret as tls.crt/tls.key under the key ca.crt. Document the expected key names in the README.
• Or add a second volume/volumeMount that pulls ca.crt from clientCaBundleExistingSecret and projects it next to tls.crt.

[jkroll-deepgram]

Heads up: this default interacts badly with the other defaults on this chart. With replicaCount: 1 (line 17), storage.files.persistence.enabled: true (line 46), and pvc.yaml hardcoding accessModes: ["ReadWriteOnce"], a rolling update has to schedule the new pod before terminating the old one — but the new pod can't mount the RWO volume while the old one holds it. The roll stalls indefinitely.

Same shape blocks HPA: scaling.auto.maxReplicas: 5 + files mode + RWO can't scale past 1.

Options:

• Default maxUnavailable: 1 (correct for replicaCount: 1) and let operators tune up when they scale.
• Expose accessModes in values.yaml so RWX-capable clusters can opt in.
• Add a fail/required check in templates when the combination is incompatible (replicas > 1 + files + RWO).

[jkroll-deepgram]

-ignore-missing-schemas silently accepts any kind whose schema isn't in the bundle, including kinds introduced by a typo (e.g., kind: Deployement). The only kind in this chart that needs the escape hatch is ServiceMonitor (from the prometheus-operator CRDs).

Tighter options:

• -skip monitoring.coreos.com/v1/ServiceMonitor — skip just that one kind.
• -schema-location 'default' -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' — load community CRD schemas so ServiceMonitor (and others) get validated.

[jkroll-deepgram]

If an operator sets networkPolicy.enabled: true but leaves ingressFrom: [] (the default in values.yaml), the {{- with ...}} block elides the entire ingress: clause. The rendered Policy then declares policyTypes: [Ingress] with no rules — k8s reads that as "deny all ingress to selected pods."

The Service stops accepting any traffic, including from kube-proxy / probes. Failure mode looks like "everything is down" with no obvious cause.

Fixes:

• {{- required "networkPolicy.ingressFrom must be set when networkPolicy.enabled" .Values.networkPolicy.ingressFrom }} to fail at template time, or
• Default to an ingressFrom rule like - podSelector: {} (same namespace) and document the implication, or
• Document loudly in the README that empty ingressFrom is default-deny.

[jkroll-deepgram]

This field controls two unrelated things: the key the chart reads inside secrets.existingSecret (the BYO Secret path) and the key the chart writes in its own credentials Secret (secret.yaml). If an operator changes it on an existing release with secrets.existingSecret: "", the chart-created Secret renames its key — but deployment.yaml's env ref also follows the rename, so it superficially keeps working until something else (a sidecar, an in-place patch, an external reader) trips over the new key name.

Suggest splitting the responsibility:

• Hardcode the chart-written key names (DEEPGRAM_API_KEY and VW_API_KEY are standard) inside secret.yaml and deployment.yaml.
• Keep *ExistingSecretKey as a read-only knob that only applies when secrets.existingSecret is set.

[jkroll-deepgram]

This scrapes /metrics on the same Service port that handles /api/health and the WebSocket execute endpoint. Worth verifying voiceworks actually exposes Prometheus metrics on the main listener — many backends route them onto a separate :9090 (or :3001, etc.) admin port that isn't in the Service or container spec.

If it's a separate port, this ServiceMonitor will scrape voiceworks's app router and either 404 (Prom marks the target down) or, worse, return HTML that breaks the parser. If it's the same port, leaving a comment in values.yaml to that effect would save the next operator a debugging session.

[jkroll-deepgram]

The chart mounts this Secret at /etc/voiceworks/tls and references tls.crt / tls.key / ca.crt from config.toml. Operators bringing their own Secret need to know which keys to put in it. Suggest tightening this row to something like:

Reference an existing kubernetes.io/tls Secret. Must contain keys tls.crt, tls.key, and (when clientCaBundle is set) ca.crt.

Same note belongs on secrets.existingSecret (line 197) — that one needs the keys named by license.apiKeyExistingSecretKey and selfHosted.apiKeyExistingSecretKey (default DEEPGRAM_API_KEY and VW_API_KEY).