Skip to content

docs: clarify Helm hook delete-policy semantics #26828

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Vedant-Mhatre wants to merge 3 commits into
base: master
Choose a base branch
from
+31 −24
Open

docs: clarify Helm hook delete-policy semantics #26828

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c5f4af4
docs: clarify Helm hook delete-policy semantics
Vedant-Mhatre Mar 14, 2026
73dff56
Merge branch 'master' into docs-hook-delete-policy-semantics
Vedant-Mhatre Mar 14, 2026
cf074d1
docs: align hook semantics tables
Vedant-Mhatre Mar 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions docs/user-guide/helm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -268,7 +268,7 @@ source:
Helm hooks are similar to [Argo CD hooks](resource_hooks.md). In Helm, a hook
is any normal Kubernetes resource annotated with the `helm.sh/hook` annotation.

Argo CD supports many (most?) Helm hooks by mapping the Helm annotations onto Argo CD's own hook annotations:
Argo CD supports many (most?) Helm hooks by mapping the Helm annotations onto Argo CD's own hook annotations. This is annotation compatibility, not a guarantee that hook lifecycle semantics are identical to Helm's:

| Helm Annotation | Notes |
| ------------------------------- |-----------------------------------------------------------------------------------------------|
Expand All @@ -283,7 +283,7 @@ Argo CD supports many (most?) Helm hooks by mapping the Helm annotations onto Ar
| `helm.sh/hook: post-rollback` | Not supported. Never used in Helm stable. |
| `helm.sh/hook: test-success` | Not supported. No equivalent in Argo CD. |
| `helm.sh/hook: test-failure` | Not supported. No equivalent in Argo CD. |
| `helm.sh/hook-delete-policy` | Supported. See also `argocd.argoproj.io/hook-delete-policy`). |
| `helm.sh/hook-delete-policy` | Supported. Cleanup still follows Argo CD sync semantics, which can differ from Helm's hook event lifecycle. See also `argocd.argoproj.io/hook-delete-policy`. |
Copy link
Member

@rumstead rumstead Mar 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we reformat both tables so they are aligned?

Copy link
Author

@Vedant-Mhatre Vedant-Mhatre Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated both tables to align the formatting in the latest commit.

| `helm.sh/hook-delete-timeout` | Not supported. Never used in Helm stable |
| `helm.sh/hook-weight` | Supported as equivalent to `argocd.argoproj.io/sync-wave`. |
| `helm.sh/resource-policy: keep` | Supported as equivalent to `argocd.argoproj.io/sync-options: Delete=false`. |
Expand All @@ -300,6 +300,11 @@ Unsupported hooks are ignored. In Argo CD, hooks are created by using `kubectl a
>
> Argo CD cannot know if it is running a first-time "install" or an "upgrade" - every operation is a "sync'. This means that, by default, apps that have `pre-install` and `pre-upgrade` will have those hooks run at the same time.

> [!NOTE]
> **Hook delete semantics differ from Helm**
>
> Helm hook annotations are mapped onto Argo CD hooks, but deletion policies are still evaluated using Argo CD sync phases and sync result semantics. This differs from Helm's per-hook-event lifecycle. In particular, passive resources such as `ServiceAccount` do not have a Kubernetes completion state like `Job` or `Workflow`, so `hook-succeeded`/`HookSucceeded` may be evaluated at a different point than you would observe with Helm.

### Hook Tips

* Make your hook idempotent.
Expand Down
4 changes: 3 additions & 1 deletion docs/user-guide/sync-waves.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,12 +44,14 @@ This can take the following values:

| Policy | Description |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `HookSucceeded` | The hook resource is deleted after the hook succeeded (e.g. Job/Workflow completed successfully). |
| `HookSucceeded` | The hook resource is deleted when the sync succeeds. For completion-based hooks such as `Job` or `Workflow`, this typically happens after the hook completes successfully. |
| `HookFailed` | The hook resource is deleted after the hook failed. |
| `BeforeHookCreation` | Any existing hook resource is deleted before the new one is created (since v1.3). It is meant to be used with `/metadata/name`. |

Note that if no deletion policy is specified, Argo CD will automatically assume `BeforeHookCreation` rules.

When Helm hook annotations are mapped onto Argo CD hooks, delete-policy evaluation still follows Argo CD sync phases and sync result semantics rather than Helm's per-hook-event lifecycle. For example, a `PreSync` resource mapped from Helm may remain available until later phases finish, and passive resources such as `ServiceAccount` do not have a completion state like `Job` or `Workflow`.

## PreDelete and PostDelete Hooks

### PreDelete Hooks
Expand Down
Loading