Anatomie de la configuration HAProxy

Publié le : 05/12/2024 à 10:00 Mis à jour le : 07/06/2026 à 13:41 Vues : 524

1. Les blocs de configuration

Le fichier haproxy.cfg est structuré en plusieurs sections (Global, Defaults, Frontend, Backend, Listen, Program) qui définissent le comportement global et le flux du trafic.

Section Global

La section global définit des paramètres au niveau du processus système (sécurité, performance, logs). Elle s'applique à l'ensemble de l'instance HAProxy.

global
    log /dev/log local0
    maxconn 4096
    user haproxy
    group haproxy
    daemon

Section Defaults

La section defaults permet d'éviter les répétitions. Les paramètres définis ici (mode, timeouts, logs) sont hérités par toutes les sections frontend et backend qui suivent.

defaults
    log global
    mode http
    timeout connect 5s
    timeout client 50s
    timeout server 50s

Section Frontend

Le frontend définit comment HAProxy reçoit les requêtes. On y précise l'adresse IP et le port d'écoute (bind), ainsi que les règles de routage (ACL) vers les backends.

frontend http-in
    bind *:80
    acl is_static path_beg /static
    use_backend static_servers if is_static
    default_backend app_servers

Section Backend

Le backend définit le pool de serveurs de destination. La syntaxe commence par le mot-clé backend suivi d'un nom unique. Pour déclarer plusieurs backends (par exemple pour séparer le trafic API du trafic Web), il suffit de définir plusieurs blocs avec des noms distincts.

backend app_servers
    balance roundrobin
    server web1 10.0.0.1:80 check

backend api_servers
    balance leastconn
    server api1 10.0.0.10:80 check

Section Listen

La section listen est un raccourci qui combine les fonctionnalités d'un frontend et d'un backend dans un seul bloc. C'est idéal pour les services simples comme l'exposition des statistiques ou le proxying TCP pur.

Note : Bien que pratique, ce rôle combiné n'est pas idéal pour les applications complexes composées de multiples domaines web et pools de serveurs. Dans ces cas, fusionner les fonctions peut complexifier inutilement la configuration. Nous recommandons alors de définir des sections frontend et backend séparées.

listen stats
    bind *:8404
    stats enable
    stats uri /monitor
    stats refresh 5s

Section Program

La section program permet à HAProxy de lancer et de surveiller des processus externes (disponible depuis la v2.2).

Note de dépréciation : La fonctionnalité program est dépréciée depuis HAProxy 3.1 et sera supprimée en version 3.3. D'ici là, son comportement change lors des rechargements : le processus maître démarre le programme, mais c'est un processus travailleur (worker) qui l'exécute. Il est désormais recommandé d'utiliser des gestionnaires de processus dédiés comme Systemd, SysVinit, Supervisord ou s6-overlays.

program my-agent
    command /usr/local/bin/agent-script.sh
    user haproxy
    group haproxy

2. Simplifier avec les inclusions

Comment organiser une configuration complexe en plusieurs fichiers.

Utilisation de dossiers de configuration

Plutôt que d'avoir un fichier unique de plusieurs milliers de lignes, HAProxy permet de charger un répertoire entier. Cela est particulièrement utile dans les environnements automatisés (Ansible, Puppet) où chaque application peut avoir son propre fichier de configuration.

Lors du lancement du service, on utilise l'argument -f pointant vers un dossier. HAProxy concatène les fichiers trouvés par ordre alphabétique.

haproxy -f /etc/haproxy/haproxy.cfg -f /etc/haproxy/conf.d/

Exemple d'organisation en production

Dans une production avec de nombreux services, on adopte souvent une nomenclature numérique pour contrôler l'ordre de chargement :

/etc/haproxy/
├── haproxy.cfg       # Global & Defaults
└── conf.d/
    ├── 10-frontend-http.cfg
    ├── 11-frontend-https.cfg
    ├── 20-backend-ecommerce.cfg
    ├── 21-backend-blog.cfg
    └── 99-stats.cfg

Cette structure permet d'ajouter ou supprimer une application simplement en gérant un fichier dans conf.d/, facilitant ainsi l'automatisation via CI/CD.

3. Mise à jour et Rechargement à chaud

Modifier la configuration sans interrompre le trafic.

Zéro Down-time Reload

HAProxy est conçu pour la haute disponibilité. Lorsque vous modifiez la configuration, vous pouvez recharger le service sans perdre de connexions actives. Le nouveau processus prend le relais sur les nouveaux sockets tandis que l'ancien termine de traiter les requêtes en cours.

# Vérifier la syntaxe avant de recharger
haproxy -c -f /etc/haproxy/haproxy.cfg

# Rechargement via systemd
systemctl reload haproxy

La Runtime API

Pour des modifications ultra-dynamiques (comme changer le poids d'un backend ou passer un serveur en maintenance) sans même recharger le fichier, HAProxy propose une Runtime API accessible via une socket Unix. Des outils comme socat ou l'utilitaire haproxy-cli permettent d'interagir avec cette API.

# Exemple : désactiver un serveur via la socket
echo "disable server app_servers/web1" | socat stdio /var/run/haproxy.stat

# Exemple : ajouter un nouveau serveur à chaud avec haproxy-cli
haproxy-cli exec "add server app_servers/web3 10.0.0.3:80 check"

Conclusion

La puissance par la modularité.

Une structure robuste

Maîtriser l'anatomie de la configuration HAProxy est la première étape pour construire des infrastructures résilientes. La séparation nette entre l'écoute (frontend) et le traitement (backend) offre une flexibilité que peu d'autres solutions égalent.