From ff2b2ddf46c89eb14f1b0699843c14629ac1784c Mon Sep 17 00:00:00 2001 From: Alan Clucas Date: Tue, 3 Sep 2024 21:35:22 +0100 Subject: [PATCH] docs: synchronization and paralellism docs improvements (#13393) Signed-off-by: Alan Clucas Signed-off-by: Anton Gilgur <4970083+agilgur5@users.noreply.github.com> Co-authored-by: Anton Gilgur <4970083+agilgur5@users.noreply.github.com> --- .spelling | 1 + docs/parallelism.md | 43 ++++++++++++++++++++++++++ docs/synchronization.md | 68 ++++++++++++++++++++++++++++------------- mkdocs.yml | 1 + 4 files changed, 92 insertions(+), 21 deletions(-) create mode 100644 docs/parallelism.md diff --git a/.spelling b/.spelling index f7554995f5b5..8ac37516c84f 100644 --- a/.spelling +++ b/.spelling @@ -185,6 +185,7 @@ memoizing metadata minikube mutex +mutexes namespace namespaces natively diff --git a/docs/parallelism.md b/docs/parallelism.md new file mode 100644 index 000000000000..bae14e3c45fe --- /dev/null +++ b/docs/parallelism.md @@ -0,0 +1,43 @@ +# Limiting parallelism + +You can restrict the number of parallel workflow executions. + +## Controller-level + +You can limit the total number of parallel workflow executions in the [workflow controller ConfigMap](workflow-controller-configmap.yaml): + +```yaml +data: + parallelism: "10" +``` + +You can also limit the total number of parallel workflow executions in a single namespace: + +```yaml +data: + namespaceParallelism: "4" +``` + +!!! Note + Workflows that are executing but restricted from running more nodes due to other mechanisms will still count toward parallelism limits. + +### Priority + +You can set a `priority` on workflows: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Workflow +metadata: + generateName: priority- +spec: + priority: 3 + # ... +``` + +Workflows that have not started due to Controller-level parallelism will be queued: workflows with higher priority numbers will start before lower priority ones. +The default is `priority: 0`. + +## Synchronization + +You can also use [mutexes, semaphores, and parallelism](synchronization.md) to control the parallel execution of workflows and templates. diff --git a/docs/synchronization.md b/docs/synchronization.md index 74776d5c800e..480952cb0221 100644 --- a/docs/synchronization.md +++ b/docs/synchronization.md @@ -2,15 +2,15 @@ > v2.10 and after -## Introduction +You can limit the parallel execution of workflows or templates: -Synchronization enables users to limit the parallel execution of certain workflows or -templates within a workflow without having to restrict others. +- You can use mutexes to restrict workflows or templates to only having a single concurrent execution. +- You can use semaphores to restrict workflows or templates to a configured number of parallel executions. +- You can use parallelism to restrict concurrent tasks or steps within a single workflow. -Users can create multiple synchronization configurations in the `ConfigMap` that can be referred to -from a workflow or template within a workflow. Alternatively, users can -configure a mutex to prevent concurrent execution of templates or -workflows using the same mutex. +The term "locks" on this page means mutexes and semaphores. + +You can create multiple semaphore configurations in a `ConfigMap` that can be referred to from a workflow or template. For example: @@ -24,11 +24,15 @@ data: template: "2" # Two instances of template can run at a given time in particular namespace ``` -### Workflow-level Synchronization +!!! Warning + Each synchronization block may only refer to either a semaphore or a mutex. + If you specify both only the semaphore will be locked. + +## Workflow-level Synchronization -Workflow-level synchronization limits parallel execution of the workflow if workflows have the same synchronization reference. -In this example, Workflow refers to `workflow` synchronization key which is configured as limit 1, -so only one workflow instance will be executed at given time even multiple workflows created. +You can limit parallel execution of workflows by using the same synchronization reference. + +In this example the synchronization key `workflow` is configured as limit `"1"`, so only one workflow instance will execute at a time even if multiple workflows are created. Using a semaphore configured by a `ConfigMap`: @@ -52,7 +56,7 @@ spec: args: ["hello world"] ``` -Using a mutex: +Using a mutex is equivalent to a limit `"1"` semaphore: ```yaml apiVersion: argoproj.io/v1alpha1 @@ -72,11 +76,12 @@ spec: args: ["hello world"] ``` -### Template-level Synchronization +## Template-level Synchronization + +You can limit parallel execution of templates by using the same synchronization reference. -Template-level synchronization limits parallel execution of the template across workflows, if templates have the same synchronization reference. -In this example, `acquire-lock` template has synchronization reference of `template` key which is configured as limit 2, -so two instances of templates will be executed at a given time: even multiple steps/tasks within workflow or different workflows referring to the same template. +In this example the synchronization key `template` is configured as limit `"2"`, so a maximum of two instances of the `acquire-lock` template will execute at a time. +This applies even when multiple steps or tasks within a workflow or different workflows refer to the same template. Using a semaphore configured by a `ConfigMap`: @@ -110,7 +115,7 @@ spec: args: ["sleep 10; echo acquired lock"] ``` -Using a mutex: +Using a mutex will limit to a single concurrent execution of the template: ```yaml apiVersion: argoproj.io/v1alpha1 @@ -147,8 +152,29 @@ Examples: 1. [Step level semaphore](https://github.com/argoproj/argo-workflows/blob/main/examples/synchronization-tmpl-level.yaml) 1. [Step level mutex](https://github.com/argoproj/argo-workflows/blob/main/examples/synchronization-mutex-tmpl-level.yaml) -### Other Parallelism support +## Queuing + +When a workflow cannot acquire a lock it will be placed into a ordered queue. + +You can set a [`priority`](parallelism.md#priority) on workflows. +The queue is first ordered by priority: a higher priority number is placed before a lower priority number. +The queue is then ordered by `creationTimestamp`: older workflows are placed before newer workflows. + +Workflows can only acquire a lock if they are at the front of the queue for that lock. + +## Workflow-level parallelism + +You can use `parallelism` within a workflow or template to restrict the total concurrent executions of steps or tasks. +(Note that this only restricts concurrent executions within the same workflow.) + +Examples: + +1. [`parallelism-limit.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/parallelism-limit.yaml) restricts the parallelism of a [loop](walk-through/loops.md) +1. [`parallelism-nested.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/parallelism-nested.yaml) restricts the parallelism of a nested loop +1. [`parallelism-nested-dag.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/parallelism-nested-dag.yaml) restricts the number of dag tasks that can be run at any one time +1. [`parallelism-nested-workflow.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/parallelism-nested-workflow.yaml) shows how parallelism is inherited by children +1. [`parallelism-template-limit.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/parallelism-template-limit.yaml) shows how parallelism of looped templates is also restricted + +## Other Parallelism support -In addition to this synchronization, the workflow controller supports a parallelism setting that applies to all workflows -in the system (it is not granular to a class of workflows, or tasks withing them). Furthermore, there is a parallelism setting -at the workflow and template level, but this only restricts total concurrent executions of tasks within the same workflow. +You can also [restrict parallelism at the Controller-level](parallelism.md). diff --git a/mkdocs.yml b/mkdocs.yml index 3403c489f3d3..52e1dbb74f3b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -252,6 +252,7 @@ nav: - workflow-restrictions.md - sidecar-injection.md - service-account-secrets.md + - parallelism.md - Argo Server: - argo-server.md - argo-server-auth-mode.md