ADR-024: Helm as deployment mechanism

Category: development Provenance: human

Decision

Use Helm charts as the primary deployment mechanism for the operator and CRD resources. Plain manifests and Kustomize are not supported.

Rationale

Plain manifests allow no configuration - users get a default operator in a default namespace with no flexibility. Kustomize provides some flexibility but easily breaks when required parameters are not overridden, leading to invalid deployments. Helm provides proper configuration management with values.yaml, type validation, and defaults. Helm integrates well with GitOps tools (ArgoCD, Flux) through native Helm support. Helm charts can be properly versioned and published to registries, enabling version pinning and upgrades. Helm's templating catches configuration errors at render time, not deployment time.

Agent Instructions

Always provide Helm charts for deployable components. Do not create plain Kubernetes manifests or Kustomize overlays as alternatives. When users ask for deployment options, direct them to Helm charts. All configuration options must be exposed as Helm values with sensible defaults.

Rejected Alternatives

Plain Kubernetes manifests

No configuration options. Users stuck with hardcoded defaults for namespace, resources, images, etc.

Kustomize

Easy to miss required parameter overrides, resulting in broken deployments. Less GitOps tool support than Helm.