Argo CD / Automation, lifecycle, and trust / Lesson 9

Sync phases, waves, and hook side effects

Order dependent work without treating resource sequencing as a distributed transaction.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Explain phase and wave ordering under the documented baseline.
Review hook repetition, selective sync, cleanup, and failure evidence.

Order is a dependency tool with limits

Argo CD sync phases and waves can arrange resource operations within a sync. Phases distinguish lifecycle roles such as PreSync, Sync, PostSync, and failure handling, while wave annotations order work within the relevant phase. Resource kind and name participate in documented ordering too. Parcel might need a prerequisite resource before a dependent workload, but an ordered apply is not a proof that every external dependency is ready. Read the health and continuation conditions and avoid using arbitrary wave numbers as an undocumented dependency language.

A hook is executable release behavior

Hooks can run Kubernetes resources such as Jobs at selected lifecycle points. Their code, images, credentials, network access, retry behavior, and external effects belong to the release trust model. A PreSync check can fail before ordinary adoption; a PostSync validation can fail after resources changed. Neither makes the whole operation an atomic transaction. Do not place irreversible data changes into a hook without compatibility and repeatability design. This course creates no Job and executes no hook or migration.

Read hook and wave metadata as a fragment

The annotation fragment below declares a PreSync hook in wave minus one and a cleanup policy after success. It does not include a runnable resource spec, image, command, or credential. Real policy must decide whether deleting successful hook objects preserves enough evidence for later diagnosis. A fixed name and generated name also affect recreation under documented hook lifecycle behavior. BeforeHookCreation and other supported policies require deliberate use, not a blanket cleanup recipe copied into every release.

yaml A hook-lifecycle metadata fragment

metadata:
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/sync-wave: "-1"
    argocd.argoproj.io/hook-delete-policy: HookSucceeded

This is not a complete Kubernetes object and is never applied. No hook result, timing, cleanup, or database behavior is claimed. The annotations illustrate a review boundary only.

Model only the declared phase and wave keys

The complete local model below sorts three synthetic operations by a declared phase rank and numeric wave. It deliberately omits Argo CD kind and name tie-breaking, pruning order, health waiting, and controller behavior. The result illustrates one ordering idea without claiming an engine test. A real dependency graph must also account for failures, unavailable APIs, and resources that never become healthy. More ordering cannot repair an incorrect health check or make an unsafe business side effect reversible.

python A limited synthetic phase-and-wave sort

phase_rank = {"PreSync": 0, "Sync": 1, "PostSync": 2}
items = [("validation", "PostSync", 0), ("workload", "Sync", 1), ("prerequisite", "PreSync", -1)]
ordered = sorted(items, key=lambda x: (phase_rank[x[1]], x[2]))
print([x[0] for x in ordered])

Expected output

['prerequisite', 'workload', 'validation']

Only local tuples are sorted. This is not the complete Argo CD operation ordering algorithm and does not execute or validate Kubernetes resources.

Selective operations can change the contract

The release-3.1 documentation states that hooks do not run during selective sync. A reviewer must therefore know whether the chosen operation includes the validations or transitions expected by the release plan. Do not assume selecting one resource preserves the same lifecycle as a complete sync. Keep hook outputs and operation history under a retention contract, and inspect partial completion before retrying. A failed PostSync hook may require user-impact investigation while the application is already changed, rather than an assumption that no deployment occurred.

Common errors and fixes

A wave number is treated as proof of complete dependency readiness.

Why it happens: Apply ordering was confused with health and external availability.
How to fix it: Define bounded readiness and failure behavior for the actual dependency.
Prevent it next time: Review ordering and health contracts together.

A selective sync is expected to execute all release hooks.

Why it happens: The operation scope differs from the full lifecycle contract.
How to fix it: Review the documented selective-sync limitation before choosing the operation.
Prevent it next time: Record scope and required hook evidence in release decisions.

A repeated hook duplicates an external business action.

Why it happens: Hook rerun and partial-completion semantics were not designed.
How to fix it: Use a reviewed repeatable or compensating operation contract.
Prevent it next time: Track request identity, retained results, and recovery before enabling hooks.

Check your understanding

1. A PostSync validation fails after resources were applied. Does that imply the target is unchanged?

Show worked solution

No. The validation occurs after relevant adoption conditions, and resources may already differ. Preserve operation and resource evidence, investigate user impact, and choose compatible completion or recovery. A failed final check is not automatic rollback.

2. Why is the Python sorter not evidence that the shown hook succeeds on Argo CD?