Designing Safe Helm Chart Hooks: Requirements, Minimal Pattern, and Operational Guardrails

Requirements

When a chart needs to perform an action that cannot be expressed as a static Kubernetes manifest—for example, running a database migration, validating configuration, or seeding secrets—the action must be executed at a well‑defined point in the release lifecycle. The hook must:

1. Run with the same namespace and service‑account privileges as the release (no extra cluster‑wide rights).
2. Be short‑lived; Helm expects the hook to complete quickly and then be cleaned up.
3. Not leave lingering resources that could interfere with later installs, upgrades, or uninstalls unless explicitly retained for debugging.
4. Receive configuration or secrets safely, preferably through Helm values or existing Kubernetes secrets, not baked into the hook image.

If any of these cannot be met, a hook is not the appropriate mechanism; consider a separate operator or a Helm plugin.

Minimal Suitable Design

The smallest hook that satisfies the requirements is a single Kubernetes Job (or Pod) that carries the annotation helm.sh/hook and optionally helm.sh/hook-weight for ordering. The Job runs a container that performs the task and exits with a zero status on success.

apiVersion: batch/v1
kind: Job
metadata:
  name: {{ .Release.Name }}-config-validator
  annotations:
    helm.sh/hook: pre-install,pre-upgrade
    helm.sh/hook-weight: "-5"
    helm.sh/hook-delete-policy: hook-succeeded
spec:
  template:
    metadata:
      labels:
        app.kubernetes.io/name: config-validator
    spec:
      restartPolicy: OnFailure
      serviceAccountName: {{ .Values.serviceAccountName | default "default" }}
      containers:
        - name: validator
          image: {{ .Values.validator.image }}:{{ .Values.validator.tag }}
          envFrom:
            - secretRef:
                name: {{ .Values.configSecret }}
          command: ["/bin/sh", "-c", "/usr/local/bin/validate-config.sh"]
  backoffLimit: 2

Key points:

• The hook runs at both pre-install and pre-upgrade (same manifest, multiple hook types).
• helm.sh/hook-weight ensures it runs before other hooks with higher weight values.
• helm.sh/hook-delete-policy: hook-succeeded tells Helm to delete the Job after it finishes successfully; if it fails, the Job remains for inspection.
• The container receives the secret via envFrom, avoiding hard‑coded credentials.

Trust and Data Boundaries

Hooks inherit the release’s service account and namespace. Therefore:

• Grant the service account only the permissions needed for the hook’s task (e.g., read a secret, create a ConfigMap). Avoid giving it cluster‑admin rights.
• Pass sensitive data through existing Kubernetes secrets or Helm values; never embed passwords or tokens in the hook image or manifest.
• If the hook needs to touch resources outside its namespace (e.g., a cluster‑wide CRD), re‑evaluate the design: a hook is not the right place for cross‑namespace actions.

Operational Checks

Before installing a chart with hooks, validate the rendered manifest:

1. helm lint ./mychart – catches syntax errors and missing annotations.
2. helm template --debug ./mychart > rendered.yaml – inspect the Job definition, verify annotations, weight, and delete policy.
3. kubectl apply -f rendered.yaml --dry-run=client – ensures the Job is syntactically valid for the target cluster.

After installation:

1. List hook jobs: kubectl get job -n <namespace> -l app.kubernetes.io/name=config-validator
2. Check completion: kubectl describe job <job-name> -n <namespace> – look for Succeeded: 1.
3. View logs for debugging: kubectl logs job/<job-name> -n <namespace>
4. Confirm cleanup per policy: if hook-succeeded is set, the Job should disappear after a successful run; if the hook failed, the Job remains.
5. Use helm get manifest <release> to see the hook as part of the release manifest.

Required permissions: the user running helm install must be able to create Jobs, Pods, and read the referenced secret in the target namespace. Running helm test (if you also annotate a hook with helm.sh/hook: test) requires the same permissions.

Failure Modes

If the hook container exits with a non‑zero code:

• Helm marks the release as failed and stops further processing (no subsequent hooks, no main resources).
• The hook resource is not** automatically removed unless the delete policy includes hook-failed. By default, only hook-succeeded triggers cleanup.
• A failed hook leaves the Job (and its Pods) in the cluster, which can clutter the namespace and obscure the real cause of the release failure.

Practical way to detect a failed hook:

1. After helm install returns an error, run helm status <release> – the status will show failed.
2. Check for hook Jobs: kubectl get job -n <namespace> -l app.kubernetes.io/name=config-validator
3. Describe the Job to see the container’s exit code and logs.

When the Design Must Change

Reconsider using a hook if any of the following conditions arise:

• The task needs to run for more than a few minutes (e.g., a long‑running data migration). Hooks are intended for short‑lived initialization; a long‑running Job blocks Helm’s cleanup and may exceed the default backoffLimit retry behavior.
• The operation requires cluster‑wide privileges (e.g., updating a namespace‑scoped RBAC that affects other tenants). In this case, a separate operator or a Helm plugin that runs with elevated rights outside the release’s service account is safer.
• You need to retain the hook resource for auditing beyond a single release cycle. While you can set helm.sh/hook-delete-policy: hook-succeeded,hook-failed, retaining hooks indefinitely deviates from their intended purpose and can cause naming collisions.
• The hook must coordinate with other releases (e.g., a global leader election). Hooks have no built‑in coordination mechanism; a sidecar or external controller is more appropriate.

In those scenarios, extract the logic into a dedicated controller, Operator, or a Helm plugin that runs independently of the release lifecycle, and keep the chart’s hooks limited to simple, short‑lived validation or configuration tasks.