From 451e1ad395ef8078932c3b6779cf8903f7eec605 Mon Sep 17 00:00:00 2001 From: Alan Clucas Date: Fri, 14 Apr 2023 14:47:53 +0100 Subject: [PATCH] docs: Improve documentation on lifecycle hooks (#10911) Signed-off-by: Alan Clucas --- docs/lifecyclehook.md | 16 ++++++++-------- examples/life-cycle-hooks-tmpl-level.yaml | 8 ++++---- examples/life-cycle-hooks-wf-level.yaml | 2 +- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/lifecyclehook.md b/docs/lifecyclehook.md index 2da5f0f93111..5332089d3bc8 100644 --- a/docs/lifecyclehook.md +++ b/docs/lifecyclehook.md @@ -4,28 +4,28 @@ ## Introduction -A [`LifecycleHook`](https://argoproj.github.io/argo-workflows/fields/#lifecyclehook) triggers an action based on a conditional expression. It is configured either at the workflow-level or template-level, for instance as a function of the `workflow.status` or `steps.status`, respectively. A `LifecycleHook` executes during execution time and executes once. +A [`LifecycleHook`](https://argoproj.github.io/argo-workflows/fields/#lifecyclehook) triggers an action based on a conditional expression or on completion of a step or template. It is configured either at the workflow-level or template-level, for instance as a function of the `workflow.status` or `steps.status`, respectively. A `LifecycleHook` executes during execution time and executes once. It will execute in parallel to its step or template once the expression is satisfied. -In other words, a `LifecycleHook` functions like an [exit handler](https://github.com/argoproj/argo-workflows/blob/master/examples/exit-handlers.yaml) with a conditional expression. +In other words, a `LifecycleHook` functions like an [exit handler](https://github.com/argoproj/argo-workflows/blob/master/examples/exit-handlers.yaml) with a conditional expression. You must not name a `LifecycleHook` `exit` or it becomes an exit handler, otherwise the hook name has no relevance. -**Workflow-level `LifecycleHook`**: Executes the workflow when a configured expression is met. +**Workflow-level `LifecycleHook`**: Executes the template when a configured expression is met during the workflow. -- [Workflow-level Lifecycle-Hook example](https://github.com/argoproj/argo-workflows/blob/45730a9cdeb588d0e52b1ac87b6e0ca391a95a81/examples/life-cycle-hooks-wf-level.yaml) +- [Workflow-level Lifecycle-Hook example](https://github.com/argoproj/argo-workflows/blob/master/examples/life-cycle-hooks-wf-level.yaml) -**Template-level Lifecycle-Hook**: Executes the template when a configured expression is met. +**Template-level `Lifecycle-Hook`**: Executes the template when a configured expression is met during the step in which it is defined. -- [Template-level Lifecycle-Hook example](https://github.com/argoproj/argo-workflows/blob/45730a9cdeb588d0e52b1ac87b6e0ca391a95a81/examples/life-cycle-hooks-tmpl-level.yaml) +- [Template-level Lifecycle-Hook example](https://github.com/argoproj/argo-workflows/blob/master/examples/life-cycle-hooks-tmpl-level.yaml) ## Supported conditions -- [Exit handler variables](https://github.com/argoproj/argo-workflows/blob/ebd3677c7a9c973b22fa81ef3b409404a38ec331/docs/variables.md#exit-handler): `workflow.status` and `workflow.failures` +- [Exit handler variables](https://github.com/argoproj/argo-workflows/blob/master/docs/variables.md#exit-handler): `workflow.status` and `workflow.failures` - [`template`](https://argoproj.github.io/argo-workflows/fields/#template) - [`templateRef`](https://argoproj.github.io/argo-workflows/fields/#templateref) - [`arguments`](https://github.com/argoproj/argo-workflows/blob/master/examples/conditionals.yaml) ## Unsupported conditions -- [`outputs`](https://argoproj.github.io/argo-workflows/fields/#outputs) are not usable since `LifecycleHook` executes during execution time and `outputs` are not produced until the step is completed. +- [`outputs`](https://argoproj.github.io/argo-workflows/fields/#outputs) are not usable since `LifecycleHook` executes during execution time and `outputs` are not produced until the step is completed. You can use outputs from previous steps, just not the one you're hooking into. If you'd like to use outputs create an exit handler instead - all the status variable are available there so you can still conditionally decide what to do. ## Notification use case diff --git a/examples/life-cycle-hooks-tmpl-level.yaml b/examples/life-cycle-hooks-tmpl-level.yaml index 58bdbeb8c7ba..91e51cb5c596 100644 --- a/examples/life-cycle-hooks-tmpl-level.yaml +++ b/examples/life-cycle-hooks-tmpl-level.yaml @@ -9,7 +9,7 @@ steps: - - name: step-1 hooks: - exit: + running: # Name of hook does not matter # Expr will not support `-` on variable name. Variable should wrap with `[]` expression: steps["step-1"].status == "Running" template: http @@ -19,20 +19,20 @@ template: echo - - name: step2 hooks: - exit: + running: expression: steps.step2.status == "Running" template: http success: expression: steps.step2.status == "Succeeded" template: http template: echo - + - name: echo container: image: alpine:3.6 command: [sh, -c] args: ["echo \"it was heads\""] - + - name: http http: # url: http://dummy.restapiexample.com/api/v1/employees diff --git a/examples/life-cycle-hooks-wf-level.yaml b/examples/life-cycle-hooks-wf-level.yaml index 9ff62de7b2c1..5865589a87f7 100644 --- a/examples/life-cycle-hooks-wf-level.yaml +++ b/examples/life-cycle-hooks-wf-level.yaml @@ -5,7 +5,7 @@ metadata: spec: entrypoint: main hooks: - exit: + exit: # Exit handler template: http running: expression: workflow.status == "Running"