guide_bonnes_pratiques.md

Introduction

Ce mini-guide vous donne des pistes pour créer de nouveaux services, tout en restant harmonieux par rapport à l'infrastructure existante.

Pour une plongée plus complète dans les différents concepts abordés ici, on pourra se référer aux documentations officielles. Il n'est pas nécessaire de les lire en entier pour travailler sur ce dépôt : elles seront surtout utiles pour comprendre l'existant.

• Une introduction à Docker : pourquoi et comment
• Référence pour l'écriture d'un Dockerfile
• Bonnes pratiques pour l'écriture des Dockerfile
• Orchestrer le lancement de conteneurs avec Docker Compose
• Référence pour l'écriture de fichiers Docker Compose

Se baser sur un autre Dockerfile ?

Tous les services tournant sur l'infrastructure de Picasoft sont voués à être pris en charge par ce dépôt.

Il y a plusieurs cas.

Je veux faire tourner un service existant, tel quel

Si un service existant a une image Docker officielle, référencée sur le Docker Hub, et qu'elle nous suffit, on s'en servira telle quel dans le docker-compose.yml.

Je veux customiser un service existant

Supposons que l'image Docker officielle ne nous convienne pas, que l'on soit obligé de la modifier pour régler des problèmes de sécurité, ou tout simplement qu'on veuille l'étendre, il faut créer un Dockerfile plus complet. Il y a deux solutions :

• Soit on part de l'image officielle, avec un FROM, et on travaille dessus en rajoutant des fichiers, en enlevant des paquets... Cette solution a l'inconvénient de multiplier les layers inutiles, et d'augmenter la taille de l'image.
• Soit on copie le Dockerfile de l'image officielle (c'est le cas pour Mattermost), et on fait nos modifications. Cette solution a pour inconvénient de devoir se synchroniser avec les modifications du Dockerfile officiel à chaque mise à jour, s'il contient des améliorations ou corrections importantes.

Je veux écrire un Dockerfile de zéro.

Allez-y ! :D

Dockerfile

Une série de recommendations est disponible ici pour l'écriture des Dockerfile.

Image de base

Préférez vous baser sur une image Alpine (peu de paquets, donc peu de vulnérabilités) ou Debian. Pour Debian, préférez la version stable la plus récente possible (Buster plutôt que Stretch) pour mitiger d'emblée un grand nombre de vulnérabilités.

Préférez également les versions slim, qui contiennent moins de paquets et suffisent souvent.

Pour les services basés sur un langage interprété comme Python, utilisez l'image officielle en appliquant les principes précédents.

Builds reproductibles

L'idée derrière un build "reproductible", c'est que si je me rends sur un ancien commit de ce dépôt et que je lance un docker build dans un dossier, comme pica-mattermost, l'image finale doit être la même quel que soit le temps écoulé depuis ce commit. Pourquoi ? Pour pouvoir relancer le build d'une ancienne version et la remettre en production en cas de problème.

Souvent, un Dockerfile va récupérer du code sur un dépôt Git, ou encore un binaire sur un site de téléchargement de releases. Il est fortement déconseillé de faire un git clone ou un wget de la dernière version (latest, master...), ce qui rend le build non reproductible et dépendant de cette dernière version.

Il est donc important de gérer la version du service en question, par exemple avec une variable ARG SERVICE_VERSION=1.0.1 qui sera ré-utilisée dans l'URL de téléchargement.

En outre il existe deux solutions pour récupérer du code existant, versionné sur un dépôt Git distant :

• Installer Git dans le Dockerfile, utiliser un git clone puis un git checkout <tag> sur la version souhaitée et copier le code dans l'image.
• Utiliser un submodule dans le dossier du service, en particulier si le dépôt où se trouve le code est de petite taille et qu'il n'utilise pas les tags. En effet, comme un submodule est lié à un numéro de commit, chaque commit de ce dépôt sera associé à un commit précis du dépôt distant. On peut donc retrouver l'état du code distant avec le numéro de commit du submodule associé au commit local.

Volumes

Une fois que l'on a identifié les dossiers du conteneur où l'on a besoin de persistence, il y a plusieurs manières de procéder :

• Soit utiliser un dossier de l'hôte comme stockage, via un bind mount
• Soit utiliser un volume Docker, géré en interne par Docker.

Chacun a ses avantages et inconvénients, voilà ce que l'on fait chez Picasoft :

• Pour monter un ou des fichiers existants dans un conteneur, on utilise un bind mount,
• Pour assurer la persistence d'un dossier du conteneur, on utilise un volume Docker.

Bind mounts

Si le fichier à monter est versionné sur ce dépôt, on utilisera un chemin relatif. Sinon, on utilisera des chemins absolus, ce qui enlève du côté "indépendant des machines", mais parfois on ne peut pas faire autrement. Par exemple, quand des certificats sont stockés sur une machine de production dans un dossier spécifique, on est obligés d'y faire référence.

Exemple :

[...]
services:
  exemple:
    [...]
    volumes:
      # Dossier contenant les certificats sur les machines de production : utilisation du chemin absolu
      - /DATA/docker/certs/example.picasoft.net:/certs
      # Fichier de configuration versionné dans le même dossier : utilisation du chemin relatif
      - ./config.json:/etc/config.json

Volumes Docker

Si on veut indiquer qu'un des dossiers du conteneur doit persister au fil des re-créations, alors on utilise des volumes Docker. C'est typiquement le cas pour le dossier /var/lib/postgresql/data d'une base PostgreSQL, qui ne doit pas supprimer les données à chaque re-création du conteneur.

Exemple :

[...]
volumes:
  # Nom du volume Docker
  db:
    # On spécifie le nom exact
    name: db

  services:
    exemple:
      volumes:
        # On fait référence au "db" défini ci-dessus, et on le monte sur /mount_point
        - db:/mount_point

Il est suggéré d'éviter les volumes déclarés external :

• Un volume créé en dehors de Compose peut être utilisé sans être déclaré external ;
• En revanche un volume non-créé et déclaré external fera échouer les commandes Compose.

Reverse-proxy

Si le service est un service HTTP(S) (i.e. Web), on utilisera systématiquement le reverse-proxy Traefik et on bindera pas son port interne sur un port de l'hôte.

En effet, Traefik permet de gérer tout pour nous : la redirection vers le bon conteneur et le bon port en fonction du nom de domaine, la création et le renouvellement des certificats, etc.

Il suffit pour ce faire d'ajouter les bons labels, et d'ajouter le conteneur au réseau par défaut de Traefik, qui s'appelle docker_default, et existe indépendamment de Docker Compose.

Exemple à reprendre :

networks:
  docker_default:
    external: true

services:
  exemple:
    networks:
      - docker_default
    labels:
      # Traefik va prendre ce conteneur en compte
      traefik.enable: true
      # Il redirigera vers ce port, exposé par le conteneur
      traefik.port: <port>
      # Lorsque l'utilisateur consulte cette URL
      traefik.frontend.rule: <exemple>.picasoft.net

Système init

Tous les systèmes Linux ont un système dit init, correspondant au processus avec le premier PID (1). Ce processus est le parent de tous les autres, et doit transmettre les signaux qu'il reçoit à ses enfants (par exemple, un signal de terminaison).

Quand vous lancez un conteneur avec un script Shell ou Bash comme entrypoint, ce script a le PID 1. S'il démarre ensuite l'application, il ne transmettra pas le signal de terminaison à ses enfants (fonctionnement normal des scripts shell).