nickjj.docker

Qu'est-ce qu'ansible-docker?

C'est un rôle Ansible qui permet de :

• Installer Docker (toutes les éditions, canaux et versions sont supportés)
• Installer Docker Compose v2 et / ou Docker Compose v1 (le verrouillage des versions est supporté)
• Installer le paquet PIP docker afin que les modules docker_* d'Ansible fonctionnent
• Gérer les identifiants de connexion aux registres Docker
• Configurer un ou plusieurs utilisateurs pour exécuter Docker sans accès root
• Configurer les options et variables d'environnement du daemon Docker
• Configurer un job cron pour exécuter des commandes de nettoyage Docker

Pourquoi utiliser ce rôle ?

Si vous êtes comme moi, vous aimez probablement Docker. Ce rôle fournit tout ce dont vous avez besoin pour configurer un hôte Docker prêt pour la production.

Au fait, si vous ne savez pas ce qu'est Docker ou si vous souhaitez devenir un expert, consultez le Cours complet sur Docker pour développeurs.

Plateformes supportées

• Ubuntu 20.04 LTS (Focal Fossa)
• Ubuntu 22.04 LTS (Jammy Jellyfish)
• Debian 11 (Bullseye)
• Debian 12 (Bookworm)

Les anciennes versions peuvent ou non fonctionner, mais elles ne sont pas officiellement supportées.

Vous consultez la documentation de la branche principale qui peut être à jour par rapport à la dernière version. Passez à la dernière version.

Démarrage rapide

La philosophie de tous mes rôles est de faciliter le démarrage tout en offrant la possibilité de personnaliser presque tout.

Qu'est-ce qui est configuré par défaut ?

La dernière version stable de Docker CE et de Docker Compose v2 sera installée, le nettoyage de disque Docker sera effectué une fois par semaine, et les journaux des conteneurs Docker seront envoyés à journald.

Exemple de playbook

---

# docker.yml

- name: Exemple
  hosts: "all"
  become: true

  roles:
    - role: "nickjj.docker"
      tags: ["docker"]

Utilisation : ansible-playbook docker.yml

Installation

$ ansible-galaxy install nickjj.docker

Variables par défaut du rôle

Installer Docker

Canal

Voulez-vous utiliser le canal "stable" ou "test"? Vous pouvez en ajouter plusieurs (l'ordre a son importance).

docker__channel: ["stable"]

Version

• Si défini sur "", la dernière version de Docker sera installée
• Si défini sur une version spécifique, cette version de Docker sera installée et verrouillée

docker__version: ""

# Par exemple, le verrouiller à 25.0.
docker__version: "25.0"

# Par exemple, le verrouiller à une version plus précise de 25.0.
docker__version: "25.0.5"

Le verrouillage se fait avec un * à la fin de la version du paquet, vous obtiendrez donc des mises à jour mineures et de sécurité, sauf si vous verrouillez une version exacte.

Stratégie de mise à jour

• Si défini sur "present", l'exécution future de ce rôle n'installera pas de nouvelles versions (si disponibles)
• Si défini sur "latest", l'exécution future de ce rôle installera de nouvelles versions (si disponibles)

docker__state: "present"

Stratégie de rétrogradation

La façon la plus simple de rétrograder serait de désinstaller manuellement le paquet Docker et ensuite d'exécuter ce rôle en verrouillant la version spécifique de Docker que vous souhaitez.

# Une commande Ansible ad-hoc pour arrêter et supprimer le paquet Docker CE sur tous les hôtes.
ansible all -m systemd -a "name=docker-ce state=stopped" \
  -m apt -a "name=docker-ce autoremove=true purge=true state=absent" -b

Installer Docker Compose v2

Docker Compose v2 sera installé avec apt en utilisant le docker-compose-plugin officiel géré par Docker.

Version

• Si défini sur "", la dernière version de Docker Compose v2 sera installée
• Si défini sur une version spécifique, cette version de Docker Compose v2 sera installée et verrouillée

docker__compose_v2_version: ""

# Par exemple, le verrouiller à 2.29.
docker__compose_v2_version: "2.29"

# Par exemple, le verrouiller à une version plus précise de 2.29.1.
docker__compose_v2_version: "2.29.1"

Stratégie de mise à jour

Elle utilisera la variable docker__state expliquée ci-dessus dans la section Docker avec les mêmes règles.

Stratégie de rétrogradation

Comme pour Docker, la façon la plus simple de désinstaller Docker Compose v2 est d'exécuter manuellement la commande ci-dessous, puis de verrouiller une version spécifique de Docker Compose v2.

# Une commande Ansible ad-hoc pour supprimer le paquet Docker Compose Plugin sur tous les hôtes.
ansible all -m apt -a "name=docker-compose-plugin autoremove=true purge=true state=absent" -b

Installer Docker Compose v1

Par défaut, ce rôle n'installe pas Docker Compose v1 car il a été officiellement déprécié et ne reçoit plus de mises à jour de Docker. Cependant, ce rôle est capable de l'installer. Il vous suffit de définir docker__pip_docker_compose_state: "present" car ce rôle est par défaut à absent pour cette valeur.

Techniquement, les deux versions peuvent être installées ensemble car la v1 est accédée avec docker-compose et la v2 avec docker compose (notez l'absence de tiret).

Je suggérerais de ne pas installer la v1 sauf si vous en avez vraiment besoin pour des raisons de compatibilité. Si vous décidez de l'installer, vous pouvez configurer quelle version sera installée ci-dessous. Si ce n'est pas défini pour être installé, ces versions resteront inutilisées :

Version

• Si défini sur "", la dernière version de Docker Compose v1 sera installée
• Si défini sur une version spécifique, cette version de Docker Compose v1 sera installée et verrouillée

docker__compose_version: ""

# Par exemple, le verrouiller à 1.29.
docker__compose_version: "1.29"

# Par exemple, le verrouiller à une version plus précise de 1.29.
docker__compose_version: "1.29.2"

Les stratégies de mise à jour et de rétrogradation seront expliquées dans l'autre section de ce document.

Configurer les utilisateurs pour exécuter Docker sans root

Une liste d'utilisateurs à ajouter au groupe docker.

Gardez à l'esprit que cet utilisateur doit déjà exister, ce rôle ne le créera pas. Si vous souhaitez créer des utilisateurs, consultez mon rôle utilisateur.

Ce rôle ne configure pas les espaces de noms utilisateur ou d'autres fonctionnalités de sécurité par défaut. Si l'utilisateur que vous ajoutez ici a accès SSH à votre serveur, vous lui donnez effectivement un accès root au serveur car il peut exécuter Docker sans sudo et monter des volumes dans n'importe quel chemin de votre système de fichiers.

Dans un environnement contrôlé, cela est sûr, mais comme tout ce qui concerne la sécurité, il est bon de le savoir à l'avance. Vous pouvez activer les espaces de noms utilisateur et d'autres options avec la variable docker__daemon_json qui sera expliquée plus loin.

# Essayez d'utiliser l'utilisateur sudo par défaut, mais revenez à root si nécessaire.
docker__users: ["{{ ansible_env.SUDO_USER | d('root') }}"]

# Par exemple, si l'utilisateur que vous souhaitez définir est différent de l'utilisateur sudo.
docker__users: ["admin"]

Configurer les connexions aux registres Docker

Connexion à un ou plusieurs registres Docker (comme le Docker Hub).

# Vos identifiants de connexion finiront dans le répertoire personnel de cet utilisateur.
docker__login_become_user: "{{ docker__users | first | d('root') }}"

# 0 ou plusieurs registres à se connecter.
docker__registries:
  - #registry_url: "https://index.docker.io/v1/"
    username: "votre_nom_utilisateur_docker_hub"
    password: "votre_mot_de_passe_docker_hub"
    #email: "[email protected]"
    #reauthorize: false
    #config_path: "$HOME/.docker/config.json"
    #state: "present"
docker__registries: []

Les propriétés commençant par * sont requises.

• registry_url par défaut est https://index.docker.io/v1/
• *username est votre nom d'utilisateur pour le registre Docker
• *password est votre mot de passe pour le registre Docker
• email par défaut n'est pas utilisé (tous les registres ne l'utilisent pas)
• reauthorize par défaut à false, si défini sur true, cela met à jour vos identifiants
• config_path par défaut dans le répertoire $HOME de votre docker__login_become_user
• state par défaut à "present", si "absent", la connexion sera supprimée

Configurer les options du daemon Docker (json)

Options par défaut du daemon Docker telles qu'elles apparaîtraient dans /etc/docker/daemon.json.

docker__default_daemon_json: |
  "log-driver": "journald",
  "features": {
    "buildkit": true
  }

# Ajoutez vos propres options de daemon sans écraser les options par défaut.
# Cela suit le même format que les options par défaut, et ne vous inquiétez pas
# de commencer par une virgule. Le modèle ajoutera la virgule si nécessaire.
docker__daemon_json: ""

Configurer les options du daemon Docker (flags)

Les flags définis lors du démarrage du daemon Docker ne peuvent pas être modifiés dans le fichier daemon.json. Par défaut, Docker définit -H unix://, ce qui signifie que cette option ne peut pas être modifiée avec les options json.

Ajoutez ou modifiez les flags de démarrage du daemon Docker en les fournissant exactement comme ils apparaîtraient dans la ligne de commande.

# Chaque flag de ligne de commande doit être un élément dans la liste.
#
# Utilisez une version de Docker antérieure à 18.09?
#   Vous devez définir `-H fd://` au lieu de `-H unix://`.
docker__daemon_flags:
  - "-H unix://"

Si vous ne fournissez pas un type de flag -H, Docker échouera à démarrer.

Configurer les variables d'environnement du daemon Docker

docker__daemon_environment: []

# Par exemple, voici comment définir quelques variables d'environnement de proxy.
docker__daemon_environment:
  - "HTTP_PROXY=http://proxy.example.com:80"
  - "HTTPS_PROXY=https://proxy.example.com:443"

Configurer des directives systémiques avancées

Ce rôle permet au paquet Docker de gérer son propre fichier d'unité systemd et ajuste des éléments comme les flags et les variables d'environnement du daemon Docker en utilisant le modèle de substitution systemd.

Si vous savez ce que vous faites, vous pouvez remplacer ou ajouter n'importe quelle directive systemd de Docker en définissant cette variable. Tout ce que vous placez dans cette chaîne sera écrit dans /etc/systemd/system/docker.service.d/custom.conf tel quel.

docker__systemd_override: ""

Configurer les jobs cron liés à Docker

Par défaut, cela nettoiera en toute sécurité l'espace disque utilisé par Docker tous les dimanches à minuit.

# `a` supprime les images inutilisées (utile en production).
# `f` force l'opération sans vous demander votre accord.
docker__cron_jobs_prune_flags: "af"

# Contrôlez le programme du prune system/docker.
docker__cron_jobs_prune_schedule: ["0", "0", "*", "*", "0"]

docker__cron_jobs:
  - name: "Nettoyage du disque Docker"
    job: "docker system prune -{{ docker__cron_jobs_prune_flags }} > /dev/null 2>&1"
    schedule: "{{ docker__cron_jobs_prune_schedule }}"
    cron_file: "docker-disk-clean-up"
    #user: "{{ (docker__users | first) | d('root') }}"
    #state: "present"

Les propriétés commençant par * sont requises.

• *name est la description du job cron
• *job est la commande à exécuter dans le job cron
• *schedule est le format de job cron standard pour chaque dimanche à minuit
• *cron_file écrit un fichier cron dans /etc/cron.d au lieu d'un crontab individuel d'un utilisateur
• user par défaut au premier utilisateur docker__users ou root si celui-ci n'est pas disponible
• state par défaut à "present", si "absent", le fichier cron sera supprimé

Configuration du gestionnaire de paquets APT

Docker nécessite quelques dépendances pour fonctionner. Vous ne devriez pas avoir à modifier ces variables.

# Liste des paquets à installer.
docker__package_dependencies:
  - "apt-transport-https"
  - "ca-certificates"
  - "cron"
  - "gnupg2"
  - "software-properties-common"

# Ansible identifie les architectures CPU différemment de Docker.
docker__architecture_map:
  "x86_64": "amd64"
  "aarch64": "arm64"
  "aarch": "arm64"
  "armhf": "armhf"
  "armv7l": "armhf"

# L'URL de la clé GPG Docker.
docker__apt_repository_url: "https://download.docker.com/linux/{{ ansible_distribution | lower }}"

# La valeur de contrôle de la clé GPG Docker.
docker__apt_key_checksum: "sha256:1500c1f56fa9e26b9b8f42452a553675796ade0807cdce11975eb98170b3a570"

# Le dépôt APT Docker.
docker__apt_repository: >
  deb [arch={{ docker__architecture_map[ansible_architecture] }}
  signed-by=/etc/apt/keyrings/docker.asc]
  {{ docker__apt_repository_url }}
  {{ ansible_distribution_release }} {{ docker__channel | join(' ') }}

Installer des paquets Python avec Virtualenv et PIP

Configuration de Virtualenv

Pour éviter de polluer la version de Python de votre serveur, tous les paquets PIP sont installés dans un Virtualenv de votre choix.

docker__pip_virtualenv: "/usr/local/lib/docker/virtualenv"

Installer PIP et ses dépendances

Ce rôle installe PIP car Docker Compose v1 est installé avec le paquet PIP docker-compose et les modules docker_* d'Ansible utilisent le paquet docker.

docker__pip_dependencies:
  - "gcc"
  - "python3-setuptools"
  - "python3-dev"
  - "python3-pip"
  - "virtualenv"

Installer des paquets PIP

docker__default_pip_packages:
  - name: "docker"
    state: "{{ docker__pip_docker_state }}"
  - name: "docker-compose"
    version: "{{ docker__compose_version }}"
    path: "/usr/local/bin/docker-compose"
    src: "{{ docker__pip_virtualenv + '/bin/docker-compose' }}"
    state: "{{ docker__pip_docker_compose_state }}"

# Ajoutez vos propres paquets PIP avec les propriétés ci-dessus.
docker__pip_packages: []

Les propriétés commençant par * sont requises.

• *name est le nom du paquet
• version est la version du paquet à installer (ou "" si cela n'est pas défini)
• path est le chemin de destination du lien symbolique
• src est le chemin source à symboliser
• state par défaut à "present", d'autres valeurs peuvent être "forcereinstall" ou "absent"

État du paquet PIP

• Si défini sur "present", le paquet sera installé mais ne sera pas mis à jour lors des exécutions futures
• Si défini sur "forcereinstall", le paquet sera toujours (ré)installé et mis à jour lors des exécutions futures
• Si défini sur "absent", le paquet sera ignoré ou supprimé

docker__pip_docker_state: "present"
docker__pip_docker_compose_state: "absent"

Travailler avec les modules docker_* d'Ansible

Ce rôle utilise docker_login pour se connecter à un registre Docker, mais vous pouvez également utiliser les autres modules docker_* dans vos propres rôles. Ils ne fonctionneront pas à moins d'instruire Ansible à utiliser le Virtualenv de ce rôle.

Au niveau de l'inventaire, du playbook ou de la tâche, vous devrez définir ansible_python_interpreter: "/usr/local/bin/python3-docker". Cela fonctionne car ce rôle crée un script proxy à partir du binaire Python du Virtualenv vers python3-docker.

Vous pouvez consulter la tâche docker_login de ce rôle comme exemple sur la façon de le faire au niveau de la tâche.

Licence

MIT