mirror of https://github.com/docker/docs.git
Add build and deploy docs
Signed-off-by: Usha Mandya <usha.mandya@docker.com>
This commit is contained in:
Usha Mandya
parent
1d5af4b2b9
commit
fc28f7560a
|
|
@ -1040,12 +1040,16 @@ reference:
|
|||
section:
|
||||
- path: /compose/compose-file/
|
||||
title: Compose Specification
|
||||
- path: /compose/compose-file/compose-versioning/
|
||||
title: About versions and upgrading
|
||||
- path: /compose/compose-file/build/
|
||||
title: Compose file build
|
||||
- path: /compose/compose-file/deploy/
|
||||
title: Compose file deploy
|
||||
- path: /compose/faq/
|
||||
title: Frequently asked questions
|
||||
- sectiontitle: Legacy versions
|
||||
section:
|
||||
- path: /compose/compose-file/compose-versioning/
|
||||
title: About versions and upgrading
|
||||
- path: /compose/compose-file/compose-file-v3/
|
||||
title: Version 3
|
||||
- path: /compose/compose-file/compose-file-v2/
|
||||
|
|
|
|||
|
|
@ -0,0 +1,305 @@
|
|||
---
|
||||
description: Compose file build reference
|
||||
keywords: fig, composition, compose, docker
|
||||
title: Compose file build reference
|
||||
toc_max: 4
|
||||
toc_min: 2
|
||||
---
|
||||
|
||||
Compose specification is a platform-neutral way to define multi-container applications. A Compose implementation
|
||||
focusing on development use-case to run application on local machine will obviously also support (re)building
|
||||
application from sources. The Compose Build specification allows to define the build process within a Compose file
|
||||
in a portable way.
|
||||
|
||||
## Definitions
|
||||
|
||||
Compose Specification is extended to support an OPTIONAL `build` subsection on services. This section define the
|
||||
build requirements for service container image. Only a subset of Compose file services MAY define such a Build
|
||||
subsection, others being created based on `Image` attribute. When a Build subsection is present for a service, it
|
||||
is *valid* for a Compose file to miss an `Image` attribute for corresponding service, as Compose implementation
|
||||
can build image from source.
|
||||
|
||||
Build can be either specified as a single string defining a context path, or as a detailed build definition.
|
||||
|
||||
In the former case, the whole path is used as a Docker context to execute a docker build, looking for a canonical
|
||||
`Dockerfile` at context root. Context path can be absolute or relative, and if so relative path MUST be resolved
|
||||
from Compose file parent folder. As an absolute path prevent the Compose file to be portable, Compose implementation
|
||||
SHOULD warn user accordingly.
|
||||
|
||||
In the later case, build arguments can be specified, including an alternate `Dockerfile` location. This one can be
|
||||
absolute or relative path. If Dockerfile path is relative, it MUST be resolved from context path. As an absolute
|
||||
path prevent the Compose file to be portable, Compose implementation SHOULD warn user if an absolute alternate
|
||||
Dockerfile path is used.
|
||||
|
||||
## Consistency with Image
|
||||
|
||||
When service definition do include both `Image` attribute and a `Build` section, Compose implementation can't
|
||||
guarantee a pulled image is strictly equivalent to building the same image from sources. Without any explicit
|
||||
user directives, Compose implementation with Build support MUST first try to pull Image, then build from source
|
||||
if image was not found on registry. Compose implementation MAY offer options to customize this behaviour by user
|
||||
request.
|
||||
|
||||
## Publishing built images
|
||||
|
||||
Compose implementation with Build support SHOULD offer an option to push built images to a registry. Doing so, it
|
||||
MUST NOT try to push service images without an `Image` attribute. Compose implementation SHOULD warn user about
|
||||
missing `Image` attribute which prevent image being pushed.
|
||||
|
||||
Compose implementation MAY offer a mechanism to compute an `Image` attribute for service when not explicitly
|
||||
declared in yaml file. In such a case, the resulting Compose configuration is considered to have a valid `Image`
|
||||
attribute, whenever the actual raw yaml file doesn't explicitly declare one.
|
||||
|
||||
## Illustrative sample
|
||||
|
||||
The following sample illustrates Compose specification concepts with a concrete sample application. The sample is non-normative.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
build: ./webapp
|
||||
|
||||
backend:
|
||||
image: awesome/database
|
||||
build:
|
||||
context: backend
|
||||
dockerfile: ../backend.Dockerfile
|
||||
|
||||
custom:
|
||||
build: ~/custom
|
||||
```
|
||||
|
||||
When used to build service images from source, such a Compose file will create three docker images:
|
||||
|
||||
* `awesome/webapp` docker image is build using `webapp` sub-directory within Compose file parent folder as docker build context. Lack of a `Dockerfile` within this folder will throw an error.
|
||||
* `awesome/database` docker image is build using `backend` sub-directory within Compose file parent folder. `backend.Dockerfile` file is used to define build steps, this file is searched relative to context path, which means for this sample `..` will resolve to Compose file parent folder, so `backend.Dockerfile` is a sibling file.
|
||||
* a docker image is build using `custom` directory within user's HOME as docker context. Compose implementation warn user about non-portable path used to build image.
|
||||
|
||||
On push, both `awesome/webapp` and `awesome/database` docker images are pushed to (default) registry. `custom` service image is skipped as no `Image` attribute is set and user is warned about this missing attribute.
|
||||
|
||||
## Build definition
|
||||
|
||||
The `build` element define configuration options that are applied by Compose implementations to build Docker image from source.
|
||||
`build` can be specified either as a string containing a path to the build context or a detailed structure:
|
||||
|
||||
```yml
|
||||
services:
|
||||
webapp:
|
||||
build: ./dir
|
||||
```
|
||||
|
||||
Using this string syntax, only the build context can be configured as a relative path to the Compose file's parent folder.
|
||||
This path MUST be a directory and contain a `Dockerfile`.
|
||||
|
||||
Alternatively `build` can be an object with fields defined as follow
|
||||
|
||||
### context (REQUIRED)
|
||||
|
||||
`context` defines either a path to a directory containing a Dockerfile, or a url to a git repository.
|
||||
|
||||
When the value supplied is a relative path, it MUST be interpreted as relative to the location of the Compose file.
|
||||
Compose implementations MUST warn user about absolute path used to define build context as those prevent Compose file
|
||||
for being portable.
|
||||
|
||||
```yml
|
||||
build:
|
||||
context: ./dir
|
||||
```
|
||||
|
||||
### dockerfile
|
||||
|
||||
`dockerfile` allows to set an alternate Dockerfile. A relative path MUST be resolved from the build context.
|
||||
Compose implementations MUST warn user about absolute path used to define Dockerfile as those prevent Compose file
|
||||
for being portable.
|
||||
|
||||
```yml
|
||||
build:
|
||||
context: .
|
||||
dockerfile: webapp.Dockerfile
|
||||
```
|
||||
|
||||
### args
|
||||
|
||||
`args` define build arguments, i.e. Dockerfile `ARG` values.
|
||||
|
||||
Using following Dockerfile:
|
||||
|
||||
```Dockerfile
|
||||
ARG GIT_COMMIT
|
||||
RUN echo "Based on commit: $GIT_COMMIT"
|
||||
```
|
||||
|
||||
`args` can be set in Compose file under the `build` key to define `GIT_COMMIT`. `args` can be set a mapping or a list:
|
||||
|
||||
```yml
|
||||
build:
|
||||
context: .
|
||||
args:
|
||||
GIT_COMMIT: cdc3b19
|
||||
```
|
||||
|
||||
```yml
|
||||
build:
|
||||
context: .
|
||||
args:
|
||||
- GIT_COMMIT=cdc3b19
|
||||
```
|
||||
|
||||
Value can be omitted when specifying a build argument, in which case its value at build time MUST be obtained by user interaction,
|
||||
otherwise build arg won't be set when building the Docker image.
|
||||
|
||||
```yml
|
||||
args:
|
||||
- GIT_COMMIT
|
||||
```
|
||||
|
||||
### ssh
|
||||
|
||||
`ssh` defines SSH authentications that the image builder SHOULD use during image build (e.g., cloning private repository)
|
||||
|
||||
`ssh` property syntax can be either:
|
||||
* `default` - let the builder connect to the ssh-agent.
|
||||
* `ID=path` - a key/value definition of an ID and the associated path. Can be either a [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) file, or path to ssh-agent socket
|
||||
|
||||
Simple `default` sample
|
||||
```yaml
|
||||
build:
|
||||
context: .
|
||||
ssh:
|
||||
- default # mount the default ssh agent
|
||||
```
|
||||
or
|
||||
```yaml
|
||||
build:
|
||||
context: .
|
||||
ssh: ["default"] # mount the default ssh agent
|
||||
```
|
||||
|
||||
Using a custom id `myproject` with path to a local SSH key:
|
||||
```yaml
|
||||
build:
|
||||
context: .
|
||||
ssh:
|
||||
- myproject=~/.ssh/myproject.pem
|
||||
```
|
||||
Image builder can then rely on this to mount SSH key during build.
|
||||
For illustration, [BuildKit extended syntax](https://github.com/compose-spec/compose-spec/pull/234/%5Bmoby/buildkit@master/frontend/dockerfile/docs/syntax.md#run---mounttypessh%5D(https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md#run---mounttypessh)) can be used to mount ssh key set by ID and access a secured resource:
|
||||
|
||||
`RUN --mount=type=ssh,id=myproject git clone ...`
|
||||
|
||||
### cache_from
|
||||
|
||||
`cache_from` defines a list of sources the Image builder SHOULD use for cache resolution.
|
||||
|
||||
Cache location syntax MUST follow the global format `[NAME|type=TYPE[,KEY=VALUE]]`. Simple `NAME` is actually a shortcut notation for `type=registry,ref=NAME`.
|
||||
|
||||
Compose Builder implementations MAY support custom types, the Compose Specification defines canonical types which MUST be supported:
|
||||
|
||||
- `registry` to retrieve build cache from an OCI image set by key `ref`
|
||||
|
||||
|
||||
```yml
|
||||
build:
|
||||
context: .
|
||||
cache_from:
|
||||
- alpine:latest
|
||||
- type=local,src=path/to/cache
|
||||
- type=gha
|
||||
```
|
||||
|
||||
Unsupported caches MUST be ignored and not prevent user from building image.
|
||||
|
||||
### cache_to
|
||||
|
||||
`cache_to` defines a list of export locations to be used to share build cache with future builds.
|
||||
|
||||
```yml
|
||||
build:
|
||||
context: .
|
||||
cache_to:
|
||||
- user/app:cache
|
||||
- type=local,dest=path/to/cache
|
||||
```
|
||||
|
||||
Cache target is defined using the same `type=TYPE[,KEY=VALUE]` syntax defined by [`cache_from`](#cache_from).
|
||||
|
||||
Unsupported cache target MUST be ignored and not prevent user from building image.
|
||||
|
||||
### extra_hosts
|
||||
|
||||
`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [extra_hosts](spec.md#extra_hosts).
|
||||
|
||||
```yml
|
||||
extra_hosts:
|
||||
- "somehost:162.242.195.82"
|
||||
- "otherhost:50.31.209.229"
|
||||
```
|
||||
|
||||
Compose implementations MUST create matching entry with the IP address and hostname in the container's network
|
||||
configuration, which means for Linux `/etc/hosts` will get extra lines:
|
||||
|
||||
```
|
||||
162.242.195.82 somehost
|
||||
50.31.209.229 otherhost
|
||||
```
|
||||
|
||||
### isolation
|
||||
|
||||
`isolation` specifies a build’s container isolation technology. Like [isolation](spec.md#isolation) supported values
|
||||
are platform-specific.
|
||||
|
||||
### labels
|
||||
|
||||
`labels` add metadata to the resulting image. `labels` can be set either as an array or a map.
|
||||
|
||||
reverse-DNS notation SHOULD be used to prevent labels from conflicting with those used by other software.
|
||||
|
||||
```yml
|
||||
build:
|
||||
context: .
|
||||
labels:
|
||||
com.example.description: "Accounting webapp"
|
||||
com.example.department: "Finance"
|
||||
com.example.label-with-empty-value: ""
|
||||
```
|
||||
|
||||
```yml
|
||||
build:
|
||||
context: .
|
||||
labels:
|
||||
- "com.example.description=Accounting webapp"
|
||||
- "com.example.department=Finance"
|
||||
- "com.example.label-with-empty-value"
|
||||
```
|
||||
|
||||
### shm_size
|
||||
|
||||
`shm_size` set the size of the shared memory (`/dev/shm` partition on Linux) allocated for building Docker image. Specify
|
||||
as an integer value representing the number of bytes or as a string expressing a [byte value](spec.md#specifying-byte-values).
|
||||
|
||||
```yml
|
||||
build:
|
||||
context: .
|
||||
shm_size: '2gb'
|
||||
```
|
||||
|
||||
```yaml
|
||||
build:
|
||||
context: .
|
||||
shm_size: 10000000
|
||||
```
|
||||
|
||||
### target
|
||||
|
||||
`target` defines the stage to build as defined inside a multi-stage `Dockerfile`.
|
||||
|
||||
```yml
|
||||
build:
|
||||
context: .
|
||||
target: prod
|
||||
```
|
||||
|
||||
## Implementations
|
||||
|
||||
* [docker-compose](https://docs.docker.com/compose)
|
||||
* [buildX bake](https://docs.docker.com/buildx/working-with-buildx/)
|
||||
|
|
@ -0,0 +1,296 @@
|
|||
---
|
||||
description: Compose file deploy reference
|
||||
keywords: fig, composition, compose, docker
|
||||
title: Compose file deploy reference
|
||||
toc_max: 4
|
||||
toc_min: 2
|
||||
---
|
||||
|
||||
Compose specification is a platform-neutral way to define multi-container applications. A Compose implementation supporting
|
||||
deployment of application model MAY require some additional metadata as the Compose application model is way too abstract
|
||||
to reflect actual infrastructure needs per service, or lifecycle constraints.
|
||||
|
||||
Compose Specification Deployment allows users to declare additional metadata on services so Compose implementations get
|
||||
relevant data to allocate adequate resources on platform and configure them to match user's needs.
|
||||
|
||||
## Definitions
|
||||
|
||||
Compose Specification is extended to support an OPTIONAL `deploy` subsection on services. This section define runtime requirements
|
||||
for a service.
|
||||
|
||||
### endpoint_mode
|
||||
|
||||
`endpoint_mode` specifies a service discovery method for external clients connecting to a service. Default and available values
|
||||
are platform specific, anyway the Compose specification define two canonical values:
|
||||
|
||||
* `endpoint_mode: vip`: Assigns the service a virtual IP (VIP) that acts as the front end for clients to reach the service
|
||||
on a network. Platform routes requests between the client and nodes running the service, without client knowledge of how
|
||||
many nodes are participating in the service or their IP addresses or ports.
|
||||
|
||||
* `endpoint_mode: dnsrr`: Platform sets up DNS entries for the service such that a DNS query for the service name returns a
|
||||
list of IP addresses (DNS round-robin), and the client connects directly to one of these.
|
||||
|
||||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
ports:
|
||||
- "8080:80"
|
||||
deploy:
|
||||
mode: replicated
|
||||
replicas: 2
|
||||
endpoint_mode: vip
|
||||
```
|
||||
|
||||
### labels
|
||||
|
||||
`labels` specifies metadata for the service. These labels MUST *only* be set on the service and *not* on any containers for the service.
|
||||
This assumes the platform has some native concept of "service" that can match Compose application model.
|
||||
|
||||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
deploy:
|
||||
labels:
|
||||
com.example.description: "This label will appear on the web service"
|
||||
```
|
||||
|
||||
### mode
|
||||
|
||||
`mode` define the replication model used to run the service on platform. Either `global` (exactly one container per physical node) or `replicated` (a specified number of containers). The default is `replicated`.
|
||||
|
||||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
deploy:
|
||||
mode: global
|
||||
```
|
||||
|
||||
### placement
|
||||
|
||||
`placement` specifies constraints and preferences for platform to select a physical node to run service containers.
|
||||
|
||||
#### constraints
|
||||
|
||||
`constraints` defines a REQUIRED property the platform's node MUST fulfill to run service container. Can be set either
|
||||
by a list or a map with string values.
|
||||
|
||||
```yml
|
||||
deploy:
|
||||
placement:
|
||||
constraints:
|
||||
- disktype=ssd
|
||||
```
|
||||
|
||||
```yml
|
||||
deploy:
|
||||
placement:
|
||||
constraints:
|
||||
disktype: ssd
|
||||
```
|
||||
|
||||
#### preferences
|
||||
|
||||
`preferences` defines a property the platform's node SHOULD fulfill to run service container. Can be set either
|
||||
by a list or a map with string values.
|
||||
|
||||
```yml
|
||||
deploy:
|
||||
placement:
|
||||
preferences:
|
||||
- datacenter=us-east
|
||||
```
|
||||
|
||||
```yml
|
||||
deploy:
|
||||
placement:
|
||||
preferences:
|
||||
datacenter: us-east
|
||||
```
|
||||
|
||||
### replicas
|
||||
|
||||
If the service is `replicated` (which is the default), `replicas` specifies the number of containers that SHOULD be
|
||||
running at any given time.
|
||||
|
||||
```yml
|
||||
services:
|
||||
fronted:
|
||||
image: awesome/webapp
|
||||
deploy:
|
||||
mode: replicated
|
||||
replicas: 6
|
||||
```
|
||||
|
||||
### resources
|
||||
|
||||
`resources` configures physical resource constraints for container to run on platform. Those constraints can be configured
|
||||
as a:
|
||||
|
||||
- `limits`: The platform MUST prevent container to allocate more
|
||||
- `reservations`: The platform MUST guarantee container can allocate at least the configured amount
|
||||
|
||||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.50'
|
||||
memory: 50M
|
||||
pids: 1
|
||||
reservations:
|
||||
cpus: '0.25'
|
||||
memory: 20M
|
||||
```
|
||||
|
||||
#### cpus
|
||||
|
||||
`cpus` configures a limit or reservation for how much of the available CPU resources (as number of cores) a container can use.
|
||||
|
||||
#### memory
|
||||
|
||||
`memory` configures a limit or reservation on the amount of memory a container can allocate, set as a string expressing a [byte value](spec.md#specifying-byte-values).
|
||||
|
||||
#### pids
|
||||
|
||||
`pids` tunes a container’s PIDs limit, set as an integer.
|
||||
|
||||
#### devices
|
||||
|
||||
`devices` configures reservations of the devices a container can use. It contains a list of reservations, each set as an object with the following parameters: `capabilities`, `driver`, `count`, `device_ids` and `options`.
|
||||
|
||||
Devices are reserved using a list of capabilities, making `capabilities` the only required field. A device MUST satisfy all the requested capabilities for a successful reservation.
|
||||
|
||||
##### capabilities
|
||||
|
||||
`capabilities` are set as a list of strings, expressing both generic and driver specific capabilities.
|
||||
The following generic capabilities are recognized today:
|
||||
|
||||
- `gpu`: Graphics accelerator
|
||||
- `tpu`: AI accelerator
|
||||
|
||||
To avoid name clashes, driver specific capabilities MUST be prefixed with the driver name.
|
||||
For example, reserving an nVidia CUDA-enabled accelerator might look like this:
|
||||
|
||||
```yml
|
||||
deploy:
|
||||
resources:
|
||||
reservations:
|
||||
devices:
|
||||
- capabilities: ["nvidia-compute"]
|
||||
```
|
||||
|
||||
##### driver
|
||||
|
||||
A different driver for the reserved device(s) can be requested using `driver` field. The value is specified as a string.
|
||||
|
||||
```yml
|
||||
deploy:
|
||||
resources:
|
||||
reservations:
|
||||
devices:
|
||||
- capabilities: ["nvidia-compute"]
|
||||
driver: nvidia
|
||||
```
|
||||
|
||||
##### count
|
||||
|
||||
If `count` is set to `all` or not specified, Compose implementations MUST reserve all devices that satisfy the requested capabilities. Otherwise, Compose implementations MUST reserve at least the number of devices specified. The value is specified as an integer.
|
||||
|
||||
```yml
|
||||
deploy:
|
||||
resources:
|
||||
reservations:
|
||||
devices:
|
||||
- capabilities: ["tpu"]
|
||||
count: 2
|
||||
```
|
||||
|
||||
`count` and `device_ids` fields are exclusive. Compose implementations MUST return an error if both are specified.
|
||||
|
||||
##### device_ids
|
||||
|
||||
If `device_ids` is set, Compose implementations MUST reserve devices with the specified IDs providing they satisfy the requested capabilities. The value is specified as a list of strings.
|
||||
|
||||
```yml
|
||||
deploy:
|
||||
resources:
|
||||
reservations:
|
||||
devices:
|
||||
- capabilities: ["gpu"]
|
||||
device_ids: ["GPU-f123d1c9-26bb-df9b-1c23-4a731f61d8c7"]
|
||||
```
|
||||
|
||||
`count` and `device_ids` fields are exclusive. Compose implementations MUST return an error if both are specified.
|
||||
|
||||
##### options
|
||||
|
||||
Driver specific options can be set with `options` as key-value pairs.
|
||||
|
||||
```yml
|
||||
deploy:
|
||||
resources:
|
||||
reservations:
|
||||
devices:
|
||||
- capabilities: ["gpu"]
|
||||
driver: gpuvendor
|
||||
options:
|
||||
virtualization: false
|
||||
```
|
||||
|
||||
### restart_policy
|
||||
|
||||
`restart_policy` configures if and how to restart containers when they exit. If `restart_policy` is not set, Compose implementations MUST consider `restart` field set by service configuration.
|
||||
|
||||
- `condition`: One of `none`, `on-failure` or `any` (default: `any`).
|
||||
- `delay`: How long to wait between restart attempts, specified as a [duration](spec.md#specifying-durations) (default: 0).
|
||||
- `max_attempts`: How many times to attempt to restart a container before giving up (default: never give up). If the restart does not
|
||||
succeed within the configured `window`, this attempt doesn't count toward the configured `max_attempts` value.
|
||||
For example, if `max_attempts` is set to '2', and the restart fails on the first attempt, more than two restarts MUST be attempted.
|
||||
- `window`: How long to wait before deciding if a restart has succeeded, specified as a [duration](#specifying-durations) (default:
|
||||
decide immediately).
|
||||
|
||||
```yml
|
||||
deploy:
|
||||
restart_policy:
|
||||
condition: on-failure
|
||||
delay: 5s
|
||||
max_attempts: 3
|
||||
window: 120s
|
||||
```
|
||||
|
||||
### rollback_config
|
||||
|
||||
`rollback_config` configures how the service should be rollbacked in case of a failing update.
|
||||
|
||||
- `parallelism`: The number of containers to rollback at a time. If set to 0, all containers rollback simultaneously.
|
||||
- `delay`: The time to wait between each container group's rollback (default 0s).
|
||||
- `failure_action`: What to do if a rollback fails. One of `continue` or `pause` (default `pause`)
|
||||
- `monitor`: Duration after each task update to monitor for failure `(ns|us|ms|s|m|h)` (default 0s).
|
||||
- `max_failure_ratio`: Failure rate to tolerate during a rollback (default 0).
|
||||
- `order`: Order of operations during rollbacks. One of `stop-first` (old task is stopped before starting new one),
|
||||
or `start-first` (new task is started first, and the running tasks briefly overlap) (default `stop-first`).
|
||||
|
||||
### update_config
|
||||
|
||||
`update_config` configures how the service should be updated. Useful for configuring rolling updates.
|
||||
|
||||
- `parallelism`: The number of containers to update at a time.
|
||||
- `delay`: The time to wait between updating a group of containers.
|
||||
- `failure_action`: What to do if an update fails. One of `continue`, `rollback`, or `pause` (default: `pause`).
|
||||
- `monitor`: Duration after each task update to monitor for failure `(ns|us|ms|s|m|h)` (default 0s).
|
||||
- `max_failure_ratio`: Failure rate to tolerate during an update.
|
||||
- `order`: Order of operations during updates. One of `stop-first` (old task is stopped before starting new one),
|
||||
or `start-first` (new task is started first, and the running tasks briefly overlap) (default `stop-first`).
|
||||
|
||||
```yml
|
||||
deploy:
|
||||
update_config:
|
||||
parallelism: 2
|
||||
delay: 10s
|
||||
order: stop-first
|
||||
```
|
||||
|
|
@ -4,7 +4,7 @@ keywords: fig, composition, compose, docker
|
|||
redirect_from:
|
||||
- /compose/yaml
|
||||
- /compose/compose-file/compose-file-v1/
|
||||
title: Compose file
|
||||
title: Compose specification
|
||||
toc_max: 4
|
||||
toc_min: 1
|
||||
---
|
||||
|
|
@ -14,14 +14,6 @@ toc_min: 1
|
|||
These topics describe the Docker Compose implementation of the Compose format.
|
||||
Docker Compose **1.27.0+** implements the format defined by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). Previous Docker Compose versions have support for several Compose file formats – 2, 2.x, and 3.x. The Compose specification is a unified 2.x and 3.x file format, aggregating properties across these formats.
|
||||
|
||||
## Compose and Docker compatibility matrix
|
||||
|
||||
There are several versions of the Compose file format – 2, 2.x, and 3.x. The
|
||||
table below provides a snapshot of various versions. For full details on what each version includes and
|
||||
how to upgrade, see **[About versions and upgrading](compose-versioning.md)**.
|
||||
|
||||
{% include content/compose-matrix.md %}
|
||||
|
||||
## Status of this document
|
||||
|
||||
This document specifies the Compose file format used to define multi-containers applications. Distribution of this document is unlimited.
|
||||
|
|
@ -38,7 +30,7 @@ is Platform dependent and can only be confirmed at runtime. The definition of a
|
|||
properties in a Compose file, established by the [docker-compose](https://github.com/docker/compose) tool where the Compose
|
||||
file format was designed, doesn't offer any guarantee to the end-user attributes will be actually implemented.
|
||||
|
||||
The specification defines the expected configuration syntax and behaviour, but - until noted - supporting any of those is OPTIONAL.
|
||||
The specification defines the expected configuration syntax and behavior, but - until noted - supporting any of those is OPTIONAL.
|
||||
|
||||
A Compose implementation to parse a Compose file using unsupported attributes SHOULD warn user. We recommend implementors
|
||||
to support those running modes:
|
||||
|
|
@ -51,15 +43,15 @@ to support those running modes:
|
|||
|
||||
The Compose specification allows one to define a platform-agnostic container based application. Such an application is designed as a set of containers which have to both run together with adequate shared resources and communication channels.
|
||||
|
||||
Computing components of an application are defined as [Services](#Services-top-level-element). A Service is an abstract concept implemented on platforms by running the same container image (and configuration) one or more times.
|
||||
Computing components of an application are defined as [Services](#services-top-level-element). A Service is an abstract concept implemented on platforms by running the same container image (and configuration) one or more times.
|
||||
|
||||
Services communicate with each other through [Networks](#Networks-top-level-element). In this specification, a Network is a platform capability abstraction to establish an IP route between containers within services connected together. Low-level, platform-specific networking options are grouped into the Network definition and MAY be partially implemented on some platforms.
|
||||
Services communicate with each other through [Networks](#networks-top-level-element). In this specification, a Network is a platform capability abstraction to establish an IP route between containers within services connected together. Low-level, platform-specific networking options are grouped into the Network definition and MAY be partially implemented on some platforms.
|
||||
|
||||
Services store and share persistent data into [Volumes](#Volumes-top-level-element). The specification describes such a persistent data as a high-level filesystem mount with global options. Actual platform-specific implementation details are grouped into the Volumes definition and MAY be partially implemented on some platforms.
|
||||
Services store and share persistent data into [Volumes](#volumes-top-level-element). The specification describes such a persistent data as a high-level filesystem mount with global options. Actual platform-specific implementation details are grouped into the Volumes definition and MAY be partially implemented on some platforms.
|
||||
|
||||
Some services require configuration data that is dependent on the runtime or platform. For this, the specification defines a dedicated concept: [Configs](#Configs-top-level-element). From a Service container point of view, Configs are comparable to Volumes, in that they are files mounted into the container. But the actual definition involves distinct platform resources and services, which are abstracted by this type.
|
||||
Some services require configuration data that is dependent on the runtime or platform. For this, the specification defines a dedicated concept: [Configs](#configs-top-level-element). From a Service container point of view, Configs are comparable to Volumes, in that they are files mounted into the container. But the actual definition involves distinct platform resources and services, which are abstracted by this type.
|
||||
|
||||
A [Secret](#Secrets-top-level-element) is a specific flavour of configuration data for sensitive data that SHOULD NOT be exposed without security considerations. Secrets are made available to services as files mounted into their containers, but the platform-specific resources to provide sensitive data are specific enough to deserve a distinct concept and definition within the Compose specification.
|
||||
A [Secret](#secrets-top-level-element) is a specific flavor of configuration data for sensitive data that SHOULD NOT be exposed without security considerations. Secrets are made available to services as files mounted into their containers, but the platform-specific resources to provide sensitive data are specific enough to deserve a distinct concept and definition within the Compose specification.
|
||||
|
||||
Distinction within Volumes, Configs and Secret allows implementations to offer a comparable abstraction at service level, but cover the specific configuration of adequate platform resources for well identified data usages.
|
||||
|
||||
|
|
@ -105,7 +97,7 @@ The example application is composed of the following parts:
|
|||
- 1 persistent volume, attached to the backend
|
||||
- 2 networks
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
|
|
@ -241,7 +233,7 @@ prefer the most recent schema at the time it has been designed.
|
|||
|
||||
Compose implementations SHOULD validate whether they can fully parse the Compose file. If some fields are unknown, typically
|
||||
because the Compose file was written with fields defined by a newer version of the specification, Compose implementations
|
||||
SHOULD warn the user. Compose implementations MAY offer options to ignore unknown fields (as defined by ["loose"](#Requirements-and-optional-attributes) mode).
|
||||
SHOULD warn the user. Compose implementations MAY offer options to ignore unknown fields (as defined by ["loose"](#requirements-and-optional-attributes) mode).
|
||||
|
||||
## Name top-level element
|
||||
|
||||
|
|
@ -250,9 +242,9 @@ Compose implementations MUST offer a way for user to override this name, and SHO
|
|||
default project name, to be used if the top-level `name` element is not set.
|
||||
|
||||
Whenever project name is defined by top-level `name` or by some custom mechanism, it MUST be exposed for
|
||||
[interpolation](#Interpolation) and environment variable resolution as `COMPOSE_PROJECT_NAME`
|
||||
[interpolation](#interpolation) and environment variable resolution as `COMPOSE_PROJECT_NAME`
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
foo:
|
||||
image: busybox
|
||||
|
|
@ -277,26 +269,27 @@ Each service MAY also include a Build section, which defines how to create the D
|
|||
Compose implementations MAY support building docker images using this service definition. If not implemented
|
||||
the Build section SHOULD be ignored and the Compose file MUST still be considered valid.
|
||||
|
||||
Build support is an OPTIONAL aspect of the Compose specification, and is described in detail [here](build.md)
|
||||
Build support is an OPTIONAL aspect of the Compose specification, and is
|
||||
described in detail in the [Build support](build.md) documentation.
|
||||
|
||||
Each Service defines runtime constraints and requirements to run its containers. The `deploy` section groups
|
||||
these constraints and allows the platform to adjust the deployment strategy to best match containers' needs with
|
||||
available resources.
|
||||
|
||||
Deploy support is an OPTIONAL aspect of the Compose specification, and is described in detail [here](deploy.md). If
|
||||
Deploy support is an OPTIONAL aspect of the Compose specification, and is
|
||||
described in detail in the [Deployment support](deploy.md) documentation.
|
||||
not implemented the Deploy section SHOULD be ignored and the Compose file MUST still be considered valid.
|
||||
|
||||
|
||||
### build
|
||||
|
||||
`build` specifies the build configuration for creating container image from source, as defined [here](build.md).
|
||||
`build` specifies the build configuration for creating container image from source, as defined in the [Build support](build.md) documentation.
|
||||
|
||||
|
||||
### blkio_config
|
||||
|
||||
`blkio_config` defines a set of configuration options to set block IO limits for this service.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
foo:
|
||||
image: busybox
|
||||
|
|
@ -374,7 +367,7 @@ on Linux kernel.
|
|||
`cpu_rt_runtime` configures CPU allocation parameters for platform with support for realtime scheduler. Can be either
|
||||
an integer value using microseconds as unit or a [duration](#specifying-durations).
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
cpu_rt_runtime: '400ms'
|
||||
cpu_rt_runtime: 95000`
|
||||
```
|
||||
|
|
@ -384,7 +377,7 @@ an integer value using microseconds as unit or a [duration](#specifying-duration
|
|||
`cpu_rt_period` configures CPU allocation parameters for platform with support for realtime scheduler. Can be either
|
||||
an integer value using microseconds as unit or a [duration](#specifying-durations).
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
cpu_rt_period: '1400us'
|
||||
cpu_rt_period: 11000`
|
||||
```
|
||||
|
|
@ -469,7 +462,7 @@ access to the `my_config` and `my_other_config` configs. The value of
|
|||
already been defined in the platform. If the external config does not exist,
|
||||
the deployment MUST fail.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
redis:
|
||||
image: redis:latest
|
||||
|
|
@ -500,7 +493,7 @@ container, sets the mode to `0440` (group-readable) and sets the user and group
|
|||
to `103`. The `redis` service does not have access to the `my_other_config`
|
||||
config.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
redis:
|
||||
image: redis:latest
|
||||
|
|
@ -523,7 +516,7 @@ You can grant a service access to multiple configs, and you can mix long and sho
|
|||
|
||||
`container_name` is a string that specifies a custom container name, rather than a generated default name.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
container_name: my-web-container
|
||||
```
|
||||
|
||||
|
|
@ -542,7 +535,7 @@ protocols for custom use-cases.
|
|||
|
||||
The `credential_spec` must be in the format `file://<filename>` or `registry://<value-name>`.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
credential_spec:
|
||||
file: my-credential-spec.json
|
||||
```
|
||||
|
|
@ -555,7 +548,7 @@ the daemon's host. A registry value with the given name must be located in:
|
|||
The following example loads the credential spec from a value named `my-credential-spec`
|
||||
in the registry:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
credential_spec:
|
||||
registry: my-credential-spec
|
||||
```
|
||||
|
|
@ -565,7 +558,7 @@ credential_spec:
|
|||
When configuring a gMSA credential spec for a service, you only need
|
||||
to specify a credential spec with `config`, as shown in the following example:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
myservice:
|
||||
image: myimage:latest
|
||||
|
|
@ -594,7 +587,7 @@ Service dependencies cause the following behaviors:
|
|||
|
||||
Simple example:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
web:
|
||||
build: .
|
||||
|
|
@ -639,7 +632,7 @@ Service dependencies cause the following behaviors:
|
|||
|
||||
Simple example:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
web:
|
||||
build: .
|
||||
|
|
@ -671,7 +664,7 @@ Compose implementations MUST guarantee dependency services marked with
|
|||
The format is the same format the Linux kernel specifies in the [Control Groups
|
||||
Device Whitelist Controller](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/devices.html).
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
device_cgroup_rules:
|
||||
- 'c 1:3 mr'
|
||||
- 'a 7:* rmw'
|
||||
|
|
@ -682,7 +675,7 @@ device_cgroup_rules:
|
|||
`devices` defines a list of device mappings for created containers in the form of
|
||||
`HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS]`.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
devices:
|
||||
- "/dev/ttyUSB0:/dev/ttyUSB0"
|
||||
- "/dev/sda:/dev/xvda:rwm"
|
||||
|
|
@ -692,11 +685,11 @@ devices:
|
|||
|
||||
`dns` defines custom DNS servers to set on the container network interface configuration. Can be a single value or a list.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
dns: 8.8.8.8
|
||||
```
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
dns:
|
||||
- 8.8.8.8
|
||||
- 9.9.9.9
|
||||
|
|
@ -706,7 +699,7 @@ dns:
|
|||
|
||||
`dns_opt` list custom DNS options to be passed to the container’s DNS resolver (`/etc/resolv.conf` file on Linux).
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
dns_opt:
|
||||
- use-vc
|
||||
- no-tld-query
|
||||
|
|
@ -716,11 +709,11 @@ dns_opt:
|
|||
|
||||
`dns` defines custom DNS search domains to set on container network interface configuration. Can be a single value or a list.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
dns_search: example.com
|
||||
```
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
dns_search:
|
||||
- dc1.example.com
|
||||
- dc2.example.com
|
||||
|
|
@ -737,14 +730,14 @@ Compose implementations MUST clear out any default command on the Docker image -
|
|||
in the Dockerfile - when `entrypoint` is configured by a Compose file. If [`command`](#command) is also set,
|
||||
it is used as parameter to `entrypoint` as a replacement for Docker image's `CMD`
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
entrypoint: /code/entrypoint.sh
|
||||
```
|
||||
|
||||
The entrypoint can also be a list, in a manner similar to
|
||||
[Dockerfile](https://docs.docker.com/engine/reference/builder/#cmd):
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
entrypoint:
|
||||
- php
|
||||
- -d
|
||||
|
|
@ -758,14 +751,14 @@ entrypoint:
|
|||
|
||||
`env_file` adds environment variables to the container based on file content.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
env_file: .env
|
||||
```
|
||||
|
||||
`env_file` can also be a list. The files in the list MUST be processed from the top down. For the same variable
|
||||
specified in two env files, the value from the last file in the list MUST stand.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
env_file:
|
||||
- ./a.env
|
||||
- ./b.env
|
||||
|
|
@ -808,7 +801,7 @@ is unset and will be removed from the service container environment.
|
|||
|
||||
Map syntax:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
environment:
|
||||
RACK_ENV: development
|
||||
SHOW: "true"
|
||||
|
|
@ -817,7 +810,7 @@ environment:
|
|||
|
||||
Array syntax:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
environment:
|
||||
- RACK_ENV=development
|
||||
- SHOW=true
|
||||
|
|
@ -832,7 +825,7 @@ When both `env_file` and `environment` are set for a service, values set by `env
|
|||
accessible to linked services and SHOULD NOT be published to the host machine. Only the internal container
|
||||
ports can be specified.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
expose:
|
||||
- "3000"
|
||||
- "8000"
|
||||
|
|
@ -846,7 +839,7 @@ defined with a required `service` and an optional `file` key.
|
|||
|
||||
```yaml
|
||||
extends:
|
||||
file: common.yaml
|
||||
file: common.yml
|
||||
service: webapp
|
||||
```
|
||||
|
||||
|
|
@ -1038,7 +1031,7 @@ Any other allowed keys in the service definition should be treated as scalars.
|
|||
`external_links` define the name of an existing service to retrieve using the platform lookup mechanism.
|
||||
An alias of the form `SERVICE:ALIAS` can be specified.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
external_links:
|
||||
- redis
|
||||
- database:mysql
|
||||
|
|
@ -1050,7 +1043,7 @@ external_links:
|
|||
`extra_hosts` adds hostname mappings to the container network interface configuration (`/etc/hosts` for Linux).
|
||||
Values MUST set hostname and IP address for additional hosts in the form of `HOSTNAME:IP`.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
extra_hosts:
|
||||
- "somehost:162.242.195.82"
|
||||
- "otherhost:50.31.209.229"
|
||||
|
|
@ -1072,7 +1065,7 @@ An example of where this is useful is when multiple containers (running as diffe
|
|||
the same file on a shared volume. That file can be owned by a group shared by all the containers, and specified in
|
||||
`group_add`.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
myservice:
|
||||
image: alpine
|
||||
|
|
@ -1090,7 +1083,7 @@ service are "healthy". This overrides
|
|||
[HEALTHCHECK Dockerfile instruction](https://docs.docker.com/engine/reference/builder/#healthcheck)
|
||||
set by the service's Docker image.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost"]
|
||||
interval: 1m30s
|
||||
|
|
@ -1105,7 +1098,7 @@ healthcheck:
|
|||
either a string or a list. If it's a list, the first item must be either `NONE`, `CMD` or `CMD-SHELL`.
|
||||
If it's a string, it's equivalent to specifying `CMD-SHELL` followed by that string.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
# Hit the local web app
|
||||
test: ["CMD", "curl", "-f", "http://localhost"]
|
||||
```
|
||||
|
|
@ -1113,18 +1106,18 @@ test: ["CMD", "curl", "-f", "http://localhost"]
|
|||
Using `CMD-SHELL` will run the command configured as a string using the container's default shell
|
||||
(`/bin/sh` for Linux). Both forms below are equivalent:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
|
||||
```
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
test: curl -f https://localhost || exit 1
|
||||
```
|
||||
|
||||
`NONE` disable the healthcheck, and is mostly useful to disable Healthcheck set by image. Alternatively
|
||||
the healthcheck set by the image can be disabled by setting `disable: true`:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
healthcheck:
|
||||
disable: true
|
||||
```
|
||||
|
|
@ -1139,7 +1132,7 @@ healthcheck:
|
|||
[addressable image format](https://github.com/opencontainers/org/blob/master/docs/docs/introduction/digests.md),
|
||||
as `[<registry>/][<project>/]<image>[:<tag>|@<digest>]`.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
image: redis
|
||||
image: redis:5
|
||||
image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
|
||||
|
|
@ -1160,7 +1153,7 @@ without build support MUST fail when `image` is missing from the Compose file.
|
|||
`init` run an init process (PID 1) inside the container that forwards signals and reaps processes.
|
||||
Set this option to `true` to enable this feature for the service.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
web:
|
||||
image: alpine:latest
|
||||
|
|
@ -1180,7 +1173,7 @@ which MUST be implemented as described if supported:
|
|||
- `service:{name}` which makes the container join another (`shareable`)
|
||||
container's IPC namespace.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
ipc: "shareable"
|
||||
ipc: "service:[service name]"
|
||||
```
|
||||
|
|
@ -1196,14 +1189,14 @@ which MUST be implemented as described if supported:
|
|||
It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with
|
||||
those used by other software.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
labels:
|
||||
com.example.description: "Accounting webapp"
|
||||
com.example.department: "Finance"
|
||||
com.example.label-with-empty-value: ""
|
||||
```
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
labels:
|
||||
- "com.example.description=Accounting webapp"
|
||||
- "com.example.department=Finance"
|
||||
|
|
@ -1223,7 +1216,7 @@ result in a runtime error.
|
|||
`links` defines a network link to containers in another service. Either specify both the service name and
|
||||
a link alias (`SERVICE:ALIAS`), or just the service name.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
web:
|
||||
links:
|
||||
- db
|
||||
|
|
@ -1247,7 +1240,7 @@ Links also express implicit dependency between services in the same way as
|
|||
|
||||
`logging` defines the logging configuration for the service.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
logging:
|
||||
driver: syslog
|
||||
options:
|
||||
|
|
@ -1266,7 +1259,7 @@ specification define specific values which MUST be implemented as described if s
|
|||
- `host` which gives the container raw access to host's network interface
|
||||
- `service:{name}` which gives the containers access to the specified service only
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
network_mode: "host"
|
||||
network_mode: "none"
|
||||
network_mode: "service:[service name]"
|
||||
|
|
@ -1277,7 +1270,7 @@ specification define specific values which MUST be implemented as described if s
|
|||
`networks` defines the networks that service containers are attached to, referencing entries under the
|
||||
[top-level `networks` key](#networks-top-level-element).
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
some-service:
|
||||
networks:
|
||||
|
|
@ -1297,7 +1290,7 @@ Since `aliases` are network-scoped, the same service can have different aliases
|
|||
|
||||
The general format is shown here:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
some-service:
|
||||
networks:
|
||||
|
|
@ -1314,7 +1307,7 @@ In the example below, service `frontend` will be able to reach the `backend` ser
|
|||
the hostname `backend` or `database` on the `back-tier` network, and service `monitoring`
|
||||
will be able to reach same `backend` service at `db` or `mysql` on the `admin` network.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
|
|
@ -1350,7 +1343,7 @@ Specify a static IP address for containers for this service when joining the net
|
|||
The corresponding network configuration in the [top-level networks section](#networks) MUST have an
|
||||
`ipam` block with subnet configurations covering each static address.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
|
|
@ -1472,7 +1465,7 @@ _DEPRECATED: use [deploy.reservations.pids](deploy.md#pids)_
|
|||
|
||||
`pids_limit` tunes a container’s PIDs limit. Set to -1 for unlimited PIDs.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
pids_limit: 10
|
||||
```
|
||||
|
||||
|
|
@ -1482,7 +1475,7 @@ pids_limit: 10
|
|||
Compose implementation MUST use this attribute when declared to determine which version of the image will be pulled
|
||||
and/or on which platform the service’s build will be performed.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
platform: osx
|
||||
platform: windows/amd64
|
||||
platform: linux/arm64/v8
|
||||
|
|
@ -1516,7 +1509,7 @@ with [yaml base-60 float](https://yaml.org/type/float.html).
|
|||
|
||||
Samples:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
ports:
|
||||
- "3000"
|
||||
- "3000-3005"
|
||||
|
|
@ -1542,7 +1535,7 @@ expressed in the short form.
|
|||
- `protocol`: the port protocol (`tcp` or `udp`), unspecified means any protocol
|
||||
- `mode`: `host` for publishing a host port on each node, or `ingress` for a port to be load balanced.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
ports:
|
||||
- target: 80
|
||||
host_ip: 127.0.0.1
|
||||
|
|
@ -1595,7 +1588,7 @@ If `pull_policy` and `build` both presents, Compose implementations SHOULD build
|
|||
- `unless-stopped`: The policy restarts a container irrespective of the exit code but will stop
|
||||
restarting when the service is stopped or removed.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
restart: "no"
|
||||
restart: always
|
||||
restart: on-failure
|
||||
|
|
@ -1609,7 +1602,7 @@ If `pull_policy` and `build` both presents, Compose implementations SHOULD build
|
|||
The value of `runtime` is specific to implementation.
|
||||
For example, `runtime` can be the name of [an implementation of OCI Runtime Spec](https://github.com/opencontainers/runtime-spec/blob/master/implementations.md), such as "runc".
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
web:
|
||||
image: busybox:latest
|
||||
command: true
|
||||
|
|
@ -1641,7 +1634,7 @@ The following example uses the short syntax to grant the `frontend` service
|
|||
access to the `server-certificate` secret. The value of `server-certificate` is set
|
||||
to the contents of the file `./server.cert`.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
|
|
@ -1672,7 +1665,7 @@ within the container, sets the mode to `0440` (group-readable) and sets the user
|
|||
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.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
|
|
@ -1695,7 +1688,7 @@ Such grant must be explicit within service specification as [secrets](#secrets)
|
|||
|
||||
`security_opt` overrides the default labeling scheme for each container.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
security_opt:
|
||||
- label:user:USER
|
||||
- label:role:ROLE
|
||||
|
|
@ -1717,7 +1710,7 @@ handle SIGTERM (or whichever stop signal has been specified with
|
|||
[`stop_signal`](#stopsignal)), before sending SIGKILL. Specified
|
||||
as a [duration](#specifying-durations).
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
stop_grace_period: 1s
|
||||
stop_grace_period: 1m30s
|
||||
```
|
||||
|
|
@ -1729,7 +1722,7 @@ Default value is 10 seconds for the container to exit before sending SIGKILL.
|
|||
`stop_signal` defines the signal that the Compose implementation MUST use to stop the service containers.
|
||||
If unset containers are stopped by the Compose Implementation by sending `SIGTERM`.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
stop_signal: SIGUSR1
|
||||
```
|
||||
|
||||
|
|
@ -1737,7 +1730,7 @@ stop_signal: SIGUSR1
|
|||
|
||||
`storage_opt` defines storage driver options for a service.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
storage_opt:
|
||||
size: '1G'
|
||||
```
|
||||
|
|
@ -1746,13 +1739,13 @@ storage_opt:
|
|||
|
||||
`sysctls` defines kernel parameters to set in the container. `sysctls` can use either an array or a map.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
sysctls:
|
||||
net.core.somaxconn: 1024
|
||||
net.ipv4.tcp_syncookies: 0
|
||||
```
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
sysctls:
|
||||
- net.core.somaxconn=1024
|
||||
- net.ipv4.tcp_syncookies=0
|
||||
|
|
@ -1767,11 +1760,11 @@ parameters (sysctls) at runtime](https://docs.docker.com/engine/reference/comman
|
|||
|
||||
`tmpfs` mounts a temporary file system inside the container. Can be a single value or a list.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
tmpfs: /run
|
||||
```
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
tmpfs:
|
||||
- /run
|
||||
- /tmp
|
||||
|
|
@ -1786,7 +1779,7 @@ tmpfs:
|
|||
`ulimits` overrides the default ulimits for a container. Either specifies as a single limit as an integer or
|
||||
soft/hard limits as a mapping.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
ulimits:
|
||||
nproc: 65535
|
||||
nofile:
|
||||
|
|
@ -1804,7 +1797,7 @@ if not set, `root`.
|
|||
`userns_mode` sets the user namespace for the service. Supported values are platform specific and MAY depend
|
||||
on platform configuration
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
userns_mode: "host"
|
||||
```
|
||||
|
||||
|
|
@ -1821,7 +1814,7 @@ volume MUST be declared in the [top-level `volumes` key](#volumes-top-level-elem
|
|||
This example shows a named volume (`db-data`) being used by the `backend` service,
|
||||
and a bind mount defined for a single service
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
backend:
|
||||
image: awesome/backend
|
||||
|
|
@ -1916,7 +1909,7 @@ Services can connect to networks by specifying the network name under the servic
|
|||
In the following example, at runtime, networks `front-tier` and `back-tier` will be created and the `frontend` service
|
||||
connected to the `front-tier` network and the `back-tier` network.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
|
|
@ -1934,7 +1927,7 @@ networks:
|
|||
`driver` specifies which driver should be used for this network. Compose implementations MUST return an error if the
|
||||
driver is not available on the platform.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
driver: overlay
|
||||
```
|
||||
|
||||
|
|
@ -1951,7 +1944,7 @@ the scope of the Compose implementation. To use them one MUST define an external
|
|||
an alias that the Compose implementation can use (`hostnet` or `nonet` in the following examples), then grant the service
|
||||
access to that network using its alias.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
web:
|
||||
networks:
|
||||
|
|
@ -1963,7 +1956,7 @@ networks:
|
|||
name: host
|
||||
```
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
web:
|
||||
...
|
||||
|
|
@ -1981,7 +1974,7 @@ networks:
|
|||
`driver_opts` specifies a list of options as key-value pairs to pass to the driver for this network. These options are
|
||||
driver-dependent - consult the driver's documentation for more information. Optional.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
driver_opts:
|
||||
foo: "bar"
|
||||
baz: 1
|
||||
|
|
@ -1993,7 +1986,7 @@ If `attachable` is set to `true`, then standalone containers SHOULD be able atta
|
|||
If a standalone container attaches to the network, it can communicate with services and other standalone containers
|
||||
that are also attached to the network.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
networks:
|
||||
mynet1:
|
||||
driver: overlay
|
||||
|
|
@ -2018,7 +2011,7 @@ networks:
|
|||
|
||||
A full example:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
ipam:
|
||||
driver: default
|
||||
config:
|
||||
|
|
@ -2045,14 +2038,14 @@ Add metadata to containers using Labels. Can use either an array or a dictionary
|
|||
|
||||
Users SHOULD use reverse-DNS notation to prevent labels from conflicting with those used by other software.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
labels:
|
||||
com.example.description: "Financial transaction network"
|
||||
com.example.department: "Finance"
|
||||
com.example.label-with-empty-value: ""
|
||||
```
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
labels:
|
||||
- "com.example.description=Financial transaction network"
|
||||
- "com.example.department=Finance"
|
||||
|
|
@ -2070,7 +2063,7 @@ In the example below, `proxy` is the gateway to the outside world. Instead of at
|
|||
implementations SHOULD interrogate the platform for an existing network simply called `outside` and connect the
|
||||
`proxy` service's containers to it.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
|
||||
services:
|
||||
proxy:
|
||||
|
|
@ -2093,7 +2086,7 @@ networks:
|
|||
`name` sets a custom name for this network. The name field can be used to reference networks which contain special characters.
|
||||
The name is used as is and will **not** be scoped with the project name.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
networks:
|
||||
network1:
|
||||
name: my-app-net
|
||||
|
|
@ -2102,7 +2095,7 @@ networks:
|
|||
It can also be used in conjunction with the `external` property to define the platform network that the Compose implementation
|
||||
should retrieve, typically by using a parameter so the Compose file doesn't need to hard-code runtime specific values:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
networks:
|
||||
network1:
|
||||
external: true
|
||||
|
|
@ -2118,7 +2111,7 @@ The `volumes` section allows the configuration of named volumes that can be reus
|
|||
an example of a two-service setup where a database's data directory is shared with another service as a volume named
|
||||
`db-data` so that it can be periodically backed up:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
backend:
|
||||
image: awesome/database
|
||||
|
|
@ -2141,7 +2134,7 @@ creating a volume. Optionally, you can configure it with the following keys:
|
|||
|
||||
Specify which volume driver should be used for this volume. Default and available values are platform specific. If the driver is not available, the Compose implementation MUST return an error and stop application deployment.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
driver: foobar
|
||||
```
|
||||
|
||||
|
|
@ -2149,7 +2142,7 @@ driver: foobar
|
|||
|
||||
`driver_opts` specifies a list of options as key-value pairs to pass to the driver for this volume. Those options are driver-dependent.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
volumes:
|
||||
example:
|
||||
driver_opts:
|
||||
|
|
@ -2168,7 +2161,7 @@ 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.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
services:
|
||||
backend:
|
||||
image: awesome/database
|
||||
|
|
@ -2187,14 +2180,14 @@ volumes:
|
|||
It's recommended that you use reverse-DNS notation to prevent your labels from
|
||||
conflicting with those used by other software.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
labels:
|
||||
com.example.description: "Database volume"
|
||||
com.example.department: "IT/Ops"
|
||||
com.example.label-with-empty-value: ""
|
||||
```
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
labels:
|
||||
- "com.example.description=Database volume"
|
||||
- "com.example.department=IT/Ops"
|
||||
|
|
@ -2208,7 +2201,7 @@ Compose implementation MUST set `com.docker.compose.project` and `com.docker.com
|
|||
`name` set a custom name for this volume. The name field can be used to reference volumes that contain special
|
||||
characters. The name is used as is and will **not** be scoped with the stack name.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
volumes:
|
||||
data:
|
||||
name: "my-app-data"
|
||||
|
|
@ -2217,7 +2210,7 @@ volumes:
|
|||
It can also be used in conjunction with the `external` property. Doing so the name of the volume used to lookup for
|
||||
actual volume on platform is set separately from the name used to refer to it within the Compose file:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
volumes:
|
||||
db-data:
|
||||
external:
|
||||
|
|
@ -2227,7 +2220,7 @@ volumes:
|
|||
This make it possible to make this lookup name a parameter of a Compose file, so that the model ID for volume is
|
||||
hard-coded but the actual volume ID on platform is set at runtime during deployment:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
volumes:
|
||||
db-data:
|
||||
external:
|
||||
|
|
@ -2262,7 +2255,7 @@ and `my_second_config` MUST already exist on Platform and value will be obtained
|
|||
In this example, `server-http_config` is created as `<project_name>_http_config` when the application is deployed,
|
||||
by registering content of the `httpd.conf` as configuration data.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
configs:
|
||||
http_config:
|
||||
file: ./httpd.conf
|
||||
|
|
@ -2270,7 +2263,7 @@ configs:
|
|||
|
||||
Alternatively, `http_config` can be declared as external, doing so Compose implementation will lookup `http_config` to expose configuration data to relevant services.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
configs:
|
||||
http_config:
|
||||
external: true
|
||||
|
|
@ -2281,7 +2274,7 @@ example modifies the previous one to lookup for config using a parameter `HTTP_C
|
|||
so the actual lookup key will be set at deployment time by [interpolation](#interpolation) of
|
||||
variables, but exposed to containers as hard-coded ID `http_config`.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
configs:
|
||||
http_config:
|
||||
external: true
|
||||
|
|
@ -2307,7 +2300,7 @@ application. The source of the secret is either `file` or `external`.
|
|||
In this example, `server-certificate` is created as `<project_name>_server-certificate` when the application is deployed,
|
||||
by registering content of the `server.cert` as a platform secret.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
secrets:
|
||||
server-certificate:
|
||||
file: ./server.cert
|
||||
|
|
@ -2315,7 +2308,7 @@ secrets:
|
|||
|
||||
Alternatively, `server-certificate` can be declared as external, doing so Compose implementation will lookup `server-certificate` to expose secret to relevant services.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
secrets:
|
||||
server-certificate:
|
||||
external: true
|
||||
|
|
@ -2326,7 +2319,7 @@ example modifies the previous one to look up for secret using a parameter `CERTI
|
|||
so the actual lookup key will be set at deployment time by [interpolation](#interpolation) of
|
||||
variables, but exposed to containers as hard-coded ID `server-certificate`.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
secrets:
|
||||
server-certificate:
|
||||
external: true
|
||||
|
|
@ -2339,7 +2332,7 @@ Compose file need to explicitly grant access to the secrets to relevant services
|
|||
|
||||
It is possible to re-use configuration fragments using [YAML anchors](http://www.yaml.org/spec/1.2/spec.html#id2765878).
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
volumes:
|
||||
db-data: &default-volume
|
||||
driver: default
|
||||
|
|
@ -2353,7 +2346,7 @@ It is also possible to partially override values set by anchor reference using t
|
|||
[YAML merge type](http://yaml.org/type/merge.html). In following example, `metrics` volume specification uses alias
|
||||
to avoid repetition but override `name` attribute:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
|
||||
services:
|
||||
backend:
|
||||
|
|
@ -2375,7 +2368,7 @@ volumes:
|
|||
Special extension fields can be of any format as long as their name starts with the `x-` character sequence. They can be used
|
||||
within any structure in a Compose file. This is the sole exception for Compose implementations to silently ignore unrecognized field.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
x-custom:
|
||||
foo:
|
||||
- bar
|
||||
|
|
@ -2392,7 +2385,7 @@ The contents of such fields are unspecified by Compose specification, and can be
|
|||
For platform extensions, it is highly recommended to prefix extension by platform/vendor name, the same way browsers add
|
||||
support for [custom CSS features](https://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#vendor-keywords)
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
service:
|
||||
backend:
|
||||
deploy:
|
||||
|
|
@ -2415,7 +2408,7 @@ This section is informative. At the time of writing, the following prefixes are
|
|||
|
||||
With the support for extension fields, Compose file can be written as follows to improve readability of reused fragments:
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
x-logging: &default-logging
|
||||
options:
|
||||
max-size: "12m"
|
||||
|
|
@ -2491,7 +2484,7 @@ dollar sign. This also prevents Compose from interpolating a value, so a `$$`
|
|||
allows you to refer to environment variables that you don't want processed by
|
||||
Compose.
|
||||
|
||||
```yaml
|
||||
```yml
|
||||
web:
|
||||
build: .
|
||||
command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"
|
||||
|
|
|
|||
Loading…
Reference in New Issue