From 2ca6fd3000bba537ca20a2fa2257e30913ffbc16 Mon Sep 17 00:00:00 2001
From: Romain Dessort <rdessort@evolix.fr>
Date: Thu, 10 May 2018 16:49:16 -0400
Subject: [PATCH] HowtoDocker : ajout partie du le fichier de stack YAML

---
 HowtoDocker.md | 127 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)

diff --git a/HowtoDocker.md b/HowtoDocker.md
index bbfeb0b1..0a388a75 100644
--- a/HowtoDocker.md
+++ b/HowtoDocker.md
@@ -540,6 +540,133 @@ Informations détaillées sur un réseau :
 ### Fichiers de configuration (docker config)
 ### Fichiers sensibles (docker secrets)
 
+### Fichier YAML de description de _stack_ (anciennement _docker-compose.yml_)
+
+Les _stacks_ Docker se décrivent à l'aide d'un fichier YAML. Anciennement le
+déploiement d'une _stack_ se faisait à l'aide de Docker-compose et le fichier
+s'appelait couramment _docker-compose.yml_. Docker stack ne définit pas de nom
+par défaut donc il peut porter n'importe quel nom.
+
+Le fichier contient une description de tous les objets Docker à créer pour
+déployer une _stack_ de zéro.
+
+Tout ce que l'on peut faire avec le fichier YAML peut être fait avec les
+commandes docker équivalentes (`docker service`, `docker volume`, `docker
+config`, etc…). Le nom des commandes et options sont exactement les mêmes. Le
+format YAML permet simplement de rendre plus simple la description d'une
+_stack_ qu'une série de commandes.
+
+Référence sur le format du fichier :
+[https://docs.docker.com/compose/compose-file/](https://docs.docker.com/compose/compose-file/)
+
+Voici un aperçu :
+
+~~~
+$ cat ma-stack.yml
+version: "3.6"
+
+services:
+
+  web:
+    image: my-website:latest
+    deploy:
+      replicas: 2
+      restart_policy:
+        condition: on-failure
+    ports:
+      - "80:80"
+      - "443:443"
+    environment:
+      - MYSQL_DB=foo_dev
+      - MYSQL_USER=foo_dev
+      - MYSQL_PASS=deb2Ozpifut?
+    secrets:
+      - ssl_cert
+    configs:
+      - source: nginx
+        target: /etc/nginx/nginx.conf
+
+  mysql:
+    image: mariadb:latest
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+      placement:
+        constraints:
+          - node.labels.role == sql
+    volumes:
+      - mysql-datadir:/var/lib/mysql
+
+volumes:
+  mysql-datadir:
+
+configs:
+  nginx:
+    file: nginx.conf
+
+secrets:
+  ssl_cert:
+    file: example.com.pem
+~~~
+
+On lance ici 2 _services_, _web_ et _mysql_. On spécifie que _web_ doit avoir 2
+réplicas, il y aura donc 2 _tasks_ (et donc 2 conteneurs) qui seront démarrés,
+peu importe où sur le cluster.
+
+Pour le service _mysql_ par contre, on spécifie une contrainte de placement de
+la _task_, elle doit être démarré sur une machine du cluster ayant le label
+_role == sql_. La raison est que comme on lui a associé un volume pour son
+_datadir_, il doit toujours être exécuter sur la même machine (les volumes ne
+sont pas répliqués entre les machines d'un cluster).
+
+On ne spécifie pas de chemin pour le _volume_ _mysql_datadir_, donc Docker le
+créera par défaut dans _/var/lib/docker/volumes/ma-stack_mysql-datadir/ sur la
+machine hôte.
+
+Le _service_ _web_ à besoin d'une _config_ appelée _nginx_ et d'un _secret_
+appelé _ssl_cert_ que l'on déclare tout en bas et qui contiennent
+respectivement le fichier _nginx.conf_ et _example.com.pem_ dans notre
+répertoire courant, à côté du _ma-stack.yml_. Lorsque Docker crée une _config_
+ou un _secret_ (au déploiement de la _stack_), il les rend disponible à tous
+les membres du cluster, ce qui fait qu'on n'a pas besoin de spécifier de
+contrainte de placement pour _web_.
+
+Ensuite on peut déployer notre _stack_ :
+
+~~~
+$ ls
+ma-stack.yml        nginx.conf      example.com.pem
+$ docker stack deploy -c ma-stack.yml ma-stack
+~~~
+
+#### Surcharge de paramètre
+
+On peut surcharger certains paramètres définit dans le premier en créant un
+second fichier contenant seulement les paramètres à surcharger. Les 2 fichiers
+devront être passer en paramètre de `docker stack deploy` et ils seront alors
+fusionnés. Cela permet de réutiliser un fichier de _stack_ pour différents
+environnement (preprod, prod…) en changeant uniquement des variables
+d'environement, mots de passe, etc…
+
+~~~
+$ cat ma-stack.dev.yml
+version: "3.6"
+services:
+  web:
+    environment:
+      - DEBUG=1
+      - MYSQL_DB=foo_dev
+      - MYSQL_USER=foo_dev
+      - MYSQL_PASS=deb2Ozpifut?
+~~~
+
+On peut ensuite déployer ainsi :
+
+~~~
+$ docker stack deploy -c ma-stack.yml -c ma-stack.dev.yml ma-stack
+~~~
+
 ## FAQ
 
 > Lors d'un redéploiement d'une stack Docker (docker stack deploy), les services ne sont pas redémarrer avec la nouvelle image