compose-file: document additional changes in the 3.8 schema (#10980)

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2020-06-12 11:51:35 +02:00 · 2020-06-12 11:51:35 +02:00 · 36e483169d
parent 93f28522ab
commit 36e483169d
2 changed files with 72 additions and 36 deletions
--- a/compose/compose-file/compose-versioning.md
+++ b/compose/compose-file/compose-versioning.md
@ -375,6 +375,23 @@ Introduces the following additional parameters:
 - Support for extension fields at the root of service, network, volume, secret
  and config definitions

+### Version 3.8
+
+An upgrade of [version 3](#version-3) that introduces new parameters. It is
+only available with Docker Engine version **19.03.0** and higher.
+
+Introduces the following additional parameters:
+
+- [`max_replicas_per_node`](index.md#max_replicas_per_node) in placement
+  configurations
+- `template_driver` option for [config](index.md#configs-configuration-reference)
+   and [secret](index.md#secrets-configuration-reference) configurations. This
+   option is only supported when deploying swarm services using
+   `docker stack deploy`.
+- `driver` and `driver_opts` option for [secret](index.md#secrets-configuration-reference)
+   configurations. This option is only supported when deploying swarm services
+   using `docker stack deploy`.
+
 ## Upgrading

 ### Version 2.x to 3.x
--- a/compose/compose-file/index.md
+++ b/compose/compose-file/index.md
@ -59,6 +59,7 @@ services:
      - backend
    deploy:
      placement:
+        max_replicas_per_node: 1
        constraints:
          - "node.role==manager"

@ -672,6 +673,8 @@ services:
    image: redis:alpine
    deploy:
      replicas: 6
+      placement:
+        max_replicas_per_node: 1
      update_config:
        parallelism: 2
        delay: 10s
@ -791,8 +794,9 @@ services:

 Specify placement of constraints and preferences. See the docker service create
 documentation for a full description of the syntax and available types of
-[constraints](../../engine/reference/commandline/service_create.md#specify-service-constraints---constraint)
-and [preferences](../../engine/reference/commandline/service_create.md#specify-service-placement-preferences---placement-pref).
+[constraints](../../engine/reference/commandline/service_create.md#specify-service-constraints---constraint),
+[preferences](../../engine/reference/commandline/service_create.md#specify-service-placement-preferences---placement-pref),
+and [specifying the maximum replicas per node](../../engine/reference/commandline/service_create.md#specify-maximum-replicas-per-node---replicas-max-per-node)

 ```yaml
 version: "{{ site.compose_file_v3 }}"
@ -808,6 +812,31 @@ services:
          - spread: node.labels.zone
 ```

+#### max_replicas_per_node
+
+> Added in [version 3.8](compose-versioning.md#version-38) file format.
+
+If the service is `replicated` (which is the default), [limit the number of replicas](../../engine/reference/commandline/service_create.md#specify-maximum-replicas-per-node---replicas-max-per-node)
+that can run on a node at any time.
+
+When there are more tasks requested than running nodes, an error
+`no suitable node (max replicas per node limit exceed)` is raised.
+
+```yaml
+version: "{{ site.compose_file_v3 }}"
+services:
+  worker:
+    image: dockersamples/examplevotingapp_worker
+    networks:
+      - frontend
+      - backend
+    deploy:
+      mode: replicated
+      replicas: 6
+      placement:
+        max_replicas_per_node: 1
+```
+
 #### replicas

 If the service is `replicated` (which is the default), specify the number of
@ -826,30 +855,6 @@ services:
      replicas: 6
 ```

-#### max_replicas_per_node
-
-If the service is `replicated` (which is the default), [limit the number of replicas](/engine/reference/commandline/service_create.md#specify-maximum-replicas-per-node---replicas-max-per-node)
-that can run on an node at any time.
-
-> **[Version 3.8](compose-versioning.md#version-3) and above.**
-
-When there are more tasks requested than running nodes, an error `no suitable node (max replicas per node limit exceed)` is raised.
-
-```yaml
-version: "{{ site.compose_file_v3 }}"
-services:
-  worker:
-    image: dockersamples/examplevotingapp_worker
-    networks:
-      - frontend
-      - backend
-    deploy:
-      mode: replicated
-      replicas: 6
-      placement:
-        max_replicas_per_node: 1
-```
-
 #### resources

 Configures resource constraints.
@ -2621,8 +2626,8 @@ networks:
 ## configs configuration reference

 The top-level `configs` declaration defines or references
-[configs](../../engine/swarm/configs.md) that can be granted to the services in this
-stack. The source of the config is either `file` or `external`.
+[configs](../../engine/swarm/configs.md) that can be granted to the services in
+this stack. The source of the config is either `file` or `external`.

 - `file`: The config is created with the contents of the file at the specified
  path.
@ -2630,9 +2635,18 @@ stack. The source of the config is either `file` or `external`.
  created. Docker does not attempt to create it, and if it does not exist, a
  `config not found` error occurs.
 - `name`: The name of the config object in Docker. This field can be used to
-   reference configs that contain special characters. The name is used as is
-   and will **not** be scoped with the stack name. Introduced in version 3.5
-   file format.
+  reference configs that contain special characters. The name is used as is
+  and will **not** be scoped with the stack name. Introduced in version 3.5
+  file format.
+- `driver` and `driver_opts`: The name of a custom secret driver, and driver-specific
+  options passed as key/value pairs. Introduced in version 3.8 file format, and
+  only supported when using `docker stack`.
+- `template_driver`: The name of the templating driver to use, which controls
+  whether and how to evaluate the secret payload as a template. If no driver
+  is set, no templating is used. The only driver currently supported is `golang`,
+  which uses a `golang`. Introduced in version 3.8 file format, and only supported
+  when using `docker stack`. Refer to [use a templated config](../../engine/swarm/configs.md#example-use-a-templated-config)
+  for a examples of templated configs.

 In this example, `my_first_config` is created (as
 `<stack_name>_my_first_config)`when the stack is deployed,
@ -2668,8 +2682,8 @@ stack.
 ## secrets configuration reference

 The top-level `secrets` declaration defines or references
-[secrets](../../engine/swarm/secrets.md) that can be granted to the services in this
-stack. The source of the secret is either `file` or `external`.
+[secrets](../../engine/swarm/secrets.md) that can be granted to the services in
+this stack. The source of the secret is either `file` or `external`.

 - `file`: The secret is created with the contents of the file at the specified
  path.
@ -2677,9 +2691,14 @@ stack. The source of the secret is either `file` or `external`.
  created. Docker does not attempt to create it, and if it does not exist, a
  `secret not found` error occurs.
 - `name`: The name of the secret object in Docker. This field can be used to
-   reference secrets that contain special characters. The name is used as is
-   and will **not** be scoped with the stack name. Introduced in version 3.5
-   file format.
+  reference secrets that contain special characters. The name is used as is
+  and will **not** be scoped with the stack name. Introduced in version 3.5
+  file format.
+- `template_driver`: The name of the templating driver to use, which controls
+  whether and how to evaluate the secret payload as a template. If no driver
+  is set, no templating is used. The only driver currently supported is `golang`,
+  which uses a `golang`. Introduced in version 3.8 file format, and only
+  supported when using `docker stack`.

 In this example, `my_first_secret` is created as
 `<stack_name>_my_first_secret `when the stack is deployed,