Helm / Intermediate: authoring and lifecycle contracts / Lesson 12

Hooks, chart tests and side effects

Model lifecycle hooks and test resources as real workloads with ordering, cleanup and side-effect contracts rather than magic deployment transactions.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Explain hook annotations and relative ordering.
Design idempotent actions and evidence-preserving cleanup.
Separate chart tests from offline render assertions.

Treat hooks as workloads

Hooks are template-generated Kubernetes resources annotated for specific lifecycle points such as pre-upgrade or post-install. A Job hook still needs an image, scheduling capacity, permissions, input data and a meaningful completion condition. It can fail independently of ordinary chart resources. A pre-install hook cannot assume that a normal Service from the same release already exists, because its lifecycle position is earlier. Choose the hook only after drawing dependencies. For configuration validation that can happen offline, a local schema check is usually easier to reason about than provisioning a workload solely to discover a bad input.

Read hook metadata precisely

Hook weights are strings containing integers; lower weights run earlier within the relevant ordering. A deletion policy controls selected cleanup timing, such as removing a previous hook resource before creating another or deleting a successful one. It is not a complete retention and auditing policy. The first fragment shows annotations only, deliberately omitting a Job body so it cannot be mistaken for an executable migration. The proposed validation action has no external side effect. Real mutation hooks require a much stronger compatibility, retry and recovery design than these metadata fields provide.

yaml Hook annotation fragment

metadata:
  name: catalog-validate-input
  annotations:
    helm.sh/hook: pre-upgrade
    helm.sh/hook-weight: "-10"
    helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded

The name and action are synthetic. There is no Job specification, image or command, so this is metadata review only.

Design retry and cleanup together

An operation can be retried after a timeout or partial failure, so a hook must distinguish not started, completed and uncertain outcomes. Writing a migration marker after an irreversible mutation may still leave an ambiguity window. Application migrations often need transactions, version checks or other domain-specific safeguards that Helm cannot invent. Cleanup also affects evidence: deleting successful hooks saves clutter, while deleting failed hooks immediately can hide diagnostics. Hook resources are not managed like ordinary release resources, so an uninstall should not be assumed to remove every hook-created artifact or external object.

Separate test layers

A Helm chart test is a hook resource invoked for a release and generally judges a container’s successful exit. It runs in an environment and can exercise real dependencies, unlike a local render assertion. A port-open check is weaker than a semantic catalog response check, and either can pass while data authorization is wrong. The second example is a pure Python classifier for synthetic test outcomes; it is not a Helm test. It demonstrates that exit success and the expected payload must both be considered when defining a meaningful application assertion.

python Synthetic application assertion

cases = [(0, "catalog-ready"), (0, "wrong-page"), (1, "catalog-ready")]
for exit_code, body in cases:
    print(exit_code == 0 and body == "catalog-ready")

Expected output

True
False
False

The first case meets both conditions; the other cases fail. No HTTP request, container or cluster is used.

Record order and evidence

For each hook record its phase, prerequisites, expected duration, retry behavior, permissions, side effects and evidence destination. For each chart test state the user contract it checks and the dependencies it cannot isolate. Keep test images and commands reviewed like application code; a test is still executable software with network and credential access if granted. This course runs neither hooks nor chart tests and displays no fabricated cluster logs. Its safe classifier verifies only boolean decision logic. A complete operational test plan would need an explicitly authorized environment and application-specific cleanup.

Common errors and fixes

A pre-install hook waits for a normal release Service

Why it happens: The dependency is scheduled after the hook’s phase.
How to fix it: Redesign the phase or remove the cyclic dependency.
Prevent it next time: Draw lifecycle prerequisites before assigning annotations.

A retried migration applies the same mutation twice

Why it happens: The action lacked an application-aware idempotency contract.
How to fix it: Design transactional or version-checked migration behavior and assess uncertain outcomes.
Prevent it next time: Review retry windows and external side effects independently of Helm status.

A successful TCP check is treated as full application validation

Why it happens: Reachability replaced semantic response and authorization checks.
How to fix it: Define a synthetic application assertion with exact expected behavior.
Prevent it next time: State the scope and limitations of every chart test.

Check your understanding

1. Why should a failed hook sometimes be retained while a successful one is cleaned up?

Show worked solution

A failed resource can preserve the evidence needed to distinguish image, scheduling, permission and application failures. Successful resources may be removable after their required evidence is stored. Retention must still respect data sensitivity and operational policy. Deletion annotations express selected lifecycle behavior; they do not substitute for an explicit diagnostic retention plan.

2. A hook timeout occurs after an external mutation. Is retry automatically safe?