Values Management

MATIH uses a layered values system with base defaults, environment overlays, and CD pipeline overrides. Understanding Helm's deep merge behavior is critical to avoiding value leakage between environments.

Values File Hierarchy

values.yaml              # Base defaults (production)
  |
  +-- values-dev.yaml    # Development overrides
  +-- values-prod.yaml   # Production-specific overrides
  +-- values-auth.yaml   # Authentication overlay
  +-- values-ai.yaml     # AI-focused deployment profile
  +-- values-minimal.yaml # Minimal deployment profile

The CD pipeline applies values in order:

helm upgrade matih-data-plane ./infrastructure/helm/matih-data-plane \
  -f values.yaml \
  -f values-dev.yaml \
  --set platform.imageTag="${IMAGE_TAG}" \
  --set platform.acrRegistry="${ACR_REGISTRY}" \
  --set platform.gitCommit="${GIT_COMMIT}"

Helm Deep Merge Behavior

Helm merges override files into base values using deep merge rules:

Type	Behavior	Risk
Scalar values	Override replaces base	Safe
Maps/objects	Keys merged recursively	Base keys leak through
Arrays	Override replaces base entirely	May lose base items

Deep Merge Pitfall

# values.yaml (base)
securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  runAsGroup: 1001
 
# values-dev.yaml (override)
securityContext:
  runAsUser: 0  # Override for dev
 
# MERGED RESULT (unexpected!)
securityContext:
  runAsNonRoot: true  # LEAKED from base
  runAsUser: 0        # From override
  runAsGroup: 1001    # LEAKED from base - conflict!

To avoid this, base values.yaml must define correct defaults for ALL keys.

Values Overlay Files

The data plane umbrella chart provides 185 values files across all its charts. Key overlays:

Data Plane Deployment Profiles

# values-minimal.yaml - Minimal deployment
query-engine:
  enabled: true
  replicaCount: 1
ai-service:
  enabled: true
  replicaCount: 1
catalog-service:
  enabled: true
  replicaCount: 1
# Everything else disabled
bi-service:
  enabled: false
ml-service:
  enabled: false

Base Chart Profile Files

File	Purpose
`values-hpa-profiles.yaml`	HPA profiles: api, worker, ai, stateful, frontend, data
`values-vpa-profiles.yaml`	VPA profiles: api, worker, ai, data, frontend, stateful
`values-pdb-profiles.yaml`	PDB profiles: critical, standard, worker
`values-cdn.yaml`	CDN annotation configuration

CD Pipeline Overrides

The CD pipeline sets deployment-specific values via --set:

--set platform.imageTag="20260131-031444-0512c3a"
--set platform.acrRegistry="matihlabsacr.azurecr.io"
--set platform.gitCommit="0512c3a..."
--set platform.gitBranch="main"
--set platform.deployedBy="cd-pipeline"
--set image.registry="matihlabsacr.azurecr.io"

These values are used in the platform-version-configmap.yaml template and propagated to service environment variables.

Secret Values

Secrets are never placed in values files. Instead, charts reference existing Kubernetes secrets:

# Correct: Reference existing secret
config:
  database:
    existingSecret: "ai-service-db-credentials"
    passwordKey: "password"
 
# Wrong: Hardcoded credential (forbidden)
config:
  database:
    password: "my-secret-password"

Secret creation is handled by:

External Secrets Operator - syncs from cloud key vaults to K8s secrets
dev-secrets.sh - creates development secrets via script
Terraform - generates passwords and stores in key vault

Umbrella Charts Chart Development