From af7deb80ffc8ee4f403d33a24586f86c6560bc7a Mon Sep 17 00:00:00 2001 From: Bruno Bernard Date: Tue, 10 Dec 2024 22:43:31 +0400 Subject: [PATCH 1/3] docs: add missing modes for compose file reference --- content/reference/compose-file/deploy.md | 27 +++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/content/reference/compose-file/deploy.md b/content/reference/compose-file/deploy.md index 11fd5e911cf..6599bbd0970 100644 --- a/content/reference/compose-file/deploy.md +++ b/content/reference/compose-file/deploy.md @@ -50,7 +50,11 @@ services: ### mode -`mode` defines the replication model used to run the service on the platform. Either `global`, exactly one container per physical node, or `replicated`, a specified number of containers. The default is `replicated`. +`mode` defines the replication model used to run the service on the platform. Either `global`, exactly one container per physical node, or `replicated`, a specified number of containers. The default is `replicated`. + +Two additional modes are available for jobs: +- `replicated-job`: A job that runs a specified number of tasks with controlled parallelism +- `global-job`: A job that runs once on each swarm node ```yml services: @@ -60,6 +64,27 @@ services: mode: global ``` +For job modes, additional parameters can be specified: + +```yml +services: + batch-job: + image: example/processor + deploy: + mode: replicated-job + replicas: 1 + max_concurrent: 2 # Maximum parallel job tasks + total_completions: 10 # Total number of times to run + + maintenance: + image: example/updater + deploy: + mode: global-job # Runs once on each node +``` + +Note: Job modes are designed for tasks that have a finite completion state, unlike services which run continuously. Once a job completes, its containers exit but the service remains in the swarm until removed. + + ### placement `placement` specifies constraints and preferences for the platform to select a physical node to run service containers. From 8c1066137d95e3c13df10de14c7ba9240bf4bd19 Mon Sep 17 00:00:00 2001 From: Bruno Bernard Date: Mon, 23 Dec 2024 21:48:03 +0400 Subject: [PATCH 2/3] docs: improve docs deploy mode --- content/reference/compose-file/deploy.md | 30 ++++++++++++------------ 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/content/reference/compose-file/deploy.md b/content/reference/compose-file/deploy.md index 6599bbd0970..db657970790 100644 --- a/content/reference/compose-file/deploy.md +++ b/content/reference/compose-file/deploy.md @@ -50,11 +50,15 @@ services: ### mode -`mode` defines the replication model used to run the service on the platform. Either `global`, exactly one container per physical node, or `replicated`, a specified number of containers. The default is `replicated`. +`mode` defines the replication model used to run a service or job. Options include: -Two additional modes are available for jobs: -- `replicated-job`: A job that runs a specified number of tasks with controlled parallelism -- `global-job`: A job that runs once on each swarm node +1. **`global`**: Ensures exactly one task continuously runs per physical node until stopped. +2. **`replicated`**: Continuously runs a specified number of tasks across nodes until stopped (default). +3. **`replicated-job`**: Executes a defined number of tasks until a completion state (exits with code 0)'. + - Total tasks are determined by `replicas`. + - Concurrency can be limited using the `max-concurrent` option (CLI only). +4. **`global-job`**: Executes one task per physical node with a completion state (exits with code 0). + - Automatically runs on new nodes as they are added. ```yml services: @@ -62,28 +66,24 @@ services: image: example/webapp deploy: mode: global -``` - -For job modes, additional parameters can be specified: -```yml -services: batch-job: image: example/processor deploy: mode: replicated-job - replicas: 1 - max_concurrent: 2 # Maximum parallel job tasks - total_completions: 10 # Total number of times to run + replicas: 5 maintenance: image: example/updater deploy: - mode: global-job # Runs once on each node + mode: global-job ``` -Note: Job modes are designed for tasks that have a finite completion state, unlike services which run continuously. Once a job completes, its containers exit but the service remains in the swarm until removed. - +**Note**: +- Job modes (`replicated-job` and `global-job`) are designed for tasks that complete and exit with code 0. +- Completed tasks remain until explicitly removed. +- Options like `max-concurrent` for controlling concurrency are supported only via the CLI and are not available in Compose YAML. +- For more detailed information about job options and behavior, see the [Docker CLI documentation](/reference/cli/docker/service/create/#running-as-a-job) ### placement From bba40a7bee2e1461376593673a216bc51edb7022 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Wed, 8 Jan 2025 08:46:55 +0000 Subject: [PATCH 3/3] Apply suggestions from code review --- content/reference/compose-file/deploy.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/content/reference/compose-file/deploy.md b/content/reference/compose-file/deploy.md index db657970790..d1bb19f57a2 100644 --- a/content/reference/compose-file/deploy.md +++ b/content/reference/compose-file/deploy.md @@ -52,12 +52,12 @@ services: `mode` defines the replication model used to run a service or job. Options include: -1. **`global`**: Ensures exactly one task continuously runs per physical node until stopped. -2. **`replicated`**: Continuously runs a specified number of tasks across nodes until stopped (default). -3. **`replicated-job`**: Executes a defined number of tasks until a completion state (exits with code 0)'. +- `global`: Ensures exactly one task continuously runs per physical node until stopped. +- `replicated`: Continuously runs a specified number of tasks across nodes until stopped (default). +- `replicated-job`: Executes a defined number of tasks until a completion state (exits with code 0)'. - Total tasks are determined by `replicas`. - Concurrency can be limited using the `max-concurrent` option (CLI only). -4. **`global-job`**: Executes one task per physical node with a completion state (exits with code 0). +- `global-job`: Executes one task per physical node with a completion state (exits with code 0). - Automatically runs on new nodes as they are added. ```yml @@ -79,11 +79,12 @@ services: mode: global-job ``` -**Note**: -- Job modes (`replicated-job` and `global-job`) are designed for tasks that complete and exit with code 0. -- Completed tasks remain until explicitly removed. -- Options like `max-concurrent` for controlling concurrency are supported only via the CLI and are not available in Compose YAML. -- For more detailed information about job options and behavior, see the [Docker CLI documentation](/reference/cli/docker/service/create/#running-as-a-job) +> [!NOTE] +> - Job modes (`replicated-job` and `global-job`) are designed for tasks that complete and exit with code 0. +> - Completed tasks remain until explicitly removed. +> - Options like `max-concurrent` for controlling concurrency are supported only via the CLI and are not available in Compose. + +For more detailed information about job options and behavior, see the [Docker CLI documentation](/reference/cli/docker/service/create.md#running-as-a-job) ### placement