From 3692e1c4bd0134138dcd0cb1258e81dc51c30072 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Thu, 6 Oct 2016 15:48:23 +0200 Subject: [PATCH] =?UTF-8?q?Add=20documentation=20for=20Tr=C3=A6fik=20on=20?= =?UTF-8?q?docker=20swarm=20mode?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Also small update on the swarm one. Signed-off-by: Vincent Demeester --- docs/user-guide/swarm-mode.md | 223 ++++++++++++++++++++++++++++++++++ docs/user-guide/swarm.md | 14 +-- mkdocs.yml | 1 + 3 files changed, 231 insertions(+), 7 deletions(-) create mode 100644 docs/user-guide/swarm-mode.md diff --git a/docs/user-guide/swarm-mode.md b/docs/user-guide/swarm-mode.md new file mode 100644 index 000000000..4bbc1c787 --- /dev/null +++ b/docs/user-guide/swarm-mode.md @@ -0,0 +1,223 @@ +# Docker Swarm (mode) cluster + +This section explains how to create a multi-host docker cluster with +swarm mode using [docker-machine](https://docs.docker.com/machine) and +how to deploy Træfɪk on it. + +The cluster constist of: + +- 3 servers +- 1 manager +- 2 workers +- 1 [overlay](https://docs.docker.com/engine/userguide/networking/dockernetworks/#an-overlay-network) network +(multi-host networking) + +## Prerequisites + +1. You will need to install [docker-machine](https://docs.docker.com/machine/) +2. You will need the latest [VirtualBox](https://www.virtualbox.org/wiki/Downloads) + +## Cluster provisioning + +First, let's create all the nodes required. It's a shorter version of +the [swarm tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/). + +```sh +docker-machine create -d virtualbox manager +docker-machine create -d virtualbox worker1 +docker-machine create -d virtualbox worker2 +``` + +Then, let's setup the cluster, in order : + +1. initialize the cluster +2. get the token for other host to join +3. on both workers, join the cluster with the token + +```sh +docker-machine ssh manager "docker swarm init \ + --listen-addr $(docker-machine ip manager) \ + --advertise-addr $(docker-machine ip manager)" + +export worker_token=$(docker-machine ssh manager "docker swarm \ +join-token worker -q") + +docker-machine ssh worker1 "docker swarm join \ + --token=${worker_token} \ + --listen-addr $(docker-machine ip worker1) \ + --advertise-addr $(docker-machine ip worker1) \ + $(docker-machine ip manager)" +docker-machine ssh worker2 "docker swarm join \ + --token=${worker_token} \ + --listen-addr $(docker-machine ip worker2) \ + --advertise-addr $(docker-machine ip worker2) \ + $(docker-machine ip manager)" +``` + +Let's validate the cluster is up and running. + +```sh +docker-machine ssh manager docker node ls +ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS +2a770ov9vixeadep674265u1n worker1 Ready Active +dbi3or4q8ii8elbws70g4hkdh * manager Ready Active Leader +esbhhy6vnqv90xomjaomdgy46 worker2 Ready Active +``` + +Finally, let's create a network for Træfik to use. + +```sh +docker-machine ssh manager "docker network create --driver=overlay traefik-net" +``` + +## Deploy Træfik + +Let's deploy Træfik as a docker service in our cluster. The only +requirement for Træfik to work with swarm mode is that it needs to run +on a manager node — we are going to use a +[constraint](https://docs.docker.com/engine/reference/commandline/service_create/#/specify-service-constraints-constraint) for +that. + +``` +docker-machine ssh manager "docker service create \ + --name traefik \ + --constraint=node.role==manager \ + --publish 80:80 --publish 8080:8080 \ + --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \ + --network traefik-net \ + traefik \ + --docker \ + --docker.swarmmode \ + --docker.domain=traefik \ + --docker.watch \ + --web" +``` + +Let's explain this command: + +- `--publish 80:80 --publish 8080:8080`: we publish port `80` and + `8080` on the cluster. +- `--constraint=node.role==manager`: we ask docker to schedule Træfik + on a manager node. +- `--mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock`: + we bind mount the docker socket where Træfik is scheduled to be able + to speak to the daemon. +- `--network traefik-net`: we attach the Træfik service (and thus + the underlined container) to the `traefik-net` network. +- `--docker`: enable docker backend, and `--docker.swarmmode` to + enable the swarm mode on Træfik. +- `--web`: activate the webUI on port 8080 + +## Deploy your apps + +We can now deploy our app on the cluster, +here [whoami](https://github.com/emilevauge/whoami), a simple web +server in Go. We start 2 services, on the `traefik-net` network. + +```sh +docker-machine ssh manager "docker service create \ + --name whoami0 \ + --label traefik.port=80 \ + --network traefik-net \ + emilevauge/whoami" +docker-machine ssh manager "docker service create \ + --name whoami1 \ + --label traefik.port=80 \ + --network traefik-net \ + emilevauge/whoami" +``` + +Check that everything is scheduled and started: + +```sh +docker-machine ssh manager "docker service ls" +ID NAME REPLICAS IMAGE COMMAND +ab046gpaqtln whoami0 1/1 emilevauge/whoami +cgfg5ifzrpgm whoami1 1/1 emilevauge/whoami +dtpl249tfghc traefik 1/1 traefik --docker --docker.swarmmode --docker.domain=traefik --docker.watch --web +``` + +## Access to your apps through Træfɪk + +```sh +curl -H Host:whoami0.traefik http://$(docker-machine ip manager) +Hostname: 8147a7746e7a +IP: 127.0.0.1 +IP: ::1 +IP: 10.0.9.3 +IP: fe80::42:aff:fe00:903 +IP: 172.18.0.3 +IP: fe80::42:acff:fe12:3 +GET / HTTP/1.1 +Host: 10.0.9.3:80 +User-Agent: curl/7.35.0 +Accept: */* +Accept-Encoding: gzip +X-Forwarded-For: 192.168.99.1 +X-Forwarded-Host: 10.0.9.3:80 +X-Forwarded-Proto: http +X-Forwarded-Server: 8fbc39271b4c + +curl -H Host:whoami1.traefik http://$(docker-machine ip manager) +Hostname: ba2c21488299 +IP: 127.0.0.1 +IP: ::1 +IP: 10.0.9.4 +IP: fe80::42:aff:fe00:904 +IP: 172.18.0.2 +IP: fe80::42:acff:fe12:2 +GET / HTTP/1.1 +Host: 10.0.9.4:80 +User-Agent: curl/7.35.0 +Accept: */* +Accept-Encoding: gzip +X-Forwarded-For: 192.168.99.1 +X-Forwarded-Host: 10.0.9.4:80 +X-Forwarded-Proto: http +X-Forwarded-Server: 8fbc39271b4c +``` + +Note that as Træfik is published, you can access it from any machine +and not only the manager. + +```sh +curl -H Host:whoami0.traefik http://$(docker-machine ip worker1) +Hostname: 8147a7746e7a +IP: 127.0.0.1 +IP: ::1 +IP: 10.0.9.3 +IP: fe80::42:aff:fe00:903 +IP: 172.18.0.3 +IP: fe80::42:acff:fe12:3 +GET / HTTP/1.1 +Host: 10.0.9.3:80 +User-Agent: curl/7.35.0 +Accept: */* +Accept-Encoding: gzip +X-Forwarded-For: 192.168.99.1 +X-Forwarded-Host: 10.0.9.3:80 +X-Forwarded-Proto: http +X-Forwarded-Server: 8fbc39271b4c + +curl -H Host:whoami1.traefik http://$(docker-machine ip worker2) +Hostname: ba2c21488299 +IP: 127.0.0.1 +IP: ::1 +IP: 10.0.9.4 +IP: fe80::42:aff:fe00:904 +IP: 172.18.0.2 +IP: fe80::42:acff:fe12:2 +GET / HTTP/1.1 +Host: 10.0.9.4:80 +User-Agent: curl/7.35.0 +Accept: */* +Accept-Encoding: gzip +X-Forwarded-For: 192.168.99.1 +X-Forwarded-Host: 10.0.9.4:80 +X-Forwarded-Proto: http +X-Forwarded-Server: 8fbc39271b4c +``` + +![](http://i.giphy.com/ujUdrdpX7Ok5W.gif) + + diff --git a/docs/user-guide/swarm.md b/docs/user-guide/swarm.md index 456b3f20a..13a9ab96b 100644 --- a/docs/user-guide/swarm.md +++ b/docs/user-guide/swarm.md @@ -1,7 +1,7 @@ # Swarm cluster This section explains how to create a multi-host [swarm](https://docs.docker.com/swarm) cluster using [docker-machine](https://docs.docker.com/machine/) and how to deploy Træfɪk on it. -The cluster will be made of: +The cluster consists of: - 2 servers - 1 swarm master @@ -10,16 +10,16 @@ The cluster will be made of: ## Prerequisites -1. You will need to install [docker-machine](https://docs.docker.com/machine/) -2. You will need the latest [VirtualBox](https://www.virtualbox.org/wiki/Downloads) +1. You need to install [docker-machine](https://docs.docker.com/machine/) +2. You need the latest [VirtualBox](https://www.virtualbox.org/wiki/Downloads) ## Cluster provisioning -We will first follow [this guide](https://docs.docker.com/engine/userguide/networking/get-started-overlay/) to create the cluster. +We first follow [this guide](https://docs.docker.com/engine/userguide/networking/get-started-overlay/) to create the cluster. ### Create machine `mh-keystore` -This machine will be the service registry of our cluster. +This machine is the service registry of our cluster. ```sh docker-machine create -d virtualbox mh-keystore @@ -37,7 +37,7 @@ docker run -d \ ### Create machine `mhs-demo0` -This machine will have a swarm master and a swarm agent on it. +This machine is a swarm master and a swarm agent on it. ```sh docker-machine create -d virtualbox \ @@ -50,7 +50,7 @@ docker-machine create -d virtualbox \ ### Create machine `mhs-demo1` -This machine will have a swarm agent on it. +This machine have a swarm agent on it. ```sh docker-machine create -d virtualbox \ diff --git a/mkdocs.yml b/mkdocs.yml index fbb1642d8..3aaf0284c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,6 +49,7 @@ pages: - User Guide: - 'Configuration examples': 'user-guide/examples.md' - 'Swarm cluster': 'user-guide/swarm.md' + - 'Swarm mode cluster': 'user-guide/swarm-mode.md' - 'Kubernetes': 'user-guide/kubernetes.md' - 'Key-value store configuration': 'user-guide/kv-config.md' - 'Clustering/HA': 'user-guide/cluster.md'