Skip to content

Commit

Permalink
Merge pull request compose-spec#142 from jprusik/doc-cleanup
Browse files Browse the repository at this point in the history
  • Loading branch information
@ndeloof
ndeloof committed Feb 28, 2021
2 parents 4fe3986 + af8304d commit f9a5c72
Show file tree
Hide file tree
Showing 3 changed files with 101 additions and 119 deletions.
72 changes: 33 additions & 39 deletions build.md
View file
Expand Up @@ -2,54 +2,51 @@

*Note:* Build is an OPTIONAL part of the Compose Specification


## Introduction

Compose specification is a platform-neutral way to define multi-container applications. A Compose implementation
focussing 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
Compose specification is a platform-neutral way to define multi-container applications. A Compose implementation
focussing 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
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 detailled build definition.
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
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
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
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
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`
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.
Expand All @@ -70,38 +67,36 @@ services:
build: ~/custom
```

When used to build service images from source, such a Compose file will create three docker images:
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 detailled structure:
`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.
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
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
Expand All @@ -112,10 +107,9 @@ build:
### 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
Compose implementations MUST warn user about absolute path used to define Dockerfile as those prevent Compose file
for being portable.


```yml
build:
context: .
Expand All @@ -127,6 +121,7 @@ build:
`args` define build arguments, i.e. Dockerfile `ARG` values.

Using following Dockerfile:

```Dockerfile
ARG GIT_COMMIT
RUN echo "Based on commit: $GIT_COMMIT"
Expand All @@ -137,7 +132,7 @@ RUN echo "Based on commit: $GIT_COMMIT"
```yml
build:
context: .
args:
args:
GIT_COMMIT: cdc3b19
```

Expand All @@ -148,7 +143,7 @@ build:
- GIT_COMMIT=cdc3b19
```

Value can be omited when specifying a build argument, in which case its value at build time MUST be obtained by user interaction,
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
Expand Down Expand Up @@ -188,12 +183,12 @@ configuration, which means for Linux `/etc/hosts` will get extra lines:

### isolation

`isolation` specifies a build’s container isolation technology. Like [isolation](spec.md#isolation) supported values
`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. `labrls` can be set either as an array or a map.
`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.

Expand Down Expand Up @@ -242,7 +237,6 @@ build:
target: prod
```


## Implementations

* [docker-compose](https://docs.docker.com/compose)
Expand Down
26 changes: 8 additions & 18 deletions deploy.md
View file
Expand Up @@ -8,29 +8,26 @@ Compose specification is a platform-neutral way to define multi-container applic
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
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
* `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
* `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:
Expand All @@ -43,7 +40,6 @@ services:
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.
Expand All @@ -58,12 +54,10 @@ services:
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:
Expand All @@ -81,7 +75,6 @@ services:
`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:
Expand All @@ -101,7 +94,6 @@ deploy:
`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:
Expand All @@ -116,7 +108,6 @@ deploy:
datacenter: us-east
```


### replicas

If the service is `replicated` (which is the default), `replicas` specifies the number of containers that SHOULD be
Expand All @@ -135,6 +126,7 @@ services:

`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

Expand Down Expand Up @@ -217,7 +209,6 @@ deploy:

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:
Expand Down Expand Up @@ -248,7 +239,7 @@ deploy:

`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`).
- `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.
Expand All @@ -274,7 +265,7 @@ deploy:
- `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),
- `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
Expand All @@ -286,10 +277,9 @@ deploy:
- `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),
- `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:
Expand Down

0 comments on commit f9a5c72

Please sign in to comment.