From 6a645b18bc86e176809ded5756fbd25f05507525 Mon Sep 17 00:00:00 2001 From: Alan Clucas Date: Wed, 28 Aug 2024 11:49:29 +0100 Subject: [PATCH] docs: update from code review Co-authored-by: Anton Gilgur <4970083+agilgur5@users.noreply.github.com> Signed-off-by: Alan Clucas --- docs/parallelism.md | 8 ++++---- docs/synchronization.md | 43 ++++++++++++++++++++++------------------- 2 files changed, 27 insertions(+), 24 deletions(-) diff --git a/docs/parallelism.md b/docs/parallelism.md index 854e25210c78..7b1b224b3ca0 100644 --- a/docs/parallelism.md +++ b/docs/parallelism.md @@ -1,17 +1,17 @@ # Limiting parallelism -You can restrict the number of simultaneous workflow executions. +You can restrict the number of parallel workflow executions. ## Controller level -You can limit the total number of workflows that can execute at any one time in the [workflow controller ConfigMap](./workflow-controller-configmap.yaml). +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 number of workflows that can execute in a single namespace. +You can also limit the total number of parallel workflow executions in a single namespace: ```yaml data: @@ -28,4 +28,4 @@ Workflows with a higher priority number that have not started due to controller ## Synchronization -You can use [mutexes, semaphores and parallelism](./synchronization.md) to control the parallel execution of sections of a workflow. +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 a6811376f7b5..759eff474c8a 100644 --- a/docs/synchronization.md +++ b/docs/synchronization.md @@ -2,13 +2,15 @@ > v2.10 and after -You can use synchronization to limit the parallel execution of workflows or templates. -You can use mutexes to restrict workflows or templates to only having a single concurrent section. -You can use semaphores to restrict workflows or templates to a configured number of parallel runs. -This documentation refers "locks" to mean mutexes and semaphores. -You can use parallelism to restrict concurrent tasks or steps within a single workflow. +You can limit the parallel execution of workflows or templates: -You can create multiple synchronization configurations in the `ConfigMap` that can be referred to from a workflow or template. +- 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. + +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: @@ -22,15 +24,16 @@ data: template: "2" # Two instances of template can run at a given time in particular namespace ``` -Each synchronization block may only refer to either a semaphore or a mutex. -If you specify both only the semaphore will be locked. +!!! 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 You can limit parallel execution of a workflow by using Workflow-level synchronization. If multiple workflows have the same synchronization reference they will be limited by that 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 if multiple workflows are created. +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`: @@ -54,7 +57,7 @@ spec: args: ["hello world"] ``` -Using a mutex achieves the same thing as a count `"1"` semaphore: +Using a mutex is equivalent to a limit `"1"` semaphore: ```yaml apiVersion: argoproj.io/v1alpha1 @@ -79,8 +82,8 @@ spec: You can limit parallel execution of a template by using Template-level synchronization. If templates have the same synchronization reference they will be limited by that synchronization reference, across all workflows. -In this example, `acquire-lock` template has synchronization reference of `template` key which is configured as limit `"2"` so a maximum of two instances of the `acquire-lock` template will be executed at a given time. -This applies even multiple steps or tasks within a workflow or different workflows refer 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`: @@ -114,7 +117,7 @@ spec: args: ["sleep 10; echo acquired lock"] ``` -Using a mutex will limit to a single execution of the template at any one time: +Using a mutex will limit to a single concurrent execution of the template: ```yaml apiVersion: argoproj.io/v1alpha1 @@ -153,22 +156,22 @@ Examples: ## Queuing -When a Workflow cannot take a lock it will be placed into a ordered queue. +When a Workflow cannot acquire a lock it will be placed into a ordered queue. Workflows can have a `priority` set in their specification. -The queue is first ordered by priority, with a higher priority number being placed before a lower priority number. -The queue is then ordered by `CreationTimestamp` of the Workflow; older Workflows will be ordered before newer 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 are only be allowed to take a lock if they are at the front of the queue for that lock. +Workflows can only acquire a lock if they are at the front of the queue for that lock. -## Workflow level parallelism +## Workflow-level parallelism You can restrict parallelism within a workflow using `parallelism` within a workflow or template. This only restricts total concurrent executions of steps or tasks 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-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 @@ -176,4 +179,4 @@ Examples: ## Other Parallelism support -You can also [restrict parallelism at the system level](parallelism.md). +You can also [restrict parallelism at the Controller-level](parallelism.md).