Stack 1 — Consul + Vault :

Cette stack déploie les services consul et vault avec leurs volumes, réseaux et configurations spécifiques. Elle utilise une syntaxe compatible Docker Compose, que Docker Swarm comprend et interprète sans souci.

Cette première stack prépare le backend de stockage de Vault avec Consul, et déploie Vault en mode serveur.

Explications des options clés :

• cap_add: IPC_LOCK : Permet à Vault de verrouiller sa mémoire et éviter que des secrets ne soient échangés sur le disque.
• volumes : Persistence des informations, chargement des configurations et synchronisation de l'heure avec l'hôte via /etc/localtime pour éviter les problèmes de logs et certificats.
• secrets: Les clés de chiffrement sont injectées de façon sécurisée via les secrets Swarm.
• networks: secret : Un réseau overlay Swarm dédié pour isoler la communication entre services.
• healthcheck : Teste périodiquement la disponibilité des services (ex: API Consul, endpoint santé Vault).
• deploy.restart_policy : Paramètres pour gérer automatiquement la résilience en cas d'erreurs.

Voici le fichier swarm_consul_vault.yml complet avec tous les commentaires qui expliquent chaque section en détail :

version: "3.8"

services:
  consul:
    image: hashicorp/consul:1.17
    ports:
      # Port web UI et API Consul
      - "8500:8500"
    volumes:
      # Configuration de Consul en lecture seule
      - /volume1/docker/secret/consul/config:/consul/config
      # Données persistantes pour Consul
      - /volume1/docker/secret/consul/data:/consul/data
      # Synchronisation de l'heure avec l'hôte pour cohérence temporelle
      - /etc/localtime:/etc/localtime:ro
    environment:
      # Informations sur le cluster Consul
      CONSUL_DATACENTER: Low-layer
      CONSUL_DOMAIN: consul
      CONSUL_NODE_NAME: synology-01-consul
      # Clé de chiffrement réseau, injectée via secret
      CONSUL_ENCRYPT_KEY_FILE: /run/secrets/consul-encrypt-key
      # Identifiants utilisateur/groupe pour permissions d'accès
      PUID: 1027
      PGID: 100
    command: sh /consul/config/start_consul.sh
    networks:
      - secret
    secrets:
      # Secret Consul encrypt key externe
      - consul-encrypt-key
    healthcheck:
      # Test pour vérifier que Consul est joignable
      test: ["CMD", "consul", "members", "-http-addr=http://localhost:8500"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 30s
        max_attempts: 20
        window: 600s

  vault:
    image: hashicorp/vault:1.15
    cap_add:
      # Verrouillage mémoire pour éviter le swap des secrets sur disque
      - IPC_LOCK
    ports:
      # Port de l'API Vault et UI accessible via 8200
      - "8200:8200"
    volumes:
      # Configuration Vault
      - /volume1/docker/secret/vault/config:/vault/config
      # Synchronisation de l'heure avec l'hôte pour éviter dérives
      - /etc/localtime:/etc/localtime:ro
    environment:
      PUID: 1027
      PGID: 100
    command: vault server -config=/vault/config/vault.hcl
    networks:
      - secret
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 30s
        max_attempts: 20
        window: 600s
    healthcheck:
      # Vérifie la santé de Vault, accepte aussi état non initialisé ou scellé
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8200/v1/sys/health?uninitcode=200&sealedcode=200"]
      interval: 30s
      timeout: 10s
      retries: 10
      start_period: 120s

# Secrets à créer à la main avant déploiement
secrets:
  consul-encrypt-key:
    external: true

# Réseau chiffré Swarm externe déjà créé (overlay)
networks:
  secret:
    name: secret
    external: true

Stack 2 — Vault Agent :

Cette stack déploie le vault_agent, un client Vault qui s'exécute sur tous les nœuds (mode global). Il s'authentifie via un AppRole sécurisé (avec role_id et secret_id) et récupère les secrets, en particulier les certificats, qu'il écrit directement dans les emplacements système des NAS Synology.

Pourquoi deux stacks ?

• Première stack : déploie le backend consul + vault, nécessaire pour initialiser et faire tourner Vault.
• Deuxième stack : déploie l'agent Vault qui consomme les secrets, il ne peut être lancé qu'après que Vault est initialisé et déverrouillé.

Explications des options clés :

• user: root pour avoir tous les droits nécessaires.
• cap_add: IPC_LOCK pour verrouiller la mémoire et protéger les secrets.
• cap_add: SYS_CHROOT pour utiliser chroot et accéder au système hôte, notamment pour redémarrer des services.
• volumes importants :
  • Les configs agent et templates de certificats.
  • L'emplacement des certificats Synology (avec RW).
  • L'accès au système hôte en lecture pour contrôle et actions.
• secrets : injection des role_id et secret_id via secrets Docker Swarm.
• deploy.mode: global pour garantir la présence d'un agent par nœud.

Voici le fichier swarm_vault_agent.yml complet avec commentaires pour bien comprendre chaque partie :

version: "3.8"

services:
  vault_agent:
    image: hashicorp/vault:1.15
    user: root
    cap_add:
      # Protection mémoire pour éviter le swap des secrets
      - IPC_LOCK
      # Permet d'utiliser chroot pour accéder au système hôte (ex: pour redémarrer nginx)
      - SYS_CHROOT 
    volumes:
      # Configuration de l'agent Vault
      - /volume1/docker/secret/vault_agent/config:/vault/config
      # Templates des certificats TLS à générer
      - /volume1/docker/secret/vault_agent/templates:/vault/templates
      # Emplacement des certificats Synology, accès lecture/écriture
      - /usr/syno/etc/certificate/_archive:/certs:rw
      # Synchronisation horaire avec l'hôte
      - /etc/localtime:/etc/localtime:ro
      # Accès en lecture au système hôte pour contrôle et redémarrage
      - /:/host:ro
    secrets:
      # Credentials AppRole Vault injectés via secrets Swarm
      - vault-role-id
      - vault-secret-id
    command: sh -c "vault agent -config=/vault/config/agent.hcl"
    networks:
      - secret
    deploy:
      # Lancement d'un agent sur chaque nœud du Swarm
      mode: global
      restart_policy:
        condition: any
        delay: 30s
        max_attempts: 20
        window: 600s

# Secrets AppRole à créer manuellement avant déploiement
secrets:
  vault-role-id:
    external: true
  vault-secret-id:
    external: true

# Réseau chiffré overlay Swarm partagé entre services
networks:
  secret:
    name: secret
    external: true

Le server.hcl : Quand la simplicité rencontre l'efficacité

Ce fichier server.hcl est probablement le plus court de notre stack, mais ne t'y trompes pas ce petit fichier optimise silencieusement les performances de Consul.

Le multiplicateur Raft :

Consul utilise l'algorithme Raft pour maintenir la cohérence des données dans le cluster. Ce multiplicateur est un facteur d'échelle qui affecte directement les timeouts de HeartbeatTimeout, ElectionTimeout et LeaderLeaseTimeout.

raft_multiplier = 1 Configuration haute performance recommandée pour la production. HashiCorp recommande de configurer ce paramètre à 1 en production pour permettre aux serveurs Consul de détecter rapidement une défaillance du leader et de terminer les élections de leader beaucoup plus rapidement.

En résumé, ce fichier fait exactement ce qu'il faut : il configure Consul pour qu'il fonctionne avec les performances optimales recommandées par HashiCorp. Contrairement aux idées reçues, la valeur 1 n'est pas la "configuration par défaut" mais bien la configuration haute performance pour la production !

# Configuration de performance pour Consul
performance {
  # Multiplicateur Raft pour ajuster les timeouts
  # Valeur 1 = configuration pour la production
  raft_multiplier = 1
}

Le start_consul.sh : Quand Docker rencontre l'auto-configuration

Le script shell start_consul.sh fait le travail ingrat que personne ne veut faire : récupérer automatiquement l'IP du conteneur et démarrer Consul avec les bons paramètres. Parce que personne n'a envie de faire du docker inspect à chaque redémarrage !

🔍 Détection automatique de l'IP

IP=$(getent hosts $HOSTNAME | awk '{ print $1 }') - Cette ligne magique récupère l'IP du conteneur dans le réseau Docker. Plus besoin de deviner ou de hardcoder une IP !

🚀 Paramètres de démarrage Consul :

• -server Mode serveur (pas agent)
• -ui Active l'interface web
• -client="0.0.0.0" Écoute sur toutes les interfaces
• -bind="$IP" IP d'écoute pour le cluster
• -advertise="$IP" IP annoncée aux autres nœuds

⚠️ Configuration cluster mono-nœud :

-bootstrap-expect=1 indique à Consul qu'il n'y aura qu'un seul serveur dans le cluster. Parfait pour notre NAS, mais attention à ne pas utiliser cette configuration pour un vrai cluster distribué !

📁 Répertoires et logs :

• -data-dir="/consul/data" - Stockage persistant des données
• -config-dir="/consul/config" - Répertoire de configuration
• -log-level="INFO" - Niveau de logs équilibré
• -disable-host-node-id=true - Désactive l'ID basé sur l'hôte (recommandé pour Docker)

Le exec final remplace le processus shell par Consul, permettant une gestion propre des signaux Docker (PID 1). C'est la différence entre un script amateur et un script professionnel !

#!/bin/sh

# Retrieves the IP on the 'secret' network (adapt the interface name if needed)
IP=$(getent hosts $HOSTNAME | awk '{ print $1 }')

echo "Starting Consul with IP: $IP"

# Read encryption key in secret Docker Swarm
if [ -f /run/secrets/consul-encrypt-key ]; then
    ENCRYPT_KEY=$(cat $CONSUL_ENCRYPT_KEY_FILE)
    echo "Encrypt key load from secret"
else
    echo "ERROR: Secret consul-encrypt-key not found!"
    exit 1
fi


exec consul agent \
  -server \
  -ui \
  -client="0.0.0.0" \
  -bind="$IP" \
  -advertise="$IP" \
  -bootstrap-expect=1 \
  -data-dir="/consul/data" \
  -config-dir="/consul/config" \
  -log-level="INFO" \
  -encrypt="$ENCRYPT_KEY" \
  -datacenter="$CONSUL_DATACENTER" \
  -domain="$CONSUL_DOMAIN" \
  -node="$CONSUL_NODE_NAME" \
  -disable-host-node-id=true

Le vault.hcl : Configuration du coffre-fort numérique

Ce fichier vault.hcl est le cerveau de notre Vault. Contrairement au server.hcl minimaliste, celui-ci contient tous les paramètres essentiels pour faire tourner notre coffre-fort en mode production.

Interface Web et Backend de stockage

ui = true Active l'interface web de Vault, parce que personne n'a envie de tout faire en ligne de commande (même si c'est possible).

Le stockage Consul : Mariage parfait

storage "consul" Vault utilise Consul comme backend de stockage. C'est du mariage arrangé qui fonctionne parfaitement : Consul gère la persistance, Vault gère la sécurité. Pour une solution encore plus simple, il est tout à fait possible de se passer complètement de Consul et de configurer Vault pour qu'il stocke ses données directement sur l'hôte, via un backend comme file.

Paramètres de stockage Consul :

• address = "consul:8500" Adresse du serveur Consul (nom Docker)
• path = "vault/" Chemin de stockage dans le KV store Consul
• scheme = "http" Protocole HTTP (réseau interne sécurisé)
• session_ttl = "15s" Durée de vie des sessions Consul
• lock_wait_time = "15s" Temps d'attente pour les verrous

Listener TCP : L'oreille de Vault

listener "tcp" Configuration du listener HTTP sur le port 8200 avec TLS désactivé car géré par le reverse proxy Synology. Le chiffrement ne sera pas strictement de bout en bout, puisque c'est le reverse proxy qui termine la connexion TLS. Cependant, comme ce proxy est hébergé sur le même hôte que Vault, le trafic non chiffré entre le proxy et Vault ne transite que sur l'interface localhost.

Configuration X-Forwarded-For :

Les paramètres x_forwarded_for_* permettent à Vault de récupérer les vraies adresses IP des clients qui passent par le reverse proxy. Essentiel pour l'audit et la sécurité !

Configuration des baux (leases) :

• default_lease_ttl = "168h" 7 jours par défaut pour les secrets
• max_lease_ttl = "720h" 30 jours maximum, parce qu'il faut bien une limite
• api_addr = "https://vault.internal" URL publique via le reverse proxy

Logs et monitoring :

log_level = "INFO" et log_format = "standard" Configuration optimisée pour Synology avec logs lisibles et niveau d'information approprié.

🔧 Détail technique :

disable_mlock = false Active le verrouillage mémoire (mlock) pour éviter que des secrets ne se retrouvent dans le swap. C'est la bonne pratique recommandée par HashiCorp pour une instance sérieuse de Vault. Par défaut, les containers Docker ne peuvent pas utiliser mlock(), mais ici on a ajouté la capacité IPC_LOCK (merci cap_add), ce qui permet à Vault de protéger ses secrets correctement, même en container. Bref, si tu veux dormir tranquille, tu laisses ça à false (oui, c'est contre-intuitif, mais c'est bien false qui signifie : "je n'empêche pas Vault d'utiliser mlock()"). 🛡️

disable_clustering = true Désactive le clustering Vault car nous n'avons qu'un seul nœud. Simplifie la configuration.

# Active l'interface web de Vault
ui = true

# Configuration du backend de stockage Consul
storage "consul" {
  # Adresse du serveur Consul
  address = "consul:8500"
  # Chemin de stockage dans Consul
  path    = "vault/"
  # Protocole (HTTP car réseau interne)
  scheme  = "http"
  
  # Configuration de session Consul
  # Durée de vie des sessions
  session_ttl = "15s"
  # Temps d'attente pour les verrous
  lock_wait_time = "15s"
}

# Listener HTTP - TLS géré par le reverse proxy Synology
listener "tcp" {
  address     = "0.0.0.0:8200"
  # TLS désactivé (géré par le reverse proxy)
  tls_disable = 1
  
  # Configuration pour les en-têtes X-Forwarded-For
  x_forwarded_for_authorized_addrs = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
  x_forwarded_for_hop_skips = 0
  x_forwarded_for_reject_not_authorized = false
  x_forwarded_for_reject_not_present = false
}

# Configuration pour le reverse proxy HTTPS
# URL publique via reverse proxy
api_addr = "https://vault.internal"
disable_clustering = true

# Activer mlock pour éviter le swap sur l'hôte
disable_mlock = false

# Configuration des logs
log_level = "INFO"
# Format lisible pour Synology
log_format = "standard"

# Configuration des baux (leases)
# 7 jours par défaut
default_lease_ttl = "168h"
# 30 jours maximum
max_lease_ttl = "720h"

Le agent.hcl : Le chef d'orchestre de l'automatisation

Le agent.hcl configure Vault-Agent, le composant qui transforme notre infrastructure en véritable usine à certificats automatisée. C'est lui qui se connecte à Vault, s'authentifie tout seul comme un grand, et génère nos certificats SSL sans intervention humaine.

Configuration de connexion à Vault

La section vault définit comment l'agent se connecte au serveur Vault avec une stratégie de retry robuste (5 tentatives) pour gérer les redémarrages et les problèmes réseau temporaires. Chaque tentative est plus longue que la précédente afin de laisser le temps au Vault de démarrer.

Authentification automatique :

L'agent utilise la méthode AppRole pour s'authentifier automatiquement auprès de Vault.

Template magic :

La section template est le cœur de l'automatisation. Elle surveille le template /vault/templates/cert.tpl et génère automatiquement les certificats.

🔧 Détail technique :

disable_mlock = false Active le verrouillage mémoire (mlock) pour éviter que des secrets ne se retrouvent dans le swap. C'est la bonne pratique recommandée par HashiCorp pour une instance sérieuse de Vault. Par défaut, les containers Docker ne peuvent pas utiliser mlock(), mais ici on a ajouté la capacité IPC_LOCK (merci cap_add), ce qui permet à Vault de protéger ses secrets correctement, même en container. Bref, si tu veux dormir tranquille, tu laisses ça à false (oui, c'est contre-intuitif, mais c'est bien false qui signifie : "je n'empêche pas Vault d'utiliser mlock()"). 🛡️

En résumé, ce fichier transforme Vault-Agent en véritable assistant personnel qui gère tout le cycle de vie des certificats SSL : authentification, génération, déploiement et redémarrage des services. Plus besoin de se lever à 3h du matin parce qu'un certificat a expiré !

# Configuration de connexion à Vault
vault {
  address = "http://vault:8200"
  retry {
    # Nombre de tentatives de reconnexion
    num_retries = 5
  }
}

# Authentification automatique via AppRole
auto_auth {
  method "approle" {
    mount_path = "auth/approle"
    config = {
      # Fichiers contenant les identifiants AppRole
      role_id_file_path   = "/run/secrets/vault_role_id"
      secret_id_file_path = "/run/secrets/vault_secret_id"
      # Garde le secret_id pour éviter les re-authentifications
      remove_secret_id_file_after_reading = false
    }
  }
}

# Activer mlock pour éviter le swap sur l'hôte
disable_mlock = true

# Template pour générer les certificats SSL
template {
  # Template source
  source      = "/vault/templates/cert.tpl"
  # Fichier de sortie
  destination = "/certs/myCert/all-certs"
  # Script post-génération
  command     = "/bin/sh /vault/config/restart_service.sh"
}

Le restart_service.sh : Quand Docker rencontre Synology

Le script restart_service.sh fait le lien entre notre conteneur Vault Agent et le système hôte Synology. Il permet de redémarrer nginx (ou d'autres services) automatiquement après la mise à jour des certificats, évitant ainsi toute intervention manuelle.

En résumé, ce script court et simple est une solution pragmatique et efficace pour relier Vault Agent et la gestion des services système sous Synology.

#!/bin/bash

# Script de redémarrage automatique des services après mise à jour des certificats
# Utilisé par Vault Agent via la directive `command` dans le template

set -euo pipefail

NGINX_RESTART_CMD="chroot /host /usr/syno/bin/synosystemctl restart nginx"

echo "Certificates deployed"

echo "Restarting nginx..."
if $NGINX_RESTART_CMD; then
   echo "Nginx restarted successfully"
else
   echo "Error while restarting nginx"
   exit 1
fi

echo "Deployment completed successfully"