Update Compose file reference for version 3

Signed-off-by: Aanand Prasad <aanand.prasad@gmail.com>

compose/compose-file.md

@@ -30,10 +30,9 @@ full details.
 
 ## Service configuration reference
 
-> **Note:** There are several versions of the Compose file format – version 1
+> **Note:** There are several versions of the Compose file format – 1, 2, 2.1
-> (the legacy format, which does not support volumes or networks) and
+> and 3. For more information, see the [Versioning](compose-file.md#versioning)
-> version 2, as well as 2.1 (the most up-to-date). For more information,
+> section.
-> see the [Versioning](compose-file.md#versioning) section.
 
 This section contains a list of all configuration options supported by a service
 definition.
@@ -187,6 +186,124 @@ Because Docker container names must be unique, you cannot scale a service
 beyond 1 container if you have specified a custom name. Attempting to do so
 results in an error.
 
+### deploy
+
+> **[Version 3](compose-file.md#version-3) only.**
+
+Specify configuration related to the deployment and running of services. This
+only takes effect when deploying to a [swarm](/engine/swarm/index.md) with
+[`docker stack deploy`](/engine/reference/commandline/stack_deploy.md), and is
+ignored by `docker-compose up` and `docker-compose run`.
+
+    deploy:
+      replicas: 6
+      update_config:
+        parallelism: 2
+        delay: 10s
+      restart_policy:
+        condition: on-failure
+
+Several sub-options are available:
+
+#### mode
+
+Either `global` (exactly one container per swarm node) or `replicated` (a
+specified number of containers). The default is `replicated`.
+
+    mode: global
+
+#### replicas
+
+If the service is `replicated` (which is the default), specify the number of
+containers that should be running at any given time.
+
+    mode: replicated
+    replicas: 6
+
+#### placement
+
+Specify placement constraints. For a full description of the syntax and
+available types of constraints, see the
+[docker service create](engine/reference/commandline/service_create.md#specify-service-constraints-constraint)
+documentation.
+
+    placement:
+      constraints:
+        - node.role == manager
+        - engine.labels.operatingsystem == ubuntu 14.04
+
+#### 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` or `pause`
+  (default: `pause`).
+- `monitor`: TODO
+- `max_failure_ratio`: TODO
+
+    update_config:
+      parallelism: 2
+      delay: 10s
+
+#### resources
+
+Configures resource constraints. This replaces the older resource constraint
+options in Compose files prior to version 3 (`cpu_shares`, `cpu_quota`,
+`cpuset`, `mem_limit`, `memswap_limit`).
+
+    resources:
+      limits:
+        cpus: '0.001'
+        memory: 50M
+      reservations:
+        cpus: '0.0001'
+        memory: 20M
+
+#### restart_policy
+
+Configures if and how to restart containers when they exit. Replaces
+[`restart`](compose-file.md#restart).
+
+- `condition`: One of `none`, `on-failure` or `any` (default: `any`).
+- `delay`: How long to wait between restart attempts, specified as a
+  [duration](compose-file.md#specifying-durations) (default: 0).
+- `max_attempts`: How many times to attempt to restart a container before giving
+  up (default: never give up).
+- `window`: How long to wait before deciding if a restart has succeeded,
+  specified as a [duration](compose-file.md#specifying-durations) (default:
+  decide immediately).
+
+    restart_policy:
+      condition: on-failure
+      delay: 5s
+      max_attempts: 3
+      window: 120s
+
+#### labels
+
+Specify labels for the service. These labels will *only* be set on the service,
+and *not* on any containers for the service.
+
+    version: "3"
+    services:
+      web:
+        image: web
+        deploy:
+          labels:
+            com.example.description: "This label will appear on the web service"
+
+To set labels on containers instead, use the `labels` key outside of `deploy`:
+
+    version: "3"
+    services:
+      web:
+        image: web
+        labels:
+          com.example.description: "This label will appear on all containers for the web service"
+
 ### devices
 
 List of device mappings.  Uses the same format as the `--device` docker
@@ -415,6 +532,41 @@ Running `id` inside the created container will show that the user belongs to
 the `mail` group, which would not have been the case if `group_add` were not
 used.
 
+### healthcheck
+
+> [Version 3 file format](compose-file.md#version-3) and up.
+
+Configure a check that's run to determine whether or not containers for this
+service are "healthy". See the docs for the
+[HEALTHCHECK Dockerfile instruction](/engine/reference/builder.md#healthcheck)
+for details on how healthchecks work.
+
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost"]
+      interval: 1m30s
+      timeout: 10s
+      retries: 3
+
+`interval` and `timeout` are specified as
+[durations](compose-file.md#specifying-durations).
+
+`test` must 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"]
+
+    # As above, but wrapped in /bin/sh. Both forms below are equivalent.
+    test: ["CMD-SHELL", "curl -f http://localhost && echo 'cool, it works'"]
+    test: curl -f https://localhost && echo 'cool, it works'
+
+To disable any default healthcheck set by the image, you can use `disable:
+true`. This is equivalent to specifying `test: ["NONE"]`.
+
+    healthcheck:
+      disable: true
+
 ### image
 
 Specify the image to start the container from. Can either be a repository/tag or
@@ -717,6 +869,19 @@ Override the default labeling scheme for each container.
       - label:user:USER
       - label:role:ROLE
 
+### stop_grace_period
+
+Specify how to long to wait when attempting to stop a container if it doesn't
+handle SIGTERM (or whatever stop signal has been specified with
+[`stop_signal`](compose-file.md#stop_signal)), before sending SIGKILL. Specified
+as a [duration](compose-file.md#specifying-durations).
+
+    stop_grace_period: 1s
+    stop_grace_period: 1m30s
+
+By default, `stop` waits 10 seconds for the container to exit before sending
+SIGKILL.
+
 ### stop_signal
 
 Sets an alternative signal to stop the container. By default `stop` uses
@@ -770,20 +935,39 @@ If you do not use a host path, you may specify a `volume_driver`.
 
     volume_driver: mydriver
 
-Note that for [version 2 files](compose-file.md#version-2), this driver
+There are several things to note, depending on which
-will not apply to named volumes (you should use the `driver` option when
+[Compose file version](compose-file.md#versioning) you're using:
-[declaring the volume](compose-file.md#volume-configuration-reference) instead).
-For [version 1](compose-file.md#version-1), both named volumes and container volumes will
-use the specified driver.
 
-> Note: No path expansion will be done if you have also specified a
+-   `volume_driver` is not supported at all in
-> `volume_driver`.
+    [version 3](compose-file.md#version-3). Instead of setting the volume driver
+    on the service, define a volume using the
+    [top-level `volumes` option](compose-file.md#volume-configuration-reference)
+    and specify the driver there.
+
+-   You can use `volume_driver` in [version 2 files](compose-file.md#version-2),
+    but it will only apply to anonymous volumes (those specified in the image,
+    or specified under `volumes` without an explicit named volume or host path).
+    To configure the driver for a named volume, use the `driver` key under the
+    entry in the
+    [top-level `volumes` option](compose-file.md#volume-configuration-reference).
+
+-   For [version 1 files](compose-file.md#version-1), both named volumes and
+    container volumes will use the specified driver.
+
+-   No path expansion will be done if you have also specified a `volume_driver`.
+    For example, if you specify a mapping of `./foo:/data`, the `./foo` part
+    will be passed straight to the volume driver without being expanded.
 
 See [Docker Volumes](/engine/userguide/dockervolumes.md) and
-[Volume Plugins](/engine/extend/plugins_volume.md) for more
+[Volume Plugins](/engine/extend/plugins_volume.md) for more information.
 
 ### volumes_from
 
+> **Removed in [version 3](compose-file.md#version-3).** The best way to share a
+> volume between services is to use the top-level
+> [`volumes` option](compose-file.md#version-configuration-reference) to define
+> a named volume and reference it from each service's `volumes` list.
+
 Mount all of the volumes from another service or container, optionally
 specifying read-only access (``ro``) or read-write (``rw``). If no access level is specified,
 then read-write will be used.
@@ -805,6 +989,13 @@ then read-write will be used.
 
 ### cpu\_shares, cpu\_quota, cpuset, domainname, hostname, ipc, mac\_address, mem\_limit, memswap\_limit, oom_score_adj, privileged, read\_only, restart, shm\_size, stdin\_open, tty, user, working\_dir
 
+> **Note:** Resource constraint options (`cpu_shares`, `cpu_quota`, `cpuset`,
+> `mem_limit`, `memswap_limit`) have been removed in
+> [version 3](compose-file.md#version-3). You should set resource constraints
+> with [deploy.resources](compose-file.md#resources) instead. Note that `deploy`
+> configuration only takes effect when using `docker stack deploy`, and is
+> ignored by `docker-compose`.
+
 Each of these is a single value, analogous to its
 [docker run](/engine/reference/run.md) counterpart.
 
@@ -838,6 +1029,21 @@ Each of these is a single value, analogous to its
 > * `oom_score_adj`
 
 
+## Specifying durations
+
+Some configuration options, such as the `interval` and `timeout` sub-options for
+[`healthcheck`](compose-file.md#healthcheck), accept a duration as a string in a
+format that looks like this:
+
+    2.5s
+    10s
+    1m30s
+    2h32m
+    5h34m56s
+
+The supported units are `us`, `ms`, `s`, `m` and `h`.
+
+
 ## Volume configuration reference
 
 While it is possible to declare volumes on the fly as part of the service
@@ -847,10 +1053,35 @@ easily retrieved and inspected using the docker command line or API.
 See the [docker volume](/engine/reference/commandline/volume_create.md)
 subcommand documentation for more information.
 
+Here's an example of a two-service setup where a database's data directory is
+shared with another service as a volume so that it can be periodically backed
+up:
+
+    version: "3"
+
+    services:
+      db:
+        image: db
+        volumes:
+          - data-volume:/var/lib/db
+      backup:
+        image: backup-service
+        volumes:
+          - data-volume:/var/lib/backup/data
+
+    volumes:
+      data-volume:
+
+An entry under the top-level `volumes` key can be empty, in which case it will
+use the default driver configured by the Engine (in most cases, this is the
+`local` driver). Optionally, you can configure it with the following keys:
+
 ### driver
 
-Specify which volume driver should be used for this volume. Defaults to
+Specify which volume driver should be used for this volume. Defaults to whatever
-`local`. The Docker Engine will return an error if the driver is not available.
+driver the Docker Engine has been configured to use, which in most cases is
+`local`. If the driver is not available, the Engine will return an error when
+`docker-compose up` tries to create the volume.
 
      driver: foobar
 
@@ -1051,23 +1282,26 @@ refer to it within the Compose file:
 
 ## Versioning
 
-There are currently three versions of the Compose file format:
+There are currently four versions of the Compose file format:
 
 - Version 1, the legacy format. This is specified by omitting a `version` key at
   the root of the YAML.
-- Version 2, the recommended format. This is specified with a `version: '2'` entry
+- Version 2. This is specified with a `version: '2'` entry at the root of the
-  at the root of the YAML.
+  YAML.
-- Version 2.1, an upgrade over version 2 that takes advantage of the Docker
+- Version 2.1, an upgrade over version 2 that takes advantage of newer Docker
-  Engine's newest features. Specify with a `version: '2.1'` entry at the root of
+  Engine features. Specify with a `version: '2.1'` entry at the root of
   the YAML.
+- Version 3, the latest and recommended version, designed to be cross-compatible
+  between Compose and the Docker Engine's [swarm mode](/engine/swarm/index.md).
 
-To move your project from version 1 to 2, see the [Upgrading](compose-file.md#upgrading)
+To move your project to a later version, see the
-section.
+[Upgrading](compose-file.md#upgrading) section.
 
 > **Note:** If you're using
 > [multiple Compose files](extends.md#different-environments) or
 > [extending services](extends.md#extending-services), each file must be of the
-> same version - you cannot mix version 1 and 2 in a single project.
+> same version - you cannot, for example, mix version 1 and 2 in a single
+> project.
 
 Several things differ depending on which version you use:
 
@@ -1091,6 +1325,11 @@ Version 1 files cannot declare named
 [volumes](compose-file.md#volume-configuration-reference), [networks](networking.md) or
 [build arguments](compose-file.md#args).
 
+Compose does not take advantage of [networking](networking.md) when you use
+version 1: every container is placed on the default `bridge` network and is
+reachable from every other container at its IP address. You will need to use
+[links](compose-file.md#links) to enable discovery between containers.
+
 Example:
 
     web:
@@ -1118,6 +1357,11 @@ Named [volumes](compose-file.md#volume-configuration-reference) can be declared
 `volumes` key, and [networks](compose-file.md#network-configuration-reference) can be declared
 under the `networks` key.
 
+By default, every container joins an application-wide default network, and is
+discoverable at a hostname that's the same as the service name. This means
+[links](compose-file.md#links) are largely unnecessary. For more details, see
+[Networking in Compose](networking.md).
+
 Simple example:
 
     version: '2'
@@ -1172,8 +1416,54 @@ Introduces the following additional parameters:
 - `labels` for [volumes](compose-file.md#volume-configuration-reference) and
   [networks](compose-file.md#network-configuration-reference)
 
+### Version 3
+
+Designed to be cross-compatible between Compose and the Docker Engine's
+[swarm mode](/engine/swarm/index.md), version 3 removes several options and adds
+several more.
+
+- Removed: `volume_driver`, `volumes_from`, `cpu_shares`, `cpu_quota`, `cpuset`,
+  `mem_limit`, `memswap_limit`. See the [upgrading](compose-file.md#upgrading)
+  guide for how to migrate away from these.
+
+- Added: [deploy](compose-file.md#deploy),
+  [healthcheck](compose-file.md#healthcheck),
+  [stop_grace_period](compose-file.md#stop-grace-period).
+
 ### Upgrading
 
+#### Version 2.x to 3.x
+
+Between versions 2.x and 3.x, the structure of the Compose file is the same, but
+several options have been removed:
+
+-   `volume_driver`: Instead of setting the volume driver on the service, define
+    a volume using the
+    [top-level `volumes` option](compose-file.md#volume-configuration-reference)
+    and specify the driver there.
+
+        version: "3"
+        services:
+          db:
+            image: postgres
+            volumes:
+              - data:/var/lib/postgresql/data
+        volumes:
+          data:
+            driver: mydriver
+
+-   `volumes_from`: To share a volume between services, define it using the
+    [top-level `volumes` option](compose-file.md#volume-configuration-reference)
+    and reference it from each service that shares it using the
+    [service-level `volumes` option](compose-file.md#volumes-volume-driver).
+
+-   `cpu_shares`, `cpu_quota`, `cpuset`, `mem_limit`, `memswap_limit`: These
+    have been replaced by the [resources](compose-file.md#resources) key under
+    `deploy`. Note that `deploy` configuration only takes effect when using
+    `docker stack deploy`, and is ignored by `docker-compose`.
+
+#### Version 1 to 2.x
+
 In the majority of cases, moving from version 1 to 2 is a very simple process:
 
 1. Indent the whole file by one level and put a `services:` key at the top.