Architecture et Ansible – Projet Voskos

Si vous arrivez directement sur cet article, je vous invite à lire les précédents à partir d’ici.

Petit aveu pour commencer : cet épisode devait sortir fin 2023, juste après celui sur le système d’exploitation. Il arrive après MergerFS et SnapRAID. Avec deux ans de retard. C’est comme ça.

Entre-temps, mon repo Ansible a accumulé 35 commits. Dont aucun entre avril 2024 et mai 2026. Deux ans pendant lesquels le serveur, lui, a continué à vivre sa vie : un service ajouté à la main ici, une variable changée en SSH là. Spoiler : le jour où j’ai voulu relancer le playbook, le repo et la machine ne racontaient plus du tout la même histoire. 😅

Alors parlons architecture, Ansible… et de ce qui arrive quand on modifie la recette sans jamais la noter.

Petit rappel de contexte

Voskos, c’est mon home server : un PC sous Ubuntu Server 22.04 LTS, dont les disques de données sont regroupés avec MergerFS et protégés par SnapRAID. Le choix du matériel et celui du système d’exploitation ont déjà eu leur épisode.

L’objectif n’a pas bougé : remplacer un maximum de services cloud par des services que j’héberge moi-même. Photos, mots de passe, documents, vidéos, monitoring…

Ce qui manquait jusqu’ici, c’est le plan de la maison : comment les morceaux se parlent, et comment tout ça s’installe.

L’architecture d’ensemble

Aujourd’hui, tout le trafic web passe par une seule porte : Traefik. Derrière, une trentaine de services dans Docker, et une deuxième machine qui fait sa vie à côté.

Schéma 1 · vue réseau, 2 machines, 1 point d'entrée

Les pièces du puzzle :

  • Deux machines sur le réseau local. Voskos, le NAS, et la box Gladys, qui gère la domotique et le broker MQTT. Le Raspberry Pi des débuts a pris sa retraite.
  • Un nom de domaine et un certificat wildcard (*.mondomaine.fr). Chaque service a son sous-domaine, et Traefik route vers le bon conteneur.
  • Tinyauth devant les services sensibles : un login (avec TOTP) et un accès défini compte par compte.
  • Tailscale pour l’accès distant, en subnet router : depuis mon téléphone, je suis « à la maison ». Tailscale envoie les requêtes DNS du domaine à AdGuard, qui répond avec l’adresse locale du NAS : même à distance, tout passe par Traefik.
  • Deux familles de services. Ceux qui doivent être joignables depuis Internet (Immich, Vaultwarden, Jellyfin, Nextcloud… bref, les apps mobiles et le partage) et ceux réservés au réseau local et à Tailscale (les consoles d’admin et le monitoring). Le comment, ce sera pour l’épisode Sécurité.

Entre les deux machines, deux liens méritent qu’on s’y arrête.

L’électricité. Le compteur remonte sa téléinformation en Zigbee, puis en MQTT sur la box Gladys. Côté NAS, mqtt2prometheus s’abonne au topic et transforme les messages en métriques pour Prometheus et Grafana. Résultat : ma conso dans un dashboard, sans cloud. 😎

Le DNS. AdGuard Home tourne sur le NAS et filtre les pubs pour toute la maison. Problème : le jour où le NAS redémarre, plus personne n’a Internet (et on me le fait savoir). J’ajoute donc en ce moment une réplique sur la box Gladys, synchronisée automatiquement par adguardhome-sync.

Vu en couches, c’est encore plus simple :

Schéma 2 · les couches, du matériel aux services

Chaque couche s’appuie sur celle du dessous. Et c’est exactement l’ordre dans lequel Ansible les installe.

Pourquoi Ansible (et pas un script bash)

Le NAS, c’est le plat. Le repo, c’est la recette.

Si le plat tombe par terre (un SSD système qui lâche, un Ubuntu à réinstaller), on ne le reconstitue pas de mémoire. On ressort la recette et on recommence. C’est exactement ce que fait Ansible : décrire le serveur dans des fichiers texte, versionnés dans Git, et pouvoir le refaire à l’identique.

Pourquoi lui plutôt qu’autre chose ?

  • L’idempotence. On peut lancer le playbook dix fois de suite : il ne refait que ce qui a changé. Un script bash, au deuxième passage, recrée l’utilisateur et rajoute la même ligne dans fstab.
  • Le déclaratif. On décrit l’état voulu (« ce paquet est installé », « ce fichier est ici »), pas la suite de commandes pour y arriver.
  • Pas d’agent. Rien à installer sur le serveur : SSH et Python, déjà présents sur Ubuntu.
  • Du texte. Donc un historique Git, des diffs, et une documentation qui ne ment pas (enfin, en théorie… on y revient).

Les alternatives que j’ai regardées :

  • Un script bash : rapide à écrire, pénible à relancer.
  • NixOS : la reproductibilité poussée à l’extrême, mais un OS et un langage à apprendre. Et j’avais déjà choisi Ubuntu pour de bonnes raisons.
  • Proxmox : très bien pour isoler des VM, mais ça ne dit toujours pas comment configurer ce qu’il y a dedans.
  • Une interface web type Portainer : clic-clic, efficace… et rien de versionné. Le jour où tout tombe, on recommence les clics.

C’est quoi Ansible ?

Ansible est un outil d’automatisation open source, porté par Red Hat. Depuis une machine de contrôle (mon Mac), il se connecte en SSH au serveur et y applique des tâches décrites en YAML.

Le vocabulaire tient en six mots :

  • L’inventaire : la liste des machines à gérer.
  • Le playbook : le fichier qui dit quoi faire, et sur quelles machines.
  • La tâche : une action unitaire, réalisée par un module (apt, file, template, systemd…).
  • Le rôle : un paquet réutilisable de tâches, fichiers et variables. Ansible Galaxy en propose des milliers.
  • Vault : le coffre-fort qui chiffre les secrets directement dans le repo.
  • Les tags : des étiquettes pour ne lancer qu’une partie du playbook.

Comment le repo est organisé (parce que c’est un blog tech quand même)

Un playbook, un inventaire, deux fichiers de variables, et un fichier par brique. Au total, 46 fichiers de tâches et environ 1 200 lignes de YAML.

voskos-nas/
├── inventory/nas          # la machine cible
├── playbook.yml           # le chef d'orchestre
├── requirements.yml       # les rôles Galaxy (geerlingguy.ntp)
├── vars/
│   ├── main.yml           # versions, hostname, accès Tinyauth…
│   └── nas-secrets.yml    # les secrets, chiffrés avec Vault
├── roles/nas/tasks/       # une tâche par brique (SnapRAID, Samba, Immich…)
└── docker-compose/        # le compose de chaque service

Et quand je lance le playbook, voilà ce qui se passe :

Schéma 3 · du poste de contrôle au NAS

L’inventaire

Une seule machine, décrite en cinq lignes.

[nas]
# Adresse locale du NAS
super_nas ansible_host=192.168.1.10
# Connexion par clé SSH uniquement, sur un port non standard
super_nas ansible_ssh_private_key_file=~/.ssh/ma_cle
super_nas ansible_port=2222
super_nas ansible_user=moi
# Les tâches passent en sudo
super_nas ansible_become=true

Le playbook

C’est le sommaire de la recette. Version allégée :

- name: Install Custom Super NAS
  hosts: super_nas
  vars_files:
    - vars/nas-secrets.yml        # déchiffré à la volée par Vault
  pre_tasks:
    - name: Include custom vars
      include_vars: vars/main.yml
      tags: [always]              # chargé même quand on filtre par tag
  tasks:
    # Le socle : système, pare-feu, disques, partages
    - include_tasks: roles/nas/tasks/initial-config.yml
    - include_tasks: roles/nas/tasks/ufw-config.yml
    - include_tasks: roles/nas/tasks/fail2ban-install.yml
    - include_tasks: roles/nas/tasks/snapraid-install.yml
    - include_tasks: roles/nas/tasks/mergerfs-install.yml
    - include_tasks: roles/nas/tasks/samba-install.yml
    # … backups, puis Docker lui-même
    - include_tasks: roles/nas/tasks/docker-install.yml
    # Les services, un fichier par stack
    - name: Services Docker
      tags: [docker]
      block:
        - import_tasks: roles/nas/tasks/docker-install-traefik.yml
        - import_tasks: roles/nas/tasks/docker-install-immich.yml
        # … une trentaine d'autres
        - import_tasks: roles/nas/tasks/docker-install-hermes.yml
          tags: [hermes]
  roles:
    - geerlingguy.ntp             # le seul « vrai » rôle, récupéré sur Galaxy

Petite subtilité qui m’a coûté quelques soirées : include_tasks et import_tasks, ce n’est pas pareil.

  • include_tasks est dynamique : le fichier est lu pendant l’exécution. Un tag posé dessus ne descend pas sur les tâches qu’il contient.
  • import_tasks est statique : le fichier est résolu avant de commencer. Les tags s’appliquent à toutes les tâches importées.

C’est pour ça que les services sont en import : --tags docker relance tous les services, et --skip-tags hermes les relance tous sauf un.

Une tâche type : Immich

Chaque service suit le même modèle en quatre temps : un dossier, un compose, un .env, un up -d.

# 1. Le dossier du service
- name: Create directory for Immich
  file:
    path: /opt/docker/immich/
    state: directory

# 2. Le compose, passé en template : les variables Jinja sont remplacées au passage
- name: Copy docker-compose Immich
  template:
    src: '{{ playbook_dir }}/docker-compose/immich/docker-compose-immich.yml'
    dest: /opt/docker/immich/docker-compose.yml

# 3. Le fichier d'environnement (les secrets viennent de Vault)
- name: Copy .env Immich
  template:
    src: '{{ playbook_dir }}/docker-compose/immich/.env'
    dest: /opt/docker/immich/.env

# 4. On lance (ou on met à jour) la stack
- name: Launch Immich
  command: docker compose up -d --remove-orphans
  args:
    chdir: /opt/docker/immich/

Multipliez par trente, et vous avez le bloc Services Docker. Ce qu’il y a dans les compose, ce sera l’épisode 7.

Les variables et Jinja

Le vrai intérêt des templates, c’est de ne plus copier-coller. Exemple avec les accès Tinyauth, déclarés dans vars/main.yml :

hostname: 'voskos'
snapraid_version: '12.4'
mergerfs_version: '2.38.0'
ntp_timezone: Europe/Paris
# Services protégés par Tinyauth (clé = sous-domaine)
tinyauth_apps:
  grafana: {}
  uptime-kuma: {}
  metube: { users: 'moi, robert' }   # celui-là, je le partage

Dans le compose de Traefik, une boucle génère la configuration de chaque service :

      # Politique deny : un service déclaré sans compte autorisé est refusé à tous
      - TINYAUTH_AUTH_ACLS_POLICY=deny
{% for id, app in tinyauth_apps.items() %}
      - TINYAUTH_APPS_{{ id | upper | replace('-', '') }}_CONFIG_DOMAIN={{ id }}.mondomaine.fr
      - TINYAUTH_APPS_{{ id | upper | replace('-', '') }}_USERS_ALLOW={{ app.users | default('moi') }}
{% endfor %}

Protéger un nouveau service = une ligne dans main.yml. Et si j’oublie de déclarer qui y a droit, personne n’y a droit. Je préfère une erreur 403 à une console d’admin ouverte aux quatre vents.

Les secrets avec Vault

Mots de passe, clés d’API, tokens : tout est dans vars/nas-secrets.yml, chiffré en AES-256 et commité tel quel.

$ANSIBLE_VAULT;1.1;AES256
6264336262396139353763636132633265656236
6166373763363435383235353935653839663464
…

Le mot de passe du coffre est dans un fichier .vault_pass, ignoré par Git. Dans les templates, un secret s’utilise comme n’importe quelle variable : {{ tinyauth_users }}.

# Modifier les secrets (déchiffre, ouvre l'éditeur, rechiffre)
ansible-vault edit vars/nas-secrets.yml

Les commandes du quotidien

# Récupérer les rôles Galaxy
ansible-galaxy install -r requirements.yml

# Tout appliquer (-K demande le mot de passe sudo)
ansible-playbook playbook.yml -i inventory --vault-password-file=.vault_pass -K

# Seulement les services Docker
ansible-playbook playbook.yml -i inventory --vault-password-file=.vault_pass -K --tags docker

# Tous les services sauf Hermes
ansible-playbook playbook.yml -i inventory --vault-password-file=.vault_pass -K --tags docker --skip-tags hermes

# Simuler sans rien appliquer, en affichant les différences
ansible-playbook playbook.yml -i inventory --vault-password-file=.vault_pass -K --check --diff

Ce qui n’est pas dans Ansible (parce qu’il y en a)

La recette a des trous. Autant les assumer.

  1. Tailscale et le serveur NFS. Installés à la main. Il faut que je le rajoute.
  2. La création de l’utilisateur et le changement de port SSH. Ils sont bien dans initial-config.yml… en commentaires. Le risque de modifier l’utilisateur principal est trop important pour moi.
  3. La box Gladys. Elle n’est pas dans l’inventaire. Le NAS sait lui parler, Ansible ne la connaît pas. A corriger aussi.
  4. Des tâches pas vraiment idempotentes. command: docker compose up -d est marqué changed à chaque passage. Pire : command: "echo 0 > /sys/…" pour couper le son de la carte mère. Le module command ne passe pas par un shell, donc la redirection > ne fait rien. Ce réglage n’a sans doute jamais été appliqué. A refaire.
  5. Un seul « rôle » fourre-tout. roles/nas/tasks n’a de rôle que le nom : pas de handlers, pas de defaults, juste une liste de fichiers. Je ne suis pas expert Ansible et je n’utilise pas toutes ses fonctionnalités.
  6. Des state: latest et aucun test. Les paquets se mettent à jour à chaque passage, donc deux lancements à un mois d’écart ne donnent pas le même serveur. Et rien ne vérifie le playbook avant qu’il touche la vraie machine. Aussi une limite de mon expertise.

Est-ce grave pour un serveur perso ? Non. Mais chaque trou, c’est une étape à refaire de mémoire le jour où le NAS tombe.

2023 → 2026 : chronique d’une dérive

L’historique Git raconte l’histoire mieux que moi.

  • Août – septembre 2023, la lune de miel. Premier commit le 23 août. Puis 21 commits en un mois : Plex, Homer, Jellyfin, ntfy, restic, Monica, Scrutiny, n8n, fail2ban… Et WireGuard, ajouté le 25 août, retiré le 9 septembre, remplacé par Tailscale. Amour de courte durée.
  • Fin 2023 – avril 2024, le rythme de croisière. Accélération matérielle pour Jellyfin, mqtt2prometheus, Audiobookshelf, Homarr. Dernier commit le 24 avril 2024.
  • Avril 2024 – mai 2026, le silence. Deux ans. Le serveur tourne, et moi je bricole en SSH : un service lancé « juste pour tester », un compose modifié sur place, une variable changée directement sur la machine.
  • Mai 2026, le réveil. Un audit de sécurité, et une première surprise : fail2ban était installé… mais arrêté. Depuis combien de temps ? Aucune idée. Mon image TinyAuth était vieille de 6 mois (mauvais repo).
  • Novembre 2026, la remise à plat. Le 15 novembre, un seul commit touche 74 fichiers : environ 1 900 lignes supprimées pour 1 000 ajoutées. 5 services réintégrés dans Ansible, 16 supprimés (Homarr, ntfy, Audiobookshelf, Monica, Radarr…) et 53 Go libérés sur le disque.

Ce qui s’est passé pendant ces deux ans porte un nom : le drift. C’est l’écart entre ce que décrit le code et ce qui tourne vraiment. Dans ma métaphore culinaire, c’est l’assaisonnement rectifié à la main, soir après soir, sans jamais toucher à la recette. Le plat reste bon… jusqu’au jour où il faut le refaire.

Petite anecdote qui résume bien le problème : plusieurs services déclaraient deux fois le label middlewares= de Traefik. Seul le dernier était appliqué. Aucune erreur, aucun log, et une protection qui n’existait que dans ma tête.

Claude, mon co-admin (avec l’humain dans la boucle)

La remise à plat de 2026, je ne l’ai pas faite seul. Claude, via Claude Code, a abattu une bonne partie du travail de fourmi. En trois temps.

  1. L’audit en lecture seule. Je lui ai donné un accès SSH en lecture seule au NAS. Résultat : un rapport classé par sévérité (4 points high, 7 medium, 5 low). Pour chaque point : le constat, la commande qui le prouve, le risque, et la tâche Ansible à écrire.
  2. La comparaison repo / machine. Le travail le plus ingrat : confronter chaque compose du repo à celui qui tourne, chaque variable, chaque volume. Exactement le genre de tâche que j’avais repoussée pendant deux ans.
  3. La refonte. Corrections, réintégration des services, ménage, avec un journal (AUDIT.md) tenu à jour à chaque étape.

Ce qui marche bien

  • La patience. Comparer trente compose ligne à ligne ne l’ennuie pas. Moi, si.
  • Les détails qu’on va d’habitude chercher dans la doc : la différence entre include et import, les variables de Tinyauth v5, la syntaxe d’un label Traefik.
  • La trace écrite. Chaque constat est documenté, donc relisible et discutable.

Les limites (parce qu’il y en a)

  1. Il faut relire. Chaque diff, chaque commande. Un agent avec les droits root sur votre NAS peut casser autant qu’il répare.
  2. Les accès se donnent au compte-gouttes. Lecture seule pour auditer. Pour modifier, c’est vous qui décidez de ce qui part en production. Toujours via Ansible.
  3. Le contexte, c’est vous. Il ne sait pas pourquoi un service existe, ni que votre frère s’en sert.
  4. Les secrets. C’est d’ailleurs en préparant cet article que j’ai découvert, dans des commentaires du repo, une clé d’API et un token en clair. Ce n’est plus le cas.

Comme avec une perceuse : l’outil est puissant, la responsabilité reste à celui qui le tient. J’en parlais déjà dans mon article sur Claude Code dans le cloud.

Mon avis

Ansible pour un seul serveur perso, c’est trop ? Non. Mais pas pour les raisons qu’on croit.

  • La première installation est plus longue. Écrire une tâche prend plus de temps que taper la commande. Le gain arrive à la deuxième fois : réinstallation, nouveau disque, migration.
  • Le repo est la meilleure documentation. Où est le compose d’Immich ? Quelle version de SnapRAID ? Réponse en dix secondes, sans se connecter au serveur.
  • Ansible ne protège pas de soi-même. Le drift ne vient pas de l’outil, il vient de la discipline. Deux ans de bricolage en SSH, et la recette ne valait plus grand-chose.

Si je ne devais garder qu’une règle de ces trois ans : si ce n’est pas dans le repo, ça n’existe pas.

Et pour la suite, la liste est déjà écrite (voir plus haut) : boucher les trous, découper en vrais rôles, et passer un --check --diff avant chaque lancement.

La suite

Prochain épisode : Services et Docker Compose. Comment chaque stack est écrite, les labels Traefik, Watchtower, et pourquoi :latest partout n’est pas une si bonne idée. Ensuite viendront la sécurité, puis les backups et la stratégie 3-2-1.

D’ici là, une question : votre homelab, il est dans un repo… ou dans votre tête ? 👇

Sources & documentation

Cyril Beslay

Papa de deux enfants, coureur de trail depuis plus de 13 ans et architecte d'entreprise de métier, j'écris sur Fotozik depuis 2007 : tutoriels tech, projets de home server (la série Projet Voskos), photographie, et réflexions sur ce qui me traverse la tête. Basé à Pau, toujours un peu geek, toujours un peu curieux.

Vous aimerez aussi...

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *