Synchronization

v2.10 and after

You can limit the parallel execution of workflows or templates:

• 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:

apiVersion: v1
kind: ConfigMap
metadata:
 name: my-config
data:
  workflow: "1"  # Only one workflow can run at given time in particular namespace
  template: "2"  # Two instances of template can run at a given time in particular namespace

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 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:

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: synchronization-wf-level-
spec:
  entrypoint: hello-world
  synchronization:
    semaphore:
      configMapKeyRef:
        name: my-config
        key: workflow
  templates:
  - name: hello-world
    container:
      image: busybox
      command: [echo]
      args: ["hello world"]

Using a mutex is equivalent to a limit "1" semaphore:

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: synchronization-wf-level-
spec:
  entrypoint: hello-world
  synchronization:
    mutex:
      name: workflow
  templates:
  - name: hello-world
    container:
      image: busybox
      command: [echo]
      args: ["hello world"]

Template-level Synchronization

You can limit parallel execution of templates by using the same synchronization reference.

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:

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: synchronization-tmpl-level-
spec:
  entrypoint: synchronization-tmpl-level-example
  templates:
  - name: synchronization-tmpl-level-example
    steps:
    - - name: synchronization-acquire-lock
        template: acquire-lock
        arguments:
          parameters:
          - name: seconds
            value: "{{item}}"
        withParam: '["1","2","3","4","5"]'

  - name: acquire-lock
    synchronization:
      semaphore:
        configMapKeyRef:
          name: my-config
          key: template
    container:
      image: alpine:latest
      command: [sh, -c]
      args: ["sleep 10; echo acquired lock"]

Using a mutex will limit to a single concurrent execution of the template:

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: synchronization-tmpl-level-
spec:
  entrypoint: synchronization-tmpl-level-example
  templates:
  - name: synchronization-tmpl-level-example
    steps:
    - - name: synchronization-acquire-lock
        template: acquire-lock
        arguments:
          parameters:
          - name: seconds
            value: "{{item}}"
        withParam: '["1","2","3","4","5"]'

  - name: acquire-lock
    synchronization:
      mutex:
        name: template
    container:
      image: alpine:latest
      command: [sh, -c]
      args: ["sleep 10; echo acquired lock"]

Examples:

1. Workflow level semaphore
2. Workflow level mutex
3. Step level semaphore
4. Step level mutex

Queuing

When a workflow cannot acquire a lock it will be placed into a ordered queue.

You can set a 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 restricts the parallelism of a loop
2. parallelism-nested.yaml restricts the parallelism of a nested loop
3. parallelism-nested-dag.yaml restricts the number of dag tasks that can be run at any one time
4. parallelism-nested-workflow.yaml shows how parallelism is inherited by children
5. parallelism-template-limit.yaml shows how parallelism of looped templates is also restricted

Other Parallelism support

You can also restrict parallelism at the Controller-level.

---

Have a question?

Search on GitHub Discussions and Slack.