Helm chart anatomy¶

Status: Current | Last reviewed: 2026-06-12

The umbrella chart + per-service subcharts that power every TrueServe deploy.

The umbrella¶

charts/trueserve-stack is a Helm umbrella that depends on every per-service chart. Deploys go through it; per-service charts are not deployed individually in production.

Values layering¶

values.yaml is the base; environment overrides layer on top.

File	Purpose
`values.yaml`	Base defaults
`values-cloud-gcp.yaml`	Sentinel and customer GKE
`values-cloud-aws.yaml`	KMS/common AWS overlays
`values-aws.yaml`	Customer EKS
`values-azure.yaml`	Customer AKS
`values-kind.yaml`	Local Kind validation
`values-kind-local.yaml`	Local Kind dev mode (host-mount sources)
`values-kind-minimal.yaml`	Smallest-footprint Kind for chart smoke tests
`values-gcp-dev-orch.yaml`	GCP dev-tier orchestrator subset
`values-branch-*.yaml`	Branch-specific overlays for preview deploys

Pick one environment file. Helm resolves it on top of values.yaml:

helm upgrade --install trueserve charts/trueserve-stack \
  -f charts/trueserve-stack/values-aws.yaml \
  --namespace trueserve --create-namespace

Subcharts¶

Every service listed in 03-services has a corresponding subchart. The full list is in charts/. Each subchart owns its Deployment, Service, optional Ingress, and (where applicable) PDB / HPA / NetworkPolicy.

Type	Examples
Application services	`ai-manager`, `ai-orchestrator`, `agent-host`, `async-agent`, …
Infrastructure services	`status-page`, `event-publisher`, `code-executor`, `config-sync-service`
Data layer	`postgres`, `pgbouncer`, `redis`, `rabbitmq`, `neo4j`
Media stack	`asterisk`, `kamailio`, `janus`, `rtpengine`, `coturn`, `media-proxy`
Observability	`otel-collector`
Optional	`livekit`, `moshi`, `humana-concierge-api`, `pagerduty-portal`, `carrier-posture`

Chart-level conventions¶

Image tags read from <service>.image.tag and default to latest only in dev. Production overlays pin SHAs.
Replicas read from <service>.replicas.
Per-service env reads from <service>.env (a list of key/value pairs) or <service>.envFrom (a list of secret/configmap refs).
A service that holds public traffic exposes its ingress under <service>.ingress.hosts.
Optional mesh transport encryption lives under global.security.transportEncryption. Base/local values leave it off; cloud values enable Istio strict mTLS and set meshSidecarInjection: true on agent/workflow/data pods so the global injectSidecar toggle controls pod injection.

Transport encryption values¶

global:
  security:
    transportEncryption:
      enabled: true
      provider: istio
      mode: strict      # strict | permissive
      injectSidecar: true
      authorizationPolicy:
        enabled: false  # scaffold for future workload identity policy

When enabled with provider: istio, the umbrella chart renders a namespace-scoped PeerAuthentication. The chart does not render or own external KMS Gateway resources; those continue to be managed by the KMS gateway layer.

Sidecar injection is a two-part opt-in: the cluster overlay enables global.security.transportEncryption.injectSidecar, and each workload that should join the mesh sets <service>.meshSidecarInjection: true. Existing <service>.podAnnotations still render normally, and an explicit podAnnotations.sidecar.istio.io/inject value can override the generated annotation for a single workload.

Toggling infra in vs out¶

Every infra subchart has an enabled flag. Set false to use a managed equivalent. See cloud-managed-swap.md for the swap matrix.

postgres:
  enabled: false  # using managed RDS
redis:
  enabled: false  # using ElastiCache
minio:
  enabled: false  # using S3

Chart dependencies¶

Chart.lock pins subchart versions. Update with:

helm dependency update charts/trueserve-stack

Pre-commit lint¶

A pre-commit hook at scripts/hooks/ lints the chart on every commit. Run manually:

helm lint charts/trueserve-stack
helm template trueserve charts/trueserve-stack \
  -f charts/trueserve-stack/values-kind.yaml >/tmp/render.yaml