Workload specification

A workload specification defines the attributes of an orchestrated workload — a service or a job — beyond the configuration of its containers, which is defined by the Container specification: how its image is built, how it is wired to other workloads, and how the platform assesses and exposes it.

These attributes apply to services and jobs, but not to other container-based elements such as pre_start init containers.

build

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

depends_on

depends_on expresses startup and shutdown dependencies between services.

Declared on a service, depends_on can only reference other services: a service cannot depend on a job. Declared on a job, depends_on can reference both services and other jobs.

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.

• 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.

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.

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.

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 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

ports

Exposes container ports.

Note

Port mapping must not be used with network_mode: host. Doing so causes a runtime error because network_mode: host already exposes container ports directly to the host network, so port mapping isn’t needed.

Short syntax

The short syntax is a colon-separated string to set the host IP, host port, and container port in the form:

[HOST:]CONTAINER[/PROTOCOL] where:

• HOST is [IP:](port | range) (optional). If it is not set, it binds to all network interfaces (0.0.0.0).
• CONTAINER is port | range.
• PROTOCOL restricts ports to a specified protocol either tcp or upd(optional). Default is tcp. Compose offers support for platform-specific protocol names.

Ports can be either a single value or a range. HOST and CONTAINER must use equivalent ranges.

You can either specify both ports (HOST:CONTAINER), or just the container port. In the latter case, the container runtime automatically allocates any unassigned port of the host.

HOST:CONTAINER should always be specified as a (quoted) string, to avoid conflicts with yaml base-60 float.

IPv6 addresses can be enclosed in square brackets.

Examples:

ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "8000-9000:80"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "::1:6000:6000"   
  - "[::1]:6001:6001" 
  - "6060:6060/udp"

Note

If host IP mapping is not supported by a container engine, Compose rejects the Compose file and ignores the specified host IP.

Long syntax

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

• target: The container port.
• published: The publicly exposed port. It is defined as a string and can be set as a range using syntax start-end. It means the actual port is assigned a remaining available port, within the set range.
• host_ip: The host IP mapping. If it is not set, it binds to all network interfaces (0.0.0.0).
• protocol: The port protocol (tcp or udp). Defaults to tcp.
• app_protocol: The application procotol (TCP/IP level 4 / OSI level 7) this port is used for. This is optional and can be used as a hint for Compose to offer richer behavior for protocols that it understands.
• mode: host: For publishing a host port on each node, or ingress for a port to be load balanced. Defaults to ingress.
• name: A human-readable name for the port, used to document its usage within the service

ports:
  - name: web
    target: 80
    host_ip: 127.0.0.1
    published: "8080"
    protocol: tcp
    app_protocol: http
    mode: host    

  - name: web-secured
    target: 443
    host_ip: 127.0.0.1
    published: "8083-9000"
    protocol: tcp
    app_protocol: https
    mode: host

stdin_open

stdin_open configures a service containers to run with an allocated stdin.

tty

tty configures service container to run with a TTY.