mirror of https://github.com/docker/docs.git
compose: merge latest spec changes
* tmpfs.mode: https://github.com/compose-spec/compose-spec/pull/252 * build.tags: https://github.com/compose-spec/compose-spec/pull/255 * env var secrets: https://github.com/compose-spec/compose-spec/pull/257 * build.platforms: https://github.com/compose-spec/compose-spec/pull/267 Signed-off-by: Milas Bowman <milas.bowman@docker.com>
This commit is contained in:
Milas Bowman
parent
0cba5cac66
commit
3518db454f
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue