docs: add missing deploy modes for compose file reference

[eznix86]

Description

Noticed that on the source code we had two more modes:
https://github.com/moby/swarmkit/blob/e8ecf83ee08e14a05e28992dc304576079d403c7/api/specs.proto#L106
https://github.com/moby/moby/blob/9633556bef3eb20dfe888903660c3df89a73605b/daemon/cluster/convert/service.go#L142

Related issues or tickets

Reviews

• Technical review
• Editorial review
• Product review

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	af7deb8
🔍 Latest deploy log	https://app.netlify.com/sites/docsdocker/deploys/67588d609bd854000814b72b
😎 Deploy Preview	https://deploy-preview-21606--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[melutovich]

What you've done is better than not having them (assuming they are meant to be permanently supposed and are not just temporary supported).
"A job that runs a specified number of tasks with controlled parallelism", since it is called a "job" is it on each replica supposed to be run once similar to the global-job ?

[eznix86]

What you've done is better than not having them (assuming they are meant to be permanently supposed and are not just temporary supported). "A job that runs a specified number of tasks with controlled parallelism", since it is called a "job" is it on each replica supposed to be run once similar to the global-job ?

From what I understand, is that global-job run on each node, basically the N amount of job will be equivalent to the amount of nodes, comapred to a replicated-job, run N amount of job of replicated, and i think placement dictate the replication behaviour, also I saw the CLI has more options --max-concurrent which controls how much tasks can run at a time.

Also I think i overlooked the yaml spec, some options are not supported on the the yaml.

the CLI side has documented it, i believe it should be documented like this

### Mode

`mode` defines the replication model used to run a service or job. Options include:

1. **`global`**: Ensures exactly one tasks runs per physical node.
2. **`replicated`**: Runs a specified number of tasks across nodes (default).
3. **`replicated-job`**: Executes a defined number of tasks with a finite end state. Tasks launch simultaneously by default.
   - 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 finite end state. 
   - Automatically runs on new nodes as they are added.

````yml
services:
  frontend:
    image: example/webapp
    deploy:
      mode: global

  batch-job:
    image: example/processor
    deploy:
      mode: replicated-job
      replicas: 5

  maintenance:
    image: example/updater
    deploy:
      mode: global-job
```


**Note**: 
- Job modes (`replicated-job` and `global-job`) are designed for tasks with a clear completion state. 
- 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.

Is it clearer for you ?

[melutovich]

It is clearer
a)however I wonder if for the global and replicated modes if they should now indicate they are long running and run until stopped (or perhaps like 'Ensures exactly one tasks continuously runs per physical node')
b)also maybe like 'finite completion** end state'
and add to the notes ** completion defined by returning 0 and exiting
c)as the cli documentation is still more verbose, perhaps a link in the notes to them?

[eznix86]

Good idea,

What do you think we settle with this:

### mode

`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 with 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:
  frontend:
    image: example/webapp
    deploy:
      mode: global

  batch-job:
    image: example/processor
    deploy:
      mode: replicated-job
      replicas: 5

  maintenance:
    image: example/updater
    deploy:
      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/#replicated-jobs).
```

[melutovich]

Almost consider:
a)'with a completion state (exits with code 0)' perhaps instead as 'until a completion state (exits with code 0)'
b)Perhaps in the notes to use the link to the previous section the Running as a Job section https://docs.docker.com/reference/cli/docker/service/create/#running-as-a-job

[eznix86]

I think its perfect, I will copy paste it once you are back, btw, thanks for the feedback :)

### mode

`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)'.
   - 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:
  frontend:
    image: example/webapp
    deploy:
      mode: global

  batch-job:
    image: example/processor
    deploy:
      mode: replicated-job
      replicas: 5

  maintenance:
    image: example/updater
    deploy:
      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)

[melutovich]

Looks great!