Skip to content

Latest commit

 

History

History
3226 lines (2420 loc) · 106 KB

spec.md

File metadata and controls

3226 lines (2420 loc) · 106 KB

The Compose Specification

{:.no_toc}

  • ToC {:toc}

Status of this document

This document specifies the Compose file format used to define multi-containers applications. Distribution of this document is unlimited.

Requirements and optional attributes

The Compose specification includes properties designed to target a local OCI container runtime, exposing Linux kernel specific configuration options, but also some Windows container specific properties. It is also designed for cloud platform features related to resource placement on a cluster, replicated application distribution, and scalability.

We acknowledge that no Compose implementation is expected to support all attributes, and that support for some properties is platform dependent and can only be confirmed at runtime. The definition of a versioned schema to control the supported properties in a Compose file, established by the docker-compose tool where the Compose file format was designed, doesn't offer any guarantee to the end-user that attributes will be actually implemented.

The specification defines the expected configuration syntax and behavior. Unless noted, supporting any of these is optional.

A Compose implementation to parse a Compose file using unsupported attributes should warn users. We recommend the following implementors to support those running modes:

  • Default: warn the user about unsupported attributes, but ignore them
  • Strict: warn the user about unsupported attributes and reject the Compose file
  • Loose: ignore unsupported attributes AND unknown attributes (that were not defined by the spec by the time implementation was created)

From this point onwards, references made to 'Compose' can be interpreted as 'a Compose implementation'.

The Compose application model

The Compose Specification lets you 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. 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. In the Compose 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. 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 configs concept. 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 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.

Note

With volumes, configs and secrets you can have a simple declaration at the top-level and then add more platform-specific information at the service level.

A project is an individual deployment of an application specification on a platform. A project's name, set with the top-level name attribute, is used to group resources together and isolate them from other applications or other installation of the same Compose specified application with distinct parameters. If you are creating resources on a platform, you must prefix resource names by project and set the label com.docker.compose.project.

Compose offers a way for users to set a custom project name and override this name, so that the same compose.yaml file can be deployed twice on the same infrastructure, without changes, by just passing a distinct name.

Project names must contain only lowercase letters, decimal digits, dashes, and underscores, and must begin with a lowercase letter or decimal digit.

Illustrative example

The following example illustrates the Compose Specification concepts outlined above. The example is non-normative.

Consider an application split into a frontend web application and a backend service.

The frontend is configured at runtime with an HTTP configuration file managed by infrastructure, providing an external domain name, and an HTTPS server certificate injected by the platform's secured secret store.

The backend stores data in a persistent volume.

Both services communicate with each other on an isolated back-tier network, while the frontend is also connected to a front-tier network and exposes port 443 for external usage.

    %%{ init: { 'flowchart': { 'curve': 'linear' } } }%%
    flowchart LR
    subgraph A[INFRASTRUCTURE]
    direction TB
    subgraph TOP[" "]
        subgraph B1[Frontend Service]
            fs["`**webapp**`"]
        end
        style B1 fill:#ccd6e8, stroke-width:0px
        subgraph B2[Backend Service]
            bs["`**database**`"]
        end
        style B2 fill:#ccd6e8, stroke-width:0px
        
    end
    style TOP fill:transparent, stroke-width:2px, stroke:#62affb, stroke-dasharray: 5 5
        key[ro= read only\nr+w = read write]
        style key fill:transparent, stroke-width:0px,text-align: left, size: 94px
        
        direction TB
        id2(Server\nCertificate)
        id1(HTTP\nConfiguration)
        id1 & id2 -.-|ro| B1
        style id1 stroke:#000,stroke-width:1px,stroke-dasharray: 10
        style id2 stroke:#000,stroke-width:1px,stroke-dasharray: 10
        B2 ==r+w==> id3[(Persistent\nVolume)]
    end
    style A fill:#eeeeee, stroke-width:0px
    direction LR
    id4[External\nUser] ---id5(((443)))--->|Frontend\nNetwork| B1
    style id4 stroke:#000,stroke-width:2px
    B1 --Backend\nNetwork--> B2
Loading

The example application is composed of the following parts:

  • 2 services, backed by Docker images: webapp and database
  • 1 secret (HTTPS certificate), injected into the frontend
  • 1 configuration (HTTP), injected into the frontend
  • 1 persistent volume, attached to the backend
  • 2 networks
services:
  frontend:
    image: example/webapp
    ports:
      - "443:8043"
    networks:
      - front-tier
      - back-tier
    configs:
      - httpd-config
    secrets:
      - server-certificate

  backend:
    image: example/database
    volumes:
      - db-data:/etc/data
    networks:
      - back-tier

volumes:
  db-data:
    driver: flocker
    driver_opts:
      size: "10GiB"

configs:
  httpd-config:
    external: true

secrets:
  server-certificate:
    external: true

networks:
  # The presence of these objects is sufficient to define them
  front-tier: {}
  back-tier: {}

This example illustrates the distinction between volumes, configs and secrets. While all of them are all exposed to service containers as mounted files or directories, only a volume can be configured for read+write access. Secrets and configs are read-only. The volume configuration allows you to select a volume driver and pass driver options to tweak volume management according to the actual infrastructure. Configs and secrets rely on platform services, and are declared external as they are not managed as part of the application lifecycle. Compose uses a platform-specific lookup mechanism to retrieve runtime values.

Compose file

The Compose file is a YAML file defining:

The default path for a Compose file is compose.yaml (preferred) or compose.yml that is placed in the working directory. Compose also supports docker-compose.yaml and docker-compose.yml for backwards compatibility of earlier versions. If both files exist, Compose prefers the canonical compose.yaml.

You can use fragments and extensions to keep your Compose file efficient and easy to maintain.

Multiple Compose files can be merged together to define the application model. The combination of YAML files are implemented by appending or overriding YAML elements based on the Compose file order you set. Simple attributes and maps get overridden by the highest order Compose file, lists get merged by appending. Relative paths are resolved based on the first Compose file's parent folder, whenever complimentary files being merged are hosted in other folders. As some Compose file elements can both be expressed as single strings or complex objects, merges apply to the expanded form.

If you want to reuse other Compose files, or factor out parts of you application model into separate Compose files, you can also use include. This is useful if your Compose application is dependent on another application which is managed by a different team, or needs to be shared with others.

Version and name top-level elements

Version top-level element (obsolete)

The top-level version property is defined by the Compose Specification for backward compatibility. It is only informative you'll receive a warning message that it is obsolete if used.

Compose doesn't use version to select an exact schema to validate the Compose file, but prefers the most recent schema when it's implemented.

Compose validates whether it 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, you'll receive a warning message. Compose offers options to ignore unknown fields (as defined by "loose" mode).

Name top-level element

The top-level name property is defined by the Specification as the project name to be used if you don't set one explicitly. Compose offers a way for you to override this name, and sets a default project name to be used if the top-level name element is not set.

Whenever a project name is defined by top-level name or by some custom mechanism, it is exposed for interpolation and environment variable resolution as COMPOSE_PROJECT_NAME

services:
  foo:
    image: busybox
    environment:
      - COMPOSE_PROJECT_NAME
    command: echo "I'm running ${COMPOSE_PROJECT_NAME}"

Services top-level element

A service is an abstract definition of a computing resource within an application which can be scaled or replaced independently from other components. Services are backed by a set of containers, run by the platform according to replication requirements and placement constraints. As services are backed by containers, they are defined by a Docker image and set of runtime arguments. All containers within a service are identically created with these arguments.

A Compose file must declare a services top-level element as a map whose keys are string representations of service names, and whose values are service definitions. A service definition contains the configuration that is applied to each service container.

Each service may also include a build section, which defines how to create the Docker image for the service. Compose supports building docker images using this service definition. If not used, the build section is ignored and the Compose file is still considered valid. Build support is an optional aspect of the Compose Specification, and is described in detail in the Compose Build Specification 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 in the Compose Deploy Specification documentation. If not implemented the deploy section is ignored and the Compose file is still considered valid.

attach

Compose v2.20.0

When attach is defined and set to false Compose does not collect service logs, until you explicitly request it to.

The default service configuration is attach: true.

build

build specifies the build configuration for creating a container image from source, as defined in the Compose Build Specification.

blkio_config

blkio_config defines a set of configuration options to set block IO limits for a service.

services:
  foo:
    image: busybox
    blkio_config:
       weight: 300
       weight_device:
         - path: /dev/sda
           weight: 400
       device_read_bps:
         - path: /dev/sdb
           rate: '12mb'
       device_read_iops:
         - path: /dev/sdb
           rate: 120
       device_write_bps:
         - path: /dev/sdb
           rate: '1024k'
       device_write_iops:
         - path: /dev/sdb
           rate: 30

device_read_bps, device_write_bps

Set a limit in bytes per second for read / write operations on a given device. Each item in the list must have two keys:

  • path: Defines the symbolic path to the affected device.
  • rate: Either as an integer value representing the number of bytes or as a string expressing a byte value.

device_read_iops, device_write_iops

Set a limit in operations per second for read / write operations on a given device. Each item in the list must have two keys:

  • path: Defines the symbolic path to the affected device.
  • rate: As an integer value representing the permitted number of operations per second.

weight

Modify the proportion of bandwidth allocated to a service relative to other services. Takes an integer value between 10 and 1000, with 500 being the default.

weight_device

Fine-tune bandwidth allocation by device. Each item in the list must have two keys:

  • path: Defines the symbolic path to the affected device.
  • weight: An integer value between 10 and 1000.

cpu_count

cpu_count defines the number of usable CPUs for service container.

cpu_percent

cpu_percent defines the usable percentage of the available CPUs.

cpu_shares

cpu_shares defines, as integer value, a service container's relative CPU weight versus other containers.

cpu_period

cpu_period configures CPU CFS (Completely Fair Scheduler) period when a platform is based on Linux kernel.

cpu_quota

cpu_quota configures CPU CFS (Completely Fair Scheduler) quota when a platform is based on Linux kernel.

cpu_rt_runtime

cpu_rt_runtime configures CPU allocation parameters for platforms with support for realtime scheduler. It can be either an integer value using microseconds as unit or a duration.

 cpu_rt_runtime: '400ms'
 cpu_rt_runtime: 95000`

cpu_rt_period

cpu_rt_period configures CPU allocation parameters for platforms with support for realtime scheduler. It can be either an integer value using microseconds as unit or a duration.

 cpu_rt_period: '1400us'
 cpu_rt_period: 11000`

cpus

cpus define the number of (potentially virtual) CPUs to allocate to service containers. This is a fractional number. 0.000 means no limit.

When both are set, cpus must be consistent with the cpus attribute in the Deploy Specification

cpuset

cpuset defines the explicit CPUs in which to allow execution. Can be a range 0-3 or a list 0,1

cap_add

cap_add specifies additional container capabilities as strings.

cap_add:
  - ALL

cap_drop

cap_drop specifies container capabilities to drop as strings.

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup

Compose v2.15.0

cgroup specifies the cgroup namespace to join. When unset, it is the container runtime's decision to select which cgroup namespace to use, if supported.

  • host: Runs the container in the Container runtime cgroup namespace.
  • private: Runs the container in its own private cgroup namespace.

cgroup_parent

cgroup_parent specifies an optional parent cgroup for the container.

cgroup_parent: m-executor-abcd

command

command overrides the default command declared by the container image, for example by Dockerfile's CMD.

command: bundle exec thin -p 3000

The value can also be a list, in a manner similar to Dockerfile:

command: [ "bundle", "exec", "thin", "-p", "3000" ]

If the value is null, the default command from the image is used.

If the value is [] (empty list) or '' (empty string), the default command declared by the image is ignored, i.e. overridden to be empty.

configs

Configs allow services to adapt their behaviour without the need to rebuild a Docker image. Services can only access configs when explicitly granted by the configs attribute. Two different syntax variants are supported.

Compose reports an error if config doesn't exist on the platform or isn't defined in the configs top-level element in the Compose file.

There are two syntaxes defined for configs. To remain compliant to this specification, an implementation must support both syntaxes. Implementations must allow use of both short and long syntaxes within the same document.

You can grant a service access to multiple configs, and you can mix long and short syntax.

Short syntax

The short syntax variant only specifies the config name. This grants the container access to the config and mounts it as files into a service’s container’s filesystem. The location of the mount point within the container defaults to /<config_name> in Linux containers, and C:\<config-name> in Windows containers.

The following example uses the short syntax to grant the redis service access to the my_config and my_other_config configs. The value of my_config is set to the contents of the file ./my_config.txt, and my_other_config is defined as an external resource, which means that it has already been defined in the platform. If the external config does not exist, the deployment fails.

services:
  redis:
    image: redis:latest
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

Long syntax

The long syntax provides more granularity in how the config is created within the service's task containers.

  • source: The name of the config as it exists in the platform.
  • target: The path and name of the file to be mounted in the service's task containers. Defaults to /<source> if not specified.
  • uid and gid: The numeric UID or GID that owns the mounted config file within the service's task containers. Default value when not specified is USER running container.
  • mode: The permissions for the file that is mounted within the service's task containers, in octal notation. Default value is world-readable (0444). Writable bit must be ignored. The executable bit can be set.

The following example sets the name of my_config to redis_config within the 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.

services:
  redis:
    image: redis:latest
    configs:
      - source: my_config
        target: /redis_config
        uid: "103"
        gid: "103"
        mode: 0440
configs:
  my_config:
    external: true
  my_other_config:
    external: true

container_name

container_name is a string that specifies a custom container name, rather than a name generated by default.

container_name: my-web-container

Compose does not scale a service beyond one container if the Compose file specifies a container_name. Attempting to do so results in an error.

container_name follows the regex format of [a-zA-Z0-9][a-zA-Z0-9_.-]+

credential_spec

credential_spec configures the credential spec for a managed service account.

If you have services that use Windows containers, you can use file: and registry: protocols for credential_spec. Compose also supports additional protocols for custom use-cases.

The credential_spec must be in the format file://<filename> or registry://<value-name>.

credential_spec:
  file: my-credential-spec.json

When using registry:, the credential spec is read from the Windows registry on the daemon's host. A registry value with the given name must be located in:

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

The following example loads the credential spec from a value named my-credential-spec in the registry:

credential_spec:
  registry: my-credential-spec

Example gMSA configuration

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:

services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

configs:
  my_credentials_spec:
    file: ./my-credential-spec.json|

depends_on

depends_on expresses startup and shutdown dependencies between services.

Short syntax

The short syntax variant only specifies service names of the dependencies. Service dependencies cause the following behaviors:

  • Compose creates services in dependency order. In the following example, db and redis are created before web.

  • Compose removes services in dependency order. In the following example, web is removed before db and redis.

Simple example:

services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

Compose guarantees dependency services have been started before starting a dependent service. Compose waits for dependency services to be "ready" before starting a dependent service.

Long syntax

The long form syntax enables the configuration of additional fields that can't be expressed in the short form.

  • restart: When set to true Compose restarts this service after it updates the dependency service. This applies to an explicit restart controlled by a Compose operation, and excludes automated restart by the container runtime after the container dies. Compose v2.17.0

  • condition: Sets the condition under which dependency is considered satisfied

    • service_started: An equivalent of the short syntax described above
    • service_healthy: Specifies that a dependency is expected to be "healthy" (as indicated by healthcheck) before starting a dependent service.
    • service_completed_successfully: Specifies that a dependency is expected to run to successful completion before starting a dependent service.
  • required: When set to false Compose only warns you when the dependency service isn't started or available. If it's not defined the default value of required is true. Compose v2.20.0

Service dependencies cause the following behaviors:

  • Compose creates services in dependency order. In the following example, db and redis are created before web.

  • Compose waits for healthchecks to pass on dependencies marked with service_healthy. In the following example, db is expected to be "healthy" before web is created.

  • Compose removes services in dependency order. In the following example, web is removed before db and redis.

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres

Compose guarantees dependency services are started before starting a dependent service. Compose guarantees dependency services marked with service_healthy are "healthy" before starting a dependent service.

deploy

deploy specifies the configuration for the deployment and lifecycle of services, as defined in the Compose Deploy Specification.

develop

Compose v2.22.0

develop specifies the development configuration for maintaining a container in sync with source, as defined in the Development Section.

device_cgroup_rules

device_cgroup_rules defines a list of device cgroup rules for this container. The format is the same format the Linux kernel specifies in the Control Groups Device Whitelist Controller.

device_cgroup_rules:
  - 'c 1:3 mr'
  - 'a 7:* rmw'

devices

devices defines a list of device mappings for created containers in the form of HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS].

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm"

dns

dns defines custom DNS servers to set on the container network interface configuration. It can be a single value or a list.

dns: 8.8.8.8
dns:
  - 8.8.8.8
  - 9.9.9.9

dns_opt

dns_opt list custom DNS options to be passed to the container’s DNS resolver (/etc/resolv.conf file on Linux).

dns_opt:
  - use-vc
  - no-tld-query

dns_search

dns_search defines custom DNS search domains to set on container network interface configuration. It can be a single value or a list.

dns_search: example.com
dns_search:
  - dc1.example.com
  - dc2.example.com

domainname

domainname declares a custom domain name to use for the service container. It must be a valid RFC 1123 hostname.

entrypoint

entrypoint declares the default entrypoint for the service container. This overrides the ENTRYPOINT instruction from the service's Dockerfile.

If entrypoint is non-null, Compose ignores any default command from the image, for example the CMD instruction in the Dockerfile.

See also command to set or override the default command to be executed by the entrypoint process.

In its short form, the value can be defined as a string:

entrypoint: /code/entrypoint.sh

Alternatively, the value can also be a list, in a manner similar to the Dockerfile:

entrypoint:
  - php
  - -d
  - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
  - -d
  - memory_limit=-1
  - vendor/bin/phpunit

If the value is null, the default entrypoint from the image is used.

If the value is [] (empty list) or '' (empty string), the default entrypoint declared by the image is ignored, i.e. overridden to be empty.

env_file

env_file adds environment variables to the container based on the file content.

env_file: .env

env_file can also be a list. The files in the list are processed from the top down. For the same variable specified in two env files, the value from the last file in the list stands.

env_file:
  - ./a.env
  - ./b.env

List elements can also be declared as a mapping, which then lets you set an additional attribute required. This defaults to true. When required is set to false and the .env file is missing, Compose silently ignores the entry.

env_file:
  - path: ./default.env
    required: true # default
  - path: ./override.env
    required: false

Relative path are resolved from the Compose file's parent folder. As absolute paths prevent the Compose file from being portable, Compose warns you when such a path is used to set env_file.

Environment variables declared in the environment section override these values. This holds true even if those values are empty or undefined.

Env_file format

Each line in an .env file must be in VAR[=[VAL]] format. The following syntax rules apply:

  • Lines beginning with # are processed as comments and ignored.
  • Blank lines are ignored.
  • Unquoted and double-quoted (") values have Interpolation applied.
  • Each line represents a key-value pair. Values can optionally be quoted.
    • VAR=VAL -> VAL
    • VAR="VAL" -> VAL
    • VAR='VAL' -> VAL
  • Inline comments for unquoted values must be preceded with a space.
    • VAR=VAL # comment -> VAL
    • VAR=VAL# not a comment -> VAL# not a comment
  • Inline comments for quoted values must follow the closing quote.
    • VAR="VAL # not a comment" -> VAL # not a comment
    • VAR="VAL" # comment -> VAL
  • Single-quoted (') values are used literally.
    • VAR='$OTHER' -> $OTHER
    • VAR='${OTHER}' -> ${OTHER}
  • Quotes can be escaped with \.
    • VAR='Let\'s go!' -> Let's go!
    • VAR="{\"hello\": \"json\"}" -> {"hello": "json"}
  • Common shell escape sequences including \n, \r, \t, and \\ are supported in double-quoted values.
    • VAR="some\tvalue" -> some value
    • VAR='some\tvalue' -> some\tvalue
    • VAR=some\tvalue -> some\tvalue

VAL may be omitted, in such cases the variable value is an empty string. =VAL may be omitted, in such cases the variable is unset.

# Set Rails/Rack environment
RACK_ENV=development
VAR="quoted"

environment

environment defines environment variables set in the container. environment can use either an array or a map. Any boolean values; true, false, yes, no, should be enclosed in quotes to ensure they are not converted to True or False by the YAML parser.

Environment variables can be declared by a single key (no value to equals sign). In this case Compose relies on you to resolve the value. If the value is not resolved, the variable is unset and is removed from the service container environment.

Map syntax:

environment:
  RACK_ENV: development
  SHOW: "true"
  USER_INPUT:

Array syntax:

environment:
  - RACK_ENV=development
  - SHOW=true
  - USER_INPUT

When both env_file and environment are set for a service, values set by environment have precedence.

expose

expose defines the (incoming) port or a range of ports that Compose exposes from the container. These ports must be accessible to linked services and should not be published to the host machine. Only the internal container ports can be specified.

Syntax is <portnum>/[<proto>] or <startport-endport>/[<proto>] for a port range. When not explicitly set, tcp protocol is used.

expose:
  - "3000"
  - "8000"
  - "8080-8085/tcp

Note

If the Dockerfile for the image already exposes ports, it is visible to other containers on the network even if expose is not set in your Compose file.

extends

extends lets you share common configurations among different files, or even different projects entirely. With extends you can define a common set of service options in one place and refer to it from anywhere. You can refer to another Compose file and select a service you want to also use in your own application, with the ability to override some attributes for your own needs.

You can use extends on any service together with other configuration keys. The extends value must be a mapping defined with a required service and an optional file key.

extends:
  file: common.yml
  service: webapp
  • service: Defines the name of the service being referenced as a base, for example web or database.
  • file: The location of a Compose configuration file defining that service.

Restrictions

Service being referenced by extends can have dependency declared on other resources. Typically it can have an explicit volumes declaration. extends then will not import the target volume definition in the extending compose model, it is Compose file author responsibility to define an equivalent resource for the extended service to be consistent. Compose will check a resource with referenced ID exists in the Compose model

Dependencies on other resources in an extends target can be:

  • An explicit references by volumes, networks, configs, secrets, links, volumes_from or depends_on
  • A reference to another service using the service:{name} syntax in namespace declaration (ipc, pid, network_mode)

Circular references with extends are not supported, Compose returns an error when one is detected.

Finding referenced service

file value can be:

  • Not present. This indicates that another service within the same Compose file is being referenced.
  • File path, which can be either:
    • Relative path. This path is considered as relative to the location of the main Compose file.
    • Absolute path.

A service denoted by service must be present in the identified referenced Compose file. Compose returns an error if:

  • The service denoted by service is not found.
  • The Compose file denoted by file is not found.

Merging service definitions

Two service definitions, the main one in the current Compose file and the referenced one specified by extends, are merged in the following way:

  • Mappings: Keys in mappings of the main service definition override keys in mappings of the referenced service definition. Keys that aren't overridden are included as is.
  • Sequences: Items are combined together into a new sequence. The order of elements is preserved with the referenced items coming first and main items after.
  • Scalars: Keys in the main service definition take precedence over keys in the referenced one.

Mappings

The following keys should be treated as mappings: annotations, build.args, build.labels, build.extra_hosts, deploy.labels, deploy.update_config, deploy.rollback_config, deploy.restart_policy, deploy.resources.limits, environment, healthcheck, labels, logging.options, sysctls, storage_opt, extra_hosts, ulimits.

One exception that applies to healthcheck is that the main mapping cannot specify disable: true unless the referenced mapping also specifies disable: true. Compose returns an error in this case.

For example, the input below:

services:
  common:
    image: busybox
    environment:
      TZ: utc
      PORT: 80
  cli:
    extends:
      service: common
    environment:
      PORT: 8080

Produces the following configuration for the cli service. The same output is produced if array syntax is used.

environment:
  PORT: 8080
  TZ: utc
image: busybox

Items under blkio_config.device_read_bps, blkio_config.device_read_iops, blkio_config.device_write_bps, blkio_config.device_write_iops, devices and volumes are also treated as mappings where key is the target path inside the container.

For example, the input below:

services:
  common:
    image: busybox
    volumes:
      - common-volume:/var/lib/backup/data:rw
  cli:
    extends:
      service: common
    volumes:
      - cli-volume:/var/lib/backup/data:ro

Produces the following configuration for the cli service. Note that the mounted path now points to the new volume name and ro flag was applied.

image: busybox
volumes:
- cli-volume:/var/lib/backup/data:ro

If the referenced service definition contains extends mapping, the items under it are simply copied into the new merged definition. The merging process is then kicked off again until no extends keys are remaining.

For example, the input below:

services:
  base:
    image: busybox
    user: root
  common:
    image: busybox
    extends:
      service: base
  cli:
    extends:
      service: common

Produces the following configuration for the cli service. Here, cli services gets user key from common service, which in turn gets this key from base service.

image: busybox
user: root

Sequences

The following keys should be treated as sequences: cap_add, cap_drop, configs, deploy.placement.constraints, deploy.placement.preferences, deploy.reservations.generic_resources, device_cgroup_rules, expose, external_links, ports, secrets, security_opt. Any duplicates resulting from the merge are removed so that the sequence only contains unique elements.

For example, the input below:

services:
  common:
    image: busybox
    security_opt:
      - label:role:ROLE
  cli:
    extends:
      service: common
    security_opt:
      - label:user:USER

Produces the following configuration for the cli service.

image: busybox
security_opt:
- label:role:ROLE
- label:user:USER

In case list syntax is used, the following keys should also be treated as sequences: dns, dns_search, env_file, tmpfs. Unlike sequence fields mentioned above, duplicates resulting from the merge are not removed.

Scalars

Any other allowed keys in the service definition should be treated as scalars.

annotations

annotations defines annotations for the container. annotations can use either an array or a map.

annotations:
  com.example.foo: bar
annotations:
  - com.example.foo=bar

external_links

external_links link service containers to services managed outside of your Compose application. 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.

external_links:
  - redis
  - database:mysql
  - database:postgresql

extra_hosts

extra_hosts adds hostname mappings to the container network interface configuration (/etc/hosts for Linux).

Short syntax

Short syntax uses plain strings in a list. Values must set hostname and IP address for additional hosts in the form of HOSTNAME=IP.

extra_hosts:
  - "somehost=162.242.195.82"
  - "otherhost=50.31.209.229"
  - "myhostv6=::1"

IPv6 addresses can be enclosed in square brackets, for example:

extra_hosts:
  - "myhostv6=[::1]"

The separator = is preferred Compose v2.24.1 but : can also be used. For example:

extra_hosts:
  - "somehost:162.242.195.82"
  - "myhostv6:::1"

Long syntax

Alternatively, extra_hosts can be set as a mapping between hostname(s) and IP(s)

extra_hosts:
  somehost: "162.242.195.82"
  otherhost: "50.31.209.229"
  myhostv6: "::1"

Compose creates a matching entry with the IP address and hostname in the container's network configuration, which means for Linux /etc/hosts get extra lines:

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

group_add

group_add specifies additional groups, by name or number, which the user inside the container must be a member of.

An example of where this is useful is when multiple containers (running as different users) need to all read or write 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.

services:
  myservice:
    image: alpine
    group_add:
      - mail

Running id inside the created container must show that the user belongs to the mail group, which would not have been the case if group_add were not declared.

healthcheck

healthcheck declares a check that's run to determine whether or not the service containers are "healthy". It works in the same way, and has the same default values, as the HEALTHCHECK Dockerfile instruction set by the service's Docker image. Your Compose file can override the values set in the Dockerfile.

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s
  start_interval: 5s

interval, timeout, start_period, and start_interval Compose v2.20.2 are specified as durations.

test defines the command Compose runs to check container health. It can be 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.

# Hit the local web app
test: ["CMD", "curl", "-f", "http://localhost"]

Using CMD-SHELL runs the command configured as a string using the container's default shell (/bin/sh for Linux). Both forms below are equivalent:

test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
test: curl -f https://localhost || exit 1

NONE disables the healthcheck, and is mostly useful to disable the Healthcheck Dockerfile instruction set by the service's Docker image. Alternatively, the healthcheck set by the image can be disabled by setting disable: true:

healthcheck:
  disable: true

hostname

hostname declares a custom host name to use for the service container. It must be a valid RFC 1123 hostname.

image

image specifies the image to start the container from. image must follow the Open Container Specification addressable image format, as [<registry>/][<project>/]<image>[:<tag>|@<digest>].

    image: redis
    image: redis:5
    image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
    image: library/redis
    image: docker.io/library/redis
    image: my_private.registry:5000/redis

If the image does not exist on the platform, Compose attempts to pull it based on the pull_policy. If you are also using the Compose Build Specification, there are alternative options for controlling the precedence of pull over building the image from source, however pulling the image is the default behavior.

image may be omitted from a Compose file as long as a build section is declared. If you are not using the Compose Build Specification, Compose won't work if image is missing from the Compose file.

init

init runs 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.

services:
  web:
    image: alpine:latest
    init: true

The init binary that is used is platform specific.

ipc

ipc configures the IPC isolation mode set by the service container. Available values are platform specific, but Compose defines specific values which must be implemented as described if supported:

  • shareable: Gives the container its own private IPC namespace, with a possibility to share it with other containers.
  • service:{name}: Makes the container join another container's (shareable) IPC namespace.
    ipc: "shareable"
    ipc: "service:[service name]"

uts

Compose v2.15.1

uts configures the UTS namespace mode set for the service container. When unspecified it is the runtime's decision to assign a UTS namespace, if supported. Available values are:

  • 'host': Results in the container using the same UTS namespace as the host.
    uts: "host"

isolation

isolation specifies a container’s isolation technology. Supported values are platform specific.

labels

labels add metadata to containers. You can use either an array or a map.

It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software.

labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""
labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

Compose creates containers with canonical labels:

  • com.docker.compose.project set on all resources created by Compose to the user project name
  • com.docker.compose.service set on service containers with service name as defined in the Compose file

The com.docker.compose label prefix is reserved. Specifying labels with this prefix in the Compose file results in a runtime error.

links

Note

Availability of the links attribute is implementation specific.

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.

web:
  links:
    - db
    - db:database
    - redis

Containers for the linked service are reachable at a hostname identical to the alias, or the service name if no alias is specified.

Links are not required to enable services to communicate. When no specific network configuration is set, any service is able to reach any other service at that service’s name on the default network. If services do declare networks they are attached to, links does not override the network configuration and services not attached to a shared network are not be able to communicate. Compose doesn't warn you about a configuration mismatch.

Links also express implicit dependency between services in the same way as depends_on, so they determine the order of service startup.

logging

logging defines the logging configuration for the service.

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

The driver name specifies a logging driver for the service's containers. The default and available values are platform specific. Driver specific options can be set with options as key-value pairs.

network_mode

network_mode sets a service container's network mode. Available values are platform specific, but Compose defines specific values which must be implemented as described if supported:

  • none: Turns off all container networking.
  • host: Gives the container raw access to the host's network interface.
  • service:{name}: Gives the containers access to the specified service only.
    network_mode: "host"
    network_mode: "none"
    network_mode: "service:[service name]"

When set, the networks attribute is not allowed and Compose rejects any Compose file containing both attributes.

networks

networks defines the networks that service containers are attached to, referencing entries under the top-level networks key.

services:
  some-service:
    networks:
      - some-network
      - other-network

aliases

aliases declares alternative hostnames for the service on the network. Other containers on the same network can use either the service name or an alias to connect to one of the service's containers.

Since aliases are network-scoped, the same service can have different aliases on different networks.

Note A network-wide alias can be shared by multiple containers, and even by multiple services. If it is, then exactly which container the name resolves to is not guaranteed.

services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2

In the following example, service frontend is able to reach the backend service at the hostname backend or database on the back-tier network. The service monitoring is able to reach same backend service at backend or mysql on the admin network.

services:
  frontend:
    image: example/webapp
    networks:
      - front-tier
      - back-tier

  monitoring:
    image: example/monitoring
    networks:
      - admin

  backend:
    image: example/backend
    networks:
      back-tier:
        aliases:
          - database
      admin:
        aliases:
          - mysql

networks:
  front-tier:
  back-tier:
  admin:

ipv4_address, ipv6_address

Specify a static IP address for a service container when joining the network.

The corresponding network configuration in the top-level networks section must have an ipam attribute with subnet configurations covering each static address.

services:
  frontend:
    image: example/webapp
    networks:
      front-tier:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  front-tier:
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"
        - subnet: "2001:3984:3989::/64"

link_local_ips

link_local_ips specifies a list of link-local IPs. Link-local IPs are special IPs which belong to a well known subnet and are purely managed by the operator, usually dependent on the architecture where they are deployed. Implementation is platform specific.

Example:

services:
  app:
    image: busybox
    command: top
    networks:
      app_net:
        link_local_ips:
          - 57.123.22.11
          - 57.123.22.13
networks:
  app_net:
    driver: bridge

mac_address

mac_address sets the MAC address used by the service container when connecting to this particular network.

driver_opts

unreleased

driver_opts specifies a list of options as key-value pairs to pass to the driver. These options are driver-dependent. Consult the driver's documentation for more information.

services:
  app:
    networks:
      app_net:
        driver_opts:
          foo: "bar"
          baz: 1

priority

priority indicates in which order Compose connects the service’s containers to its networks. If unspecified, the default value is 0.

In the following example, the app service connects to app_net_1 first as it has the highest priority. It then connects to app_net_3, then app_net_2, which uses the default priority value of 0.

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
        priority: 1000
      app_net_2:

      app_net_3:
        priority: 100
networks:
  app_net_1:
  app_net_2:
  app_net_3:

mac_address

Compose v2.23.2

mac_address sets a MAC address for the service container.

Note Container runtimes might reject this value (ie. Docker Engine >= v25.0). In that case, you should use networks.mac_address instead.

mem_limit

mem_limit configures a limit on the amount of memory a container can allocate, set as a string expressing a byte value.

When both are set, mem_limit must be consistent with the limits.memory attribute in the Deploy Specification

mem_reservation

mem_reservation configures a reservation on the amount of memory a container can allocate, set as a string expressing a byte value.

When both are set, mem_reservation must be consistent with the reservations.memory attribute in the Deploy Specification

mem_swappiness

mem_swappiness defines as a percentage, a value between 0 and 100, for the host kernel to swap out anonymous memory pages used by a container.

  • 0: Turns off anonymous page swapping.
  • 100: Sets all anonymous pages as swappable.

The default value is platform specific.

memswap_limit

memswap_limit defines the amount of memory the container is allowed to swap to disk. This is a modifier attribute that only has meaning if memory is also set. Using swap lets the container write excess memory requirements to disk when the container has exhausted all the memory that is available to it. There is a performance penalty for applications that swap memory to disk often.

  • If memswap_limit is set to a positive integer, then both memory and memswap_limit must be set. memswap_limit represents the total amount of memory and swap that can be used, and memory controls the amount used by non-swap memory. So if memory="300m" and memswap_limit="1g", the container can use 300m of memory and 700m (1g - 300m) swap.
  • If memswap_limit is set to 0, the setting is ignored, and the value is treated as unset.
  • If memswap_limit is set to the same value as memory, and memory is set to a positive integer, the container does not have access to swap.
  • If memswap_limit is unset, and memory is set, the container can use as much swap as the memory setting, if the host container has swap memory configured. For instance, if memory="300m" and memswap_limit is not set, the container can use 600m in total of memory and swap.
  • If memswap_limit is explicitly set to -1, the container is allowed to use unlimited swap, up to the amount available on the host system.

oom_kill_disable