docs: synchronization and paralellism docs improvements (#13393)

Signed-off-by: Alan Clucas <[email protected]> Signed-off-by: Anton Gilgur <[email protected]> Co-authored-by: Anton Gilgur <[email protected]>
argoproj · Sep 3, 2024 · ff2b2dd · ff2b2dd
1 parent c29c630
commit ff2b2dd
Show file tree

Hide file tree

Showing 4 changed files with 92 additions and 21 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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