1. Introduction à la gestion dynamique
Traditionnellement, modifier la structure des backends nécessitait un reload du fichier de configuration. La Runtime API permet désormais d'effectuer ces changements en mémoire.Attention : L'ajout et la suppression dynamique de backends et serveurs via la Runtime API nécessite HAProxy 2.8 ou une version supérieure.
Configuration de base
Pour utiliser ces commandes, votre instance HAProxy doit exposer une socket d'administration avec un niveau admin dans la section global de votre configuration :
En classique :stats socket /run/haproxy/admin.sock user haproxy group haproxy mode 660 level adminstats socket ipv4@127.0.0.1:9999 level admin expose-fd listeners2. Lexique des commandes clés
Pour manipuler l'infrastructure à chaud, il est essentiel de comprendre le rôle de chaque verbe de la Runtime API.
help
La commande help permet d'afficher l'ensemble des commandes possibles. La syntaxe est donc la suivante, seul le endpoint change en fonction du type d'activation que vous avez fait:
Le chemin à utiliser avec socat peut changer en fonction de votre configuration
- Classique :
echo 'help' | socat stdio /var/run/haproxy.stat - IP/PORT :
echo 'help' | socat stdio tcp4-connect:127.0.0.1:9999
add (backend / server)
La commande add permet de créer un nouvel objet (backend ou serveur) en mémoire. Un backend peut être créé ex nihilo ou en héritant des paramètres d'une section defaults existante (indispensable pour les timeouts).
Attention : Il est possible d'avoir des problèmes de résolution quand vous ajoutez un serveur. Cela peut se voir en lançant cette commande dans laquelle vous verez qu'un serveur n'a pas d'IP :Et vous pouvez éviter cela en précalculant l'IP :$ echo "show servers conn default" | socat stdio /run/haproxy/admin.sock # bkname/svname bkid/svid addr port - purge_delay served used_cur used_max need_est idle_sess unsafe_nb safe_nb idle_lim idle_cur idle_per_thr[10] default/web1 4/1 192.168.48.3 80 - 5000 0 0 1 1 0 0 0 -1 0 0 0 0 0 0 0 0 0 0 0 default/web2 4/2 192.168.48.2 80 - 5000 0 0 1 1 0 0 0 -1 0 0 0 0 0 0 0 0 0 0 0 default/web3 4/3 - 80 - 5000 0 0 0 0 0 0 0 -1 0 0 0 0 0 0 0 0 0 0 0IP=$(getent hosts web3 | awk '{print $1}'); echo "add server default/web3 $IP:80 check" | socat stdio /run/haproxy/admin.sock
enable (server / health)
Par défaut, un serveur ajouté dynamiquement est en mode maintenance (maint). enable server le rend opérationnel. enable health active spécifiquement les tests de santé (health checks) pour ce serveur.
publish (backend)
C'est une étape de validation. Tant qu'un backend n'est pas publié, il est invisible pour les frontends, même s'il existe en mémoire. Cela permet de configurer entièrement un pool avant de l'exposer au trafic.
map (add / show / del)
Les Maps sont des tables de correspondance (ex: URL -> Backend) stockées en mémoire. add map ajoute une règle de routage, del map la supprime, et show map permet de déboguer le contenu de la table sans recharger HAProxy.
3. Ajouter un backend et un serveur
Voici le workflow pour créer un nouveau pool de serveurs et le rendre disponible.
Création et activation
Le processus se décompose en 4 étapes clés : l'ajout du backend, l'ajout du serveur, l'activation de la santé et la publication.
# 1. Ajouter le backend en héritant d'une section defaults
echo "add backend test-backend from mydefaults mode http" | socat stdio unix-connect:/run/haproxy/admin.sock
# 2. Ajouter un serveur au backend
echo "add server test-backend/server1 127.0.0.1:3000 check" | socat stdio unix-connect:/run/haproxy/admin.sock
# 3. Activer le serveur et ses health checks
echo "enable server test-backend/server1" | socat stdio unix-connect:/run/haproxy/admin.sock
echo "enable health test-backend/server1" | socat stdio unix-connect:/run/haproxy/admin.sock
# 4. Publier le backend pour le rendre utilisable par les frontends
echo "publish backend test-backend" | socat stdio unix-connect:/run/haproxy/admin.sockRoutage dynamique via Map files
Pour diriger du trafic vers ce nouveau backend sans modifier le frontend, utilisez les fichiers de mapping en mémoire :
# Associer le chemin /test au nouveau backend
echo "add map virt@paths.map /test test-backend" | socat stdio unix-connect:/run/haproxy/admin.sock4. Supprimer un backend proprement
La suppression nécessite de respecter un ordre précis pour ne pas rompre les connexions en cours.
Procédure de retrait
Il est impératif de passer le serveur en maintenance et d'attendre qu'il soit 'removable' avant la suppression physique.
# 1. Passer le serveur en maintenance
echo "set server test-backend/server1 state maint" | socat stdio unix-connect:/run/haproxy/admin.sock
# 2. Attendre et supprimer le serveur
echo "wait 2s srv-removable test-backend/server1; del server test-backend/server1" | socat stdio unix-connect:/run/haproxy/admin.sock
# 3. Dé-publier et supprimer le backend
echo "unpublish backend test-backend" | socat stdio unix-connect:/run/haproxy/admin.sock
echo "wait 2s be-removable test-backend; del backend test-backend" | socat stdio unix-connect:/run/haproxy/admin.sock5. Points d'attention importants
Quelques règles de comportement du moteur HAProxy à connaître.
Publication et Force Switch
Un backend référencé par un use_backend sera ignoré s'il n'est pas publié. Pour forcer l'utilisation même s'il est 'unpublished', utilisez la directive force-be-switch.
Gestion de la mémoire
Pour permettre l'ajout dynamique, HAProxy conserve les sections defaults en mémoire. Si vous n'utilisez pas de backends dynamiques, vous pouvez libérer cette mémoire avec la directive globale suivante :
global
tune.defaults.purge onConclusion
Vers une automatisation totale
Cette approche est idéale pour coupler HAProxy à des outils comme Consul ou des contrôleurs personnalisés, permettant de scaler votre infrastructure sans jamais générer de micro-coupures liées aux rechargements de processus.