compose: merge latest spec changes

* tmpfs.mode: compose-spec/compose-spec#252
* build.tags: compose-spec/compose-spec#255
* env var secrets: compose-spec/compose-spec#257
* build.platforms: compose-spec/compose-spec#267

Signed-off-by: Milas Bowman <milas.bowman@docker.com>

compose/compose-file/build.md

@@ -272,6 +272,17 @@ build:
     - "com.example.label-with-empty-value"
 ```
 
+### no_cache
+
+`no_cache` disables image builder cache and enforce a full rebuild from source for all image layers. This only
+applies to layers declared in the Dockerfile, referenced images COULD be retrieved from local image store whenever tag
+has been updated on registry (see [pull](#pull)).
+
+### pull
+
+`pull` require the image builder to pull referenced images (`FROM` Dockerfile directive), even if those are already 
+available in the local image store.
+
 ### shm_size
 
 `shm_size` set the size of the shared memory (`/dev/shm` partition on Linux) allocated for building Docker image. Specify
@@ -299,6 +310,123 @@ build:
   target: prod
 ```
 
+### secrets
+`secrets` grants access to sensitive data defined by [secrets](secrets) on a per-service build basis. Two
+different syntax variants are supported: the short syntax and the long syntax.
+
+Compose implementations MUST report an error if the secret isn't defined in the
+[`secrets`](#secrets-top-level-element) section of this Compose file.
+
+#### Short syntax
+
+The short syntax variant only specifies the secret name. This grants the
+container access to the secret and mounts it as read-only to `/run/secrets/<secret_name>`
+within the container. The source name and destination mountpoint are both set
+to the secret name.
+
+The following example uses the short syntax to grant the build of the `frontend` service
+access to the `server-certificate` secret. The value of `server-certificate` is set
+to the contents of the file `./server.cert`.
+
+```yml
+services:
+  frontend:
+    build: 
+      context: .
+      secrets:
+        - server-certificate
+secrets:
+  server-certificate:
+    file: ./server.cert
+```
+
+#### Long syntax
+
+The long syntax provides more granularity in how the secret is created within
+the service's containers.
+
+- `source`: The name of the secret as it exists on the platform.
+- `target`: The name of the file to be mounted in `/run/secrets/` in the
+  service's task containers. Defaults to `source` if not specified.
+- `uid` and `gid`: The numeric UID or GID that owns the file within
+  `/run/secrets/` in the service's task containers. Default value is USER running container.
+- `mode`: The [permissions](http://permissions-calculator.org/) for the file to be mounted in `/run/secrets/`
+  in the service's task containers, in octal notation.
+  Default value is world-readable permissions (mode `0444`).
+  The writable bit MUST be ignored if set. The executable bit MAY be set.
+
+The following example sets the name of the `server-certificate` secret file to `server.crt`
+within the container, sets the mode to `0440` (group-readable) and sets the user and group
+to `103`. The value of `server-certificate` secret is provided by the platform through a lookup and
+the secret lifecycle not directly managed by the Compose implementation.
+
+```yml
+services:
+  frontend:
+    build:
+      context: .
+      secrets:
+        - source: server-certificate
+          target: server.cert
+          uid: "103"
+          gid: "103"
+          mode: 0440
+secrets:
+  server-certificate:
+    external: true
+```
+
+Service builds MAY be granted access to multiple secrets. Long and short syntax for secrets MAY be used in the
+same Compose file. Defining a secret in the top-level `secrets` MUST NOT imply granting any service build access to it.
+Such grant must be explicit within service specification as [secrets](spec.md#secrets) service element.
+
+### tags
+
+`tags` defines a list of tag mappings that MUST be associated to the build image. This list comes in addition of 
+the `image` [property defined in the service section](spec.md#image)
+
+```yml
+tags:
+  - "myimage:mytag"
+  - "registry/username/myrepos:my-other-tag"
+```
+
+### platforms
+
+`platforms` defines a list of target [platforms](spec.md#platform).
+
+```yml
+build:
+  context: "."
+  platforms:
+    - "linux/amd64"
+    - "linux/arm64"
+```
+
+When the `platforms` attribute is omitted, Compose implementations MUST include the service's platform
+in the list of the default build target platforms.
+
+Compose implementations SHOULD report an error in the following cases:
+* when the list contains multiple platforms but the implementation is incapable of storing multi-platform images
+* when the list contains an unsupported platform
+```yml
+build:
+  context: "."
+  platforms:
+    - "linux/amd64"
+    - "unsupported/unsupported"
+```
+* when the list is non-empty and does not contain the service's platform
+```yml
+services:
+  frontend:
+    platform: "linux/amd64"
+    build:
+      context: "."
+      platforms:
+        - "linux/arm64"
+```
+
 ## Implementations
 
 * [docker-compose](../../compose/index.md)

compose/compose-file/index.md

@@ -1876,6 +1876,7 @@ expressed in the short form.
   - `nocopy`: flag to disable copying of data from a container when a volume is created
 - `tmpfs`: configure additional tmpfs options
   - `size`: the size for the tmpfs mount in bytes (either numeric or as bytes unit)
+  - `mode`: the filemode for the tmpfs mount as Unix permission bits as an octal number
 - `consistency`: the consistency requirements of the mount. Available values are platform specific
 
 ### volumes_from
@@ -2061,6 +2062,9 @@ Compose implementations MUST set `com.docker.compose.project` and `com.docker.co
 If set to `true`, `external` specifies that this network’s lifecycle is maintained outside of that of the application.
 Compose Implementations SHOULD NOT attempt to create these networks, and raises an error if one doesn't exist.
 
+If `external` is set to `true` and network configuration has other but `name` attributes set, considering resource is
+not managed by compose lifecycle, Compose Implementations SHOULD reject a Compose file as invalid.
+
 In the example below, `proxy` is the gateway to the outside world. Instead of attempting to create a network, Compose
 implementations SHOULD interrogate the platform for an existing network simply called `outside` and connect the
 `proxy` service's containers to it.
@@ -2159,6 +2163,10 @@ If set to `true`, `external` specifies that this volume already exist on the pla
 of that of the application. Compose implementations MUST NOT attempt to create these volumes, and MUST return an error if they
 do not exist.
 
+If `external` is set to `true` and volume configuration has other but `name` attributes set, considering resource is
+not managed by compose lifecycle, Compose Implementations SHOULD reject a Compose file as invalid.
+
+
 In the example below, instead of attempting to create a volume called
 `{project_name}_db-data`, Compose looks for an existing volume simply
 called `db-data` and mounts it into the `backend` service's containers.
@@ -2283,6 +2291,9 @@ configs:
     name: "${HTTP_CONFIG_KEY}"
 ```
 
+If `external` is set to `true` and secret configuration has other but `name` attributes set, considering resource is
+not managed by compose lifecycle, Compose Implementations SHOULD reject a Compose file as invalid.
+
 Compose file need to explicitly grant access to the configs to relevant services in the application.
 
 ## Secrets top-level element
@@ -2293,13 +2304,14 @@ The top-level `secrets` declaration defines or references sensitive data that ca
 application. 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.
+- `environment`: The secret is created with the value of an environment variable.
 - `external`: If set to true, specifies that this secret has already been created. Compose implementation does
   not attempt to create it, and if it does not exist, an 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 project name.
 
-In this example, `server-certificate` is created as `<project_name>_server-certificate` when the application is deployed,
+In this example, `server-certificate` secret is created as `<project_name>_server-certificate` when the application is deployed,
 by registering content of the `server.cert` as a platform secret.
 
 ```yml
@@ -2308,6 +2320,15 @@ secrets:
     file: ./server.cert
 ```
 
+In this example, `token` secret  is created as `<project_name>_token` when the application is deployed,
+by registering content of the `OAUTH_TOKEN` environment variable as a platform secret.
+
+```yml
+secrets:
+  token:
+    environment: "OAUTH_TOKEN"
+```
+
 Alternatively, `server-certificate` can be declared as external, doing so Compose implementation will lookup `server-certificate` to expose secret to relevant services.
 
 ```yml
@@ -2328,6 +2349,9 @@ secrets:
     name: "${CERTIFICATE_KEY}"
 ```
 
+If `external` is set to `true` and secret configuration has other but `name` attributes set, considering resource is
+not managed by compose lifecycle, Compose Implementations SHOULD reject a Compose file as invalid.
+
 Compose file need to explicitly grant access to the secrets to relevant services in the application.
 
 ## Fragments