Helm migration hooks under GitOps

WHAT THIS TESTS Whether you know Helm's hook mechanism and understand that its imperative, lifecycle-driven behavior clashes with declarative continuous reconciliation.

A GOOD ANSWER COVERS In Helm you implement the migration as a Kubernetes Job templated in the chart and annotated with helm.sh/hook: pre-upgrade so it runs before the new application pods roll out during an upgrade. Use helm.sh/hook-weight to order multiple hooks and helm.sh/hook-delete-policy, for example before-hook-creation or hook-succeeded, to control cleanup of the Job between runs. The challenge under GitOps is that tools like Argo CD do not invoke Helm's release lifecycle; they render the chart to plain manifests and reconcile them continuously. Helm hooks are translated to the tool's own model, such as Argo CD sync hooks and PreSync phase via argocd.argoproj.io annotations, and a hook Job re-created on every sync can rerun the migration. Therefore migrations must be idempotent, ordering must be expressed in the tool's phases, and you must avoid drift from Jobs lingering or being pruned. Some teams move migrations out of hooks into an explicit, version-gated Job or a dedicated migration step.

COMMON WRONG ANSWERS Assuming Helm pre-upgrade hooks run transparently under Argo CD, ignoring idempotency so a re-sync corrupts data, or putting the migration in an init container where it runs per-pod rather than once.

LIKELY FOLLOW-UPS How do Argo CD sync phases map to Helm hooks? How do you guarantee a migration runs once? How do you handle failed migrations and rollback?

ONE CONCRETE EXAMPLE You add a Job with helm.sh/hook: pre-upgrade and hook-weight "-5" running the migration binary. Under plain Helm it executes before new pods. Under Argo CD, you instead annotate it as argocd.argoproj.io/hook: PreSync; because every sync may recreate it, the migration tool tracks applied versions in the database and exits early if already applied, keeping the operation idempotent.