Publish Canary application instances

Estimated reading time: 3 minutes

This topic applies to Docker Enterprise.

The Docker Enterprise platform business, including products, customers, and employees, has been acquired by Mirantis, inc., effective 13-November-2019. For more information on the acquisition and how it may affect you and your business, refer to the Docker Enterprise Customer FAQ.

The following example publishes a service as a canary instance.

First, create an overlay network to isolate and secure service traffic:

$> docker network create -d overlay demo

Next, create the initial service:

$> docker service create \
    --name demo-v1 \
    --network demo \
    --detach=false \
    --replicas=4 \
    --label \
    --label \
    --env METADATA="demo-version-1" \

Interlock detects when the service is available and publishes it. After tasks are running and the proxy service is updated, the application is available via http://demo.local:

$> curl -vs -H "Host: demo.local"
*   Trying
* Connected to demo.local ( port 80 (#0)
> GET /ping HTTP/1.1
> Host: demo.local
> User-Agent: curl/7.54.0
> Accept: */*
< HTTP/1.1 200 OK
< Server: nginx/1.13.6
< Date: Wed, 08 Nov 2017 20:28:26 GMT
< Content-Type: text/plain; charset=utf-8
< Content-Length: 120
< Connection: keep-alive
< Set-Cookie: session=1510172906715624280; Path=/; Expires=Thu, 09 Nov 2017 20:28:26 GMT; Max-Age=86400
< x-request-id: f884cf37e8331612b8e7630ad0ee4e0d
< x-proxy-id: 5ad7c31f9f00
< x-server-info: interlock/2.0.0-development (147ff2b1) linux/amd64
< x-upstream-addr:
< x-upstream-response-time: 1510172906.714

Notice metadata is specified with demo-version-1.

Deploy an updated service as a canary instance

The following example deploys an updated service as a canary instance:

$> docker service create \
    --name demo-v2 \
    --network demo \
    --detach=false \
    --label \
    --label \
    --env METADATA="demo-version-2" \
    --env VERSION="0.2" \

Since this has a replica of one (1), and the initial version has four (4) replicas, 20% of application traffic is sent to demo-version-2:

$> curl -vs -H "Host: demo.local"
$> curl -vs -H "Host: demo.local"
$> curl -vs -H "Host: demo.local"
$> curl -vs -H "Host: demo.local"
$> curl -vs -H "Host: demo.local"

To increase traffic to the new version, add more replicas with docker scale:

$> docker service scale demo-v2=4

To complete the upgrade, scale the demo-v1 service to zero (0):

$> docker service scale demo-v1=0

This routes all application traffic to the new version. If you need to rollback, simply scale the v1 service back up and v2 down.

routing, proxy