Skip to main content

ADR-008 — Helm Chart Organization (Option C: Hybrid)

Context​

Noxys ships multiple deployable services (noxys-api, noxys-console, noxys-presidio, noxys-extension backend, future noxys-eval, noxys-cli daemon). Each needs a Helm chart for k8s deployment (Scaleway prod, on-prem enterprise overlays). Three layout options were on the table:

  • A — Charts in noxys-infra (centralized): every chart lives in noxys-infra/charts/<service>/. Single repo, single PR review. Cons: slow iteration loop (any chart tweak = cross-repo PR), high coupling between app and infra teams (we are 1 dev so coupling is real friction).
  • B — Charts in app repos only: each repo owns its chart AND values. Cons: enterprise customer overlays scatter across N repos, hard to enumerate prod state, deploy automation needs N-way fanout.
  • C — Hybrid: chart in app repo, values in infra repo. Charts (Chart.yaml, templates/, values.yaml defaults) live in <app-repo>/deploy/helm/. Per-environment values (staging, prod, enterprise-X) live in noxys-infra/helm-values/<service>/.

Decision​

Adopt Option C.

Layout:

noxys-api/
  deploy/helm/
    Chart.yaml
    values.yaml          # safe defaults
    templates/
      deployment.yaml
      service.yaml
      ingress.yaml
      ...

noxys-infra/
  helm-values/
    noxys-api/
      staging.yaml
      prod.yaml
      enterprise-acme.yaml
    noxys-presidio/
      staging.yaml
      prod.yaml
    ...

CI/CD: deploy job in noxys-infra does helm upgrade --install <release> oci://ghcr.io/noxys-eu/<chart> -f helm-values/<service>/<env>.yaml. Charts published to GHCR OCI registry on app repo tag.

Rationale​

  1. Solo-dev velocity: chart edits ship with the code that needs them, no cross-repo PR ping-pong.
  2. Single source for env state: all prod.yaml live in one repo → easy diff before deploy, easy audit.
  3. Enterprise overlays: when a customer demands enterprise-acme overrides, only noxys-infra/helm-values/<service>/enterprise-acme.yaml changes — no app fork.
  4. Chart ownership stays with app team: future-proof when team grows past 1.
  5. OCI registry decouples: values repo references chart by version, no path coupling.

Consequences​

Positive:

  • App-repo PRs can include both code and chart changes atomically.
  • noxys-infra becomes the deploy control plane (values + OpenTofu + CI templates), not a chart bazaar.
  • Easy to enumerate "what runs in prod": ls noxys-infra/helm-values/*/prod.yaml.

Negative:

  • Two-repo workflow when bumping chart + adjusting prod values in same change. Mitigation: tag-based OCI release pins versions, infra PR refs chart version.
  • Enterprise customers wanting fork-able charts must fork the app repo (acceptable: they want code anyway).

Migration:

  • Existing roadmap items mentioning "Helm chart for X" → land in <X>/deploy/helm/.
  • Items mentioning "staging values for X" or "prod overlay for X" → land in noxys-infra/helm-values/<X>/.
  • Phase 3a roadmap re-classification (2026-04-28) flagged 0 items requiring split under strict rule; relaxed pass logged in /tmp/helm-splits-suggested.json for manual review.

Status​

Accepted. Effective immediately for noxys-presidio Helm chart (currently being scoped) and all future deployable services.