From 355871289467565de7bf7b6a0c6e3458b3bc5af0 Mon Sep 17 00:00:00 2001 From: Victoria Bialas Date: Wed, 26 Jul 2017 10:33:46 -0700 Subject: [PATCH] added endpoint_mode topic for Compose file v3.3 (#3982) * added endpoint_mode topic for Compose file v3.3 Signed-off-by: Victoria Bialas * incorporated review comments re: features and versioning Signed-off-by: Victoria Bialas --- compose/compose-file/compose-versioning.md | 9 +- compose/compose-file/index.md | 177 ++++++++++++++------- 2 files changed, 125 insertions(+), 61 deletions(-) diff --git a/compose/compose-file/compose-versioning.md b/compose/compose-file/compose-versioning.md index 28939c56e2..a664e84302 100644 --- a/compose/compose-file/compose-versioning.md +++ b/compose/compose-file/compose-versioning.md @@ -189,7 +189,7 @@ between services and startup order. An upgrade of [version 2](#version-2) that introduces new parameters only available with Docker Engine version **1.12.0+**. Version 2.1 files are -supported by **Compose 1.9.0+** +supported by **Compose 1.9.0+**. Introduces the following additional parameters: @@ -229,14 +229,15 @@ the [upgrading](#upgrading) guide for how to migrate away from these. ### Version 3.3 -An upgrade of [version 3](#version-3) that introduces new parameters only available -with Docker Engine version **17.06.0+** +An upgrade of [version 3](#version-3) that introduces new parameters only +available with Docker Engine version **17.06.0+**, and higher. Introduces the following additional parameters: - [build `labels`](index.md#build) -- [`credential_spec`](index.md#credential_spec) +- [`credential_spec`](index.md#credentialspec) - [`configs`](index.md#configs) +- [deploy `endpoint_mode`](index.md#endpointmode) ## Upgrading diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md index ae52995665..7891dc6336 100644 --- a/compose/compose-file/index.md +++ b/compose/compose-file/index.md @@ -382,6 +382,91 @@ ignored by `docker-compose up` and `docker-compose run`. Several sub-options are available: +#### endpoint_mode + +Specify a service discovery method for external clients connecting to a swarm. + +> **[Version 3.3](compose-versioning.md#version-3) only.** + +* `endpoint_mode: vip` - Docker assigns the service a virtual IP (VIP), +which acts as the “front end” for clients to reach the service on a +network. Docker routes requests between the client and available worker +nodes for the service, without client knowledge of how many nodes +are participating in the service or their IP addresses or ports. +(This is the default.) + +* `endpoint_mode: dnsrr` - DNS round-robin (DNSRR) service discovery does +not use a single virtual IP. Docker sets up DNS entries for the service +such that a DNS query for the service name returns a list of IP addresses, +and the client connects directly to one of these. DNS round-robin is useful +in cases where you want to use your own load balancer, or for Hybrid +Windows and Linux applications. + + version: "3.3" + services: + + wordpress: + image: wordpress + ports: + - 8080:80 + networks: + - overlay + deploy: + mode: replicated + replicas: 2 + endpoint_mode: vip + + mysql: + image: mysql + volumes: + - db-data:/var/lib/mysql/data + networks: + - overlay + deploy: + mode: replicated + replicas: 2 + endpoint_mode: dnsrr + + volumes: + db-data: + + networks: + overlay: + +The options for `endpoint_mode` also work as flags on the swarm mode CLI command +[docker service create](/engine/reference/commandline/service_create.md). For a +quick list of all swarm related `docker` commands, see [Swarm mode CLI +commands](/engine/swarm.md#swarm-mode-key-concepts-and-tutorial). + +To learn more about service discovery and networking in swarm mode, see +[Configure service +discovery](/engine/swarm/networking.md#configure-service-discovery) in the swarm +mode topics. + + +#### 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" + + #### mode Either `global` (exactly one container per swarm node) or `replicated` (a @@ -398,22 +483,6 @@ in the [swarm](/engine/swarm/) topics.) deploy: 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. - - version: '3' - services: - worker: - image: dockersamples/examplevotingapp_worker - networks: - - frontend - - backend - deploy: - mode: replicated - replicas: 6 - #### placement Specify placement constraints. For a full description of the syntax and @@ -431,31 +500,21 @@ documentation. - node.role == manager - engine.labels.operatingsystem == ubuntu 14.04 -#### update_config +#### replicas -Configures how the service should be updated. Useful for configuring rolling -updates. +If the service is `replicated` (which is the default), specify the number of +containers that should be running at any given time. -- `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`: 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. - -```none -version: '3' -services: - vote: - image: dockersamples/examplevotingapp_vote:before - depends_on: - - redis - deploy: - replicas: 2 - update_config: - parallelism: 2 - delay: 10s -``` + version: '3' + services: + worker: + image: dockersamples/examplevotingapp_worker + networks: + - frontend + - backend + deploy: + mode: replicated + replicas: 6 #### resources @@ -518,27 +577,31 @@ services: window: 120s ``` -#### labels +#### update_config -Specify labels for the service. These labels will *only* be set on the service, -and *not* on any containers for the service. +Configures how the service should be updated. Useful for configuring rolling +updates. - version: "3" - services: - web: - image: web - deploy: - labels: - com.example.description: "This label will appear on the web service" +- `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`: 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. -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" +```none +version: '3' +services: + vote: + image: dockersamples/examplevotingapp_vote:before + depends_on: + - redis + deploy: + replicas: 2 + update_config: + parallelism: 2 + delay: 10s +``` #### Not supported for `docker stack deploy`