Les APIs essentielles pour les load balancers
Ta config manuelle ne survit pas à un pool qui bouge. Voici les APIs qui pilotent vraiment un load balancer, avec les commandes qui servent en prod.
Un pool de 40 backends, une mise à jour de config poussée à 14 h, et trois minutes plus tard 12 % des requêtes tombent en 502. La faute ne vient pas du load balancer : elle vient de la personne qui a touché au pool sans passer par son API. Un load balancer se pilote par API, pas par un fichier de conf édité à la main.
Tu vas voir les interfaces qui comptent réellement en production : health checks, configuration dynamique, métriques, et les APIs cloud qui orchestrent tout ça.
Pourquoi l'API change tout (et pas seulement le confort)
Un rechargement de configuration HAProxy coûte un reload complet : nouveau process, nouvelles sockets, et quelques millisecondes de trou si ton hard-stop-after est mal réglé. Sur un cluster qui bouge toutes les cinq minutes, tu ne tiens pas.
L'API de configuration résout ça en modifiant l'état à chaud, sans toucher au process. C'est la différence entre « je déploie une nouvelle version du fichier » et « je retire le serveur 10.0.0.7 du pool maintenant ».
Trois modèles coexistent, et il faut savoir lequel tu as sous la main :
- API REST dédiée — HAProxy Data Plane API, NGINX Plus API, Traefik API. Lecture/écriture par HTTP, transactions ou pas.
- Socket de contrôle local — runtime API HAProxy via
socat, très rapide, mais non réseau et sans authentification propre. - API cloud — AWS ELBv2, Google Cloud Load Balancing. Tu ne configures pas un serveur, tu déclares des ressources et tu interroges leur santé.
Et il y a Envoy, à part : pas d'API REST stable, mais un protocole de découverte xDS en gRPC qui est devenu le standard de l'industrie. J'y reviens plus bas.
Health checks : l'API que tu appelles sans le savoir
Un health check est un contrat entre le load balancer et ton application. Le LB appelle une URL, lit un code de statut, et décide. Si ton endpoint répond 200 alors que la base est injoignable, tu envoies du trafic vers un serveur mort — et tu ne le sauras qu'à la première erreur utilisateur.
Le minimum viable côté application, en FastAPI :
from fastapi import FastAPI, Response
import asyncpg
app = FastAPI()
@app.get("/healthz")
async def healthz(response: Response):
try:
conn = await asyncpg.connect(dsn=DB_DSN, timeout=1.5)
await conn.fetchval("SELECT 1")
await conn.close()
except Exception:
response.status_code = 503
return {"status": "db unreachable"}
return {"status": "ok"}Deux règles que j'applique systématiquement : un timeout interne plus court que le timeout du check (1,5 s contre 2 s), et un endpoint séparé du / public pour ne pas polluer les métriques d'usage.
Côté HAProxy, la supervision active se déclare dans le backend :
backend app
option httpchk GET /healthz
http-check expect status 200
default-server inter 2s fastinter 500ms downinter 5s fall 3 rise 2
server web1 10.0.0.11:8080 check
server web2 10.0.0.12:8080 checkTraduction : un check toutes les 2 s, passage en down après 3 échecs consécutifs, retour après 2 succès. Avec ces valeurs, un backend défaillant est retiré en 6 s et remis en 4 s.
Health check passif et actif ne s'opposent pas, ils se complètent. Le passif (observe layer7-error-rate) détecte les 502 que le check actif ne voit pas, parce que l'endpoint /healthz va bien mais une route métier casse.
La configuration dynamique : HAProxy Data Plane API
La Data Plane API v3 travaille par transactions. Tu ouvres une transaction, tu modifies une ou plusieurs ressources, tu la valides — et HAProxy applique l'ensemble de façon atomique.
Exemple concret : basculer un serveur en maintenance pendant un déploiement.
# 1. ouvrir une transaction
TX=$(curl -s -u admin:$DPAPI_PASS -X POST \
"https://lb.example.com:5555/v3/services/haproxy/transactions?version=42" \
| jq -r '.id')
# 2. passer le serveur en maintien
curl -s -u admin:$DPAPI_PASS -X PUT \
"https://lb.example.com:5555/v3/services/haproxy/configuration/servers/web1?backend=app&transaction_id=$TX" \
-H 'Content-Type: application/json' \
-d '{"name":"web1","address":"10.0.0.11","port":8080,"state":"maint"}'
# 3. valider la transaction
curl -s -u admin:$DPAPI_PASS -X PUT \
"https://lb.example.com:5555/v3/services/haproxy/transactions/$TX"Le paramètre version=42 est ta protection contre les écritures concurrentes : si quelqu'un a modifié la config entre-temps, la version ne correspond plus et l'API refuse. Sans ce garde-fou, deux pipelines Terraform peuvent s'écraser mutuellement sans que personne ne le remarque.
Si tu n'as pas besoin d'atomicité multi-ressources, la runtime API via socket est plus directe et ne demande aucun port réseau :
echo "set server app/web1 state drain" | sudo socat stdio /var/run/haproxy.sock
echo "show servers state app" | sudo socat stdio /var/run/haproxy.sockdrain est différent de maint : le serveur n'accepte plus de nouvelles connexions mais laisse finir les requêtes en cours. C'est exactement ce qu'il faut avant de tuer un conteneur.
Traefik et NGINX Plus, même logique
Traefik expose une API REST en lecture quand tu actives --api=true, avec un accès en écriture aux serveurs d'un load balancer :
curl -s http://traefik:8080/api/http/services | jq '.[] | select(."@type"=="service") | .name'
curl -s -X PUT http://traefik:8080/api/http/services/app@docker/loadbalancer/servers/0 \
-d '{"url":"http://10.0.0.21:8080"}'NGINX Plus fait la même chose via /api/9/http/upstreams/app/servers/, avec un POST qui accepte weight, max_conns et down. Attention : NGINX open source n'a pas d'API de configuration. Si tu lis un tutoriel qui te promet le contraire, il parle de NGINX Plus.
Les APIs de métriques : ce que tu dois scraper
Sans métriques, un load balancer est une boîte noire qui distribue du trafic jusqu'au jour où elle ne le fait plus. Voici les trois sources que je branche systématiquement sur Prometheus.
| Source | Endpoint | Métrique clé |
|---|---|---|
| HAProxy | :8404/metrics (exporter) ou socket show stat | haproxy_server_check_failures_total |
| NGINX | stub_status sur un location dédié | nginx_connections_active |
| AWS ELBv2 | CloudWatch namespace AWS/ApplicationELB | UnHealthyHostCount, TargetResponseTime |
Le stub_status de NGINX reste le moyen le plus court d'avoir un pouls sans module tiers :
location = /basic_status {
stub_status;
allow 10.0.0.0/8;
deny all;
}La réponse tient en trois lignes et contient tout ce qui compte en cas d'incident :
Active connections: 291
server accepts handled requests
16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106Écart entre accepts et handled non nul ? Tu drops des connexions. Waiting qui grimpe alors que Active stagne ? Tes keepalive absorbent, mais tes workers saturent. Deux chiffres, deux diagnostics.
Côté HAProxy, la métrique qui m'a le plus servi n'est pas le trafic mais haproxy_server_up. Une alerte sur haproxy_server_up == 0 pendant plus de 60 s attrape les pannes silencieuses, celles où tout fonctionne à 70 % de capacité parce qu'un backend est sorti du pool.
Les APIs cloud : déclarer plutôt que configurer
Sur AWS, tu ne configures pas un serveur : tu enregistres des cibles dans un target group et tu interroges leur santé. Le cycle de vie d'un déploiement bleu/vert tient en deux commandes.
aws elbv2 describe-target-health \
--target-group-arn arn:aws:elasticloadbalancing:eu-west-3:123456789012:targetgroup/app-blue/6d0ecf831eec9f09 \
--query 'TargetHealthDescriptions[].{id:Target.Id,state:TargetHealth.State}'
aws elbv2 deregister-targets \
--target-group-arn arn:aws:elasticloadbalancing:eu-west-3:123456789012:targetgroup/app-blue/6d0ecf831eec9f09 \
--targets Id=i-0abc123,Port=8080deregister-targets ne coupe pas net : une période de drainage de 300 s par défaut laisse les requêtes en cours se terminer. Si ton application a des requêtes de 7 minutes, ce défaut te ment — passe deregistration_delay.timeout_seconds à 420.
Google Cloud suit la même grammaire avec backendServices et healthChecks, mais la santé d'un backend n'est pas dans le load balancer : elle remonte via le health check attaché. Tu ne peux pas forcer un backend à unhealthy par API, tu peux seulement changer le health check ou retirer le backend du groupe. Cette asymétrie surprend quand on vient d'AWS.
Le piège transversal, c'est le throttling. Les APIs ELBv2 et Compute sont limitées par compte et par région, et un script de déploiement qui boucle sur 200 cibles en describe-target-health individuel se fait jeter en ThrottlingException. Batch quand c'est possible, mets du backoff exponentiel, et mets en cache les ARN.
Envoy et xDS : le standard que tout le monde copie
Envoy n'a pas d'API REST de configuration, et c'est volontaire. À la place, il consomme quatre flux gRPC : LDS pour les listeners, RDS pour les routes, CDS pour les clusters, EDS pour les endpoints.
Concrètement, EDS envoie des ClusterLoadAssignment qui contiennent les adresses et leur health_status. Le control plane peut marquer un endpoint DRAINING sans redémarrer quoi que ce soit, et Envoy arrête instantanément de lui envoyer du trafic neuf.
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address: { address: 10.0.0.31, port_value: 8080 }
health_check_config:
port_value: 8080
health_status: HEALTHY
- endpoint:
address:
socket_address: { address: 10.0.0.32, port_value: 8080 }
health_status: DRAININGCe modèle est un flux persistant : pas de polling, pas de fenêtre de stale, et une propagation en quelques dizaines de millisecondes. C'est la raison pour laquelle Istio, Consul Connect, Cilium et les load balancers managés de Google s'appuient tous dessus.
Si tu montes une plateforme Kubernetes, tu n'auras probablement jamais à écrire d'xDS à la main — mais tu dois savoir que c'est le mécanisme sous ton Ingress. Ça explique beaucoup de comportements étranges lors des rolling updates, notamment les 502 de quelques secondes. J'ai détaillé ce point dans les outils incontournables pour les load balancers.
Quelle API pour quel usage
Après plusieurs années à brancher ces interfaces sur des plateformes différentes, ma règle est simple : le load balancer n'est jamais l'endroit où tu prends tes décisions, c'est l'endroit où tu les appliques.
| Besoin | API à utiliser | Fréquence réaliste |
|---|---|---|
| Retirer un backend pour maintenance | Data Plane API (transaction) ou socket runtime | À chaque déploiement |
| Ajouter un serveur après autoscaling | EDS / API du control plane | Toutes les 30–120 s |
| Surveiller l'état des cibles | CloudWatch / Prometheus exporter | Toutes les 15 s |
| Basculer de version (bleu/vert) | ELBv2 register-targets | Une fois par release |
Deux règles d'architecture qui évitent 90 % des incidents que j'ai vus. Première règle : l'API de configuration n'est jamais exposée sur Internet. Data Plane API en 127.0.0.1:5555 ou derrière un VPN, socket runtime en permissions 660 sur un groupe dédié. Deuxième règle : tout changement passe par le même chemin, y compris les urgences — un socat manuel à 3 h du matin qui n'est pas dans le code est une dette qui se paiera au prochain déploiement.
Et si tu cherches à industrialiser ces appels depuis un outil interne, la mécanique d'authentification et de pagination est décrite dans les APIs utiles d'infrastructure : c'est le même schéma partout, seuls les noms changent.
Les pièges qui coûtent une astreinte
Le health check trop lent. Un inter 10s fall 3 met 30 s à sortir un backend mort. Pendant ces 30 s, un tiers de ton trafic part dans le vide si tu n'as que trois serveurs.
Le drain oublié. Retirer une cible de l'enregistrement DNS ne coupe rien : les clients gardent la connexion ouverte. Le drain doit se faire côté load balancer, et dans le bon ordre — d'abord drain, attendre la fin des connexions, puis maint.
L'API qui ne dit pas qu'elle a échoué. Un 200 sur un PUT ne garantit pas l'application : sur HAProxy, c'est la validation de la transaction qui déclenche l'écriture, et une transaction abandonnée expire au bout de 30 s. Si ton script ne valide pas, il ne s'est rien passé.
Les identifiants dans le pipeline. Les clés d'API cloud et les secrets Data Plane API finissent souvent en variable d'environnement de CI, lisibles par tous les jobs. Je les sors d'un coffre au démarrage du process, jamais d'un fichier versionné.
FAQ
Peut-on piloter NGINX open source par API de configuration ?
Non. L'API /api/ est une fonctionnalité NGINX Plus. En open source, tu as stub_status pour les métriques et un reload de process pour la configuration — ce qui provoque une coupure de quelques millisecondes selon les versions.
Faut-il préférer la Data Plane API ou le socket HAProxy ?
Le socket pour les actions unitaires rapides (set server ... state drain), la Data Plane API pour tout ce qui doit être atomique ou versionné. Le socket ne garde aucune trace : aucune auditabilité, aucun rollback.
À quelle fréquence interroger describe-target-health ?
Pas plus d'une fois toutes les 10 s par target group, et uniquement pendant une fenêtre de déploiement. En continu, passe par CloudWatch : le polling API coûte cher et se fait throttler dès que tu montes en nombre de groupes.
xDS remplace-t-il vraiment les APIs REST ?
Pour la distribution d'endpoints à grande échelle, oui. Pour modifier une règle de routage ponctuelle, non : un flux gRPC persistant est plus lourd à opérer qu'un PUT HTTP. Les deux coexistent, souvent dans le même système.
Le vrai marqueur de maturité d'une plateforme n'est pas le nombre de load balancers qu'elle fait tourner, mais le fait que personne n'ait besoin de se connecter en SSH pour en changer un réglage. Les sources officielles à garder sous la main : la documentation Data Plane API, la référence ELBv2 et le protocole xDS.