Un fichier map HAProxy stocke des paires clé-valeur et constitue le point de départ pour des opérations telles que la limitation de débit dynamique et les déploiements blue-green.
Dictionnaires. Correspondances. Les hachages. Tableaux associatifs. Imaginez-vous la vie sans ces extraordinaires structures de données clé-valeur ? Le monde fou et dystopique que cela serait ? Ce sont des outils fiables toujours à portée de main.
Ne soyez pas surpris qu’elles soient comptées parmi les vastes fonctionnalités du répartiteur de charge HAProxy. Elles s’appellent des fichiers map et sont intégrées et prêtes à l’emploi. Elles vous surprendront avec les tâches étonnantes que vous pourriez accomplir.
Vous voulez implémenter des déploiements blue-green ? Ou définir des limites de débit par chemin d’accès URL ? Ou changer dynamiquement les serveurs backend pour un domaine ? Tout est possible avec les fichiers map !
Dans cet article, vous verrez comment créer un fichier map, le stocker, le référencer dans votre configuration HAProxy et le mettre à jour en temps réel, ainsi que des scénarios utiles pour mettre à profit vos connaissances.
Pour commencer
Avant d’examiner ce que vous pouvez accomplir avec un fichier map, il faut d’abord comprendre ce que c’est.
Le fichier map
Tout commence par la création d’un fichier map. Lancez un éditeur de texte et créez un fichier nommé hosts.map. Puis ajoutez-y les lignes suivantes :
Quelques éléments à noter concernant la structure de ce fichier :
- C’est du texte brut
- Chaque ligne commence avec une clé (par exemple : static.example.com)
- Une valeur vient après une clé, séparée par au moins un espace (ex : be_static)
- Les lignes vides et les espaces supplémentaires entre les mots sont ignorés.
- Les commentaires doivent commencer par un hashtag (#) et figurer sur leur propre ligne.
Un fichier map stocke des paires clé-valeur. HAProxy s’en sert comme une table de consultation (« lookup »), par exemple pour savoir vers quel backend diriger un client en fonction de la valeur de l’en-tête Host. L’avantage de stocker cette association dans un fichier plutôt que dans la configuration HAProxy elle-même est de pouvoir modifier ces valeurs de manière dynamique.
Ensuite, mettez ce fichier sur un serveur où il y a une instance de HAProxy sans importance et placez-le dans un répertoire quelconque. Dans ces exemples, puisque nous utilisons HAProxy Enterprise, nous le stockons sous /etc/hapee-1.8/maps. Les fichiers map sont chargés par HAProxy au démarrage, bien qu’ils puissent être modifiés pendant l’exécution sans être rechargés.
Convertisseurs de map
Pour vous donner une idée, voyons comment utiliser un fichier map pour trouver le bon pool de serveurs backend où envoyer les utilisateurs. Vous utiliserez le fichier hosts.map créé précédemment pour rechercher le backend approprié en fonction d’un certain nom de domaine.
Commencez par modifier votre fichier haproxy.cfg. Vous allez ajouter un convertisseur map qui lit le fichier map et renvoie un nom de backend.
Un convertisseur est une directive placée dans votre configuration HAProxy qui prend une entrée et renvoie une sortie associée. Il existe plusieurs types de convertisseurs. Par exemple, vous utilisez le convertisseur lower pour changer une chaîne donnée en minuscules ou url_dec pour décoder l’URL.
Dans l’exemple suivant, l’entrée est une chaîne littérale example.com et le convertisseur map recherche cette clé dans le fichier map hosts.map.
La valeur de la première ligne de hosts.map dont la clé est example.com, sera renvoyée. Remarquez que l’entrée, str(example.com), débute l’expression et est séparée du convertisseur par une virgule.
Lorsque cette expression est évaluée au moment de l’exécution, elle est convertie en la ligne use_backend be_static, qui dirige les requêtes vers le pool de serveurs be_static. Plutôt que de transmettre une chaîne codée en dur comme example.com, vous envoyez la valeur d’un en-tête HTTP ou un paramètre d’URL. L’exemple suivant utilise la valeur de l’en-tête Host comme entrée.
Le convertisseur de map prend jusqu’à deux arguments. Le premier est le chemin d’accès à votre fichier map. Le deuxième, facultatif, déclare une valeur par défaut utilisée si aucune clé correspondante n’est trouvée. Donc, s’il n’y a pas de correspondance, be_static sera utilisé. Si l’entrée correspond à plusieurs éléments dans le fichier map, HAProxy retournera le premier.
Le convertisseur map recherche une correspondance exacte dans le fichier, mais il existe quelques variantes qui offrent la possibilité d’une correspondance partielle. Les plus couramment utilisées sont résumées ici :
map_beg |
Recherche les entrées dans le fichier map qui correspondent au début de l’entrée (par exemple, une entrée de « abcd » correspondrait à « a » dans le fichier). |
map_end |
Recherche les entrées dans le fichier map correspondant à la fin de l’entrée (par exemple, une entrée de « abcd » correspondrait à « d » dans le fichier).
Contrairement aux autres modes de correspondance, ce mode n’effectue pas de recherche dans les arborescences ebtree et vérifie chaque ligne. |
map_sub |
Recherche les entrées dans le fichier map qui constituent une sous-chaîne de l’échantillon (par exemple, « abcd » correspondrait à « ab » ou « c » dans le fichier).
Contrairement aux autres modes de correspondance, ce mode n’effectue pas de recherche dans les arborescences ebtree et vérifie chaque ligne. |
map_ip |
Cette fonction prend l’entrée comme une adresse IP et la recherche dans la table. Si la table contient des masques (tels que 192.168.0.0/16), alors n’importe quelle adresse IP de la plage correspondra à cette adresse. |
map_reg |
Ce mode lit les échantillons dans le map comme des expressions régulières et correspondra si l’expression régulière correspond. Contrairement aux autres modes de correspondance, ce mode n’effectue pas de recherches dans ebtree et vérifie chaque ligne. |
map_str |
Un alias pour map. Cette fonction prend une chaîne de caractères en entrée, effectue une correspondance sur toute la clé et renvoie une valeur sous forme de chaîne de caractères. |
Modifier les valeurs
Il y a quatre façons de modifier les fichier map dans HAProxy
La valeur ajoutée des fichiers map est leur capacité à être modifiés dynamiquement. Cela vous permet, par exemple, de modifier le flux de trafic d’un backend à un autre, par exemple pour la maintenance.
Il existe quatre façons de modifier la valeur renvoyée par un fichier map. Premièrement, vous modifiez les valeurs en éditant directement le fichier. C’est simple, mais nécessite un rechargement de HAProxy. C’est un bon choix si vous utilisez un gestionnaire de configuration comme Puppet ou Ansible.
La deuxième méthode est fournie avec HAProxy Enterprise via le module lb-update, très appréciable si vous utilisez un cluster de répartiteurs de charge. Vous pouvez mettre à jour les tables dans plusieurs instances de HAProxy à la fois en surveillant un fichier map hébergé à une URL à un intervalle défini.
Une troisième façon de modifier le contenu du fichier est d’utiliser l’API d’exécution. L’API fournit toutes les opérations CRUD nécessaires pour créer, mettre à jour et supprimer des lignes du map en mémoire, sans recharger HAProxy. Nous vous montrerons également une technique pour sauvegarder vos modifications sur le disque.
Une quatrième méthode utilise la directive http-request set-map dans votre fichier de configuration HAProxy afin de mettre à jour les entrées du fichier map en fonction des paramètres URL dans la requête. Elle peut être transformée en une interface HTTP pratique pour apporter des modifications au fichier map à partir d’un client distant.
Les prochaines sections proposent des conseils sur la manière d’utiliser ces techniques.
Modifier directement le fichier
Une façon simple de modifier les valeurs obtenues de votre fichier map est de modifier le fichier lui-même. Apportez toutes les modifications nécessaires : ajouts et suppressions de lignes, modifications des valeurs existantes. Cependant, HAProxy ne lit le fichier qu’au démarrage et le charge ensuite en mémoire. Mettre à jour le fichier signifie donc recharger HAProxy.
Depuis la version HAProxy Enterprise 1.8r1 et HAProxy 1.8, vous pouvez recharger HAProxy sans abandonner les connexions actives (hitless reloads). Lisez notre article de blog Recharges sans interruptions avec HAProxy pour plus de détails sur cette fonctionnalité.
Cette approche fonctionne avec des gestionnaires de configuration comme Puppet qui permettent de distribuer les changements à vos serveurs à un intervalle défini. N’oubliez pas de recharger HAProxy pour les prendre en compte.
Édition avec le module lb-update
Bien que les gestionnaires de configuration vous permettent de mettre à jour les serveurs de votre cluster, ils nécessitent une administration. Une alternative est d’utiliser le module lb-update pour synchroniser chaque réplique de HAProxy au sein de votre cluster. Le module lb-update demande à HAProxy de récupérer le contenu du fichier map depuis une URL à un intervalle défini et vérifie automatiquement les mises à jour à une fréquence configurée. Ceci est particulièrement utile lorsqu’il y a beaucoup de processus et/ou de serveurs dans un cluster qui ont besoin des fichiers mis à jour.
Ci-dessous se trouve un exemple de la section dynamic-update qui gère la mise à jour du fichier hosts.map à partir d’une URL. Ajoutez une directive update pour chaque fichier map à surveiller.
Consultez la documentation HAProxy Enterprise pour des instructions d’utilisation ou contactez-nous pour en savoir plus.
Édition avec l’API d’exécution
Dans notre précédent article de blog, intitulé Configuration dynamique avec l’API d’execution d’HAProxy, vous constatez plusieurs méthodes d’API permettant de mettre à jour un fichier map existant.
Le tableau ci-dessous les résume.
| Méthode API | Description |
|---|---|
show map |
Liste les fichiers map disponibles ou affiche le contenu d’un fichier map. |
get map |
Signale les clés et les valeurs correspondant à une entrée donnée. |
set map |
Modifie une entrée du fichier map. |
add map |
Ajoute une entrée dans le fichier map. |
del map |
Supprime une entrée du fichier map. |
clear map |
Supprime toutes les entrées d’un fichier map. |
Sans aucun paramètre, show map liste les fichiers map chargés en mémoire. Avec le chemin d’accès à un fichier particulier, il affiche son contenu. L’exemple suivant l’utilise pour afficher les paires clé-valeur contenues dans hosts.map.
La première colonne est l’emplacement de l’entrée et souvent ignorée. La deuxième est la clé à mapper, et la troisième la valeur. C’est facile d’ajouter et de supprimer des entrées via l’API d’exécution. Pour supprimer une entrée du fichier map, utilisez del map. Notez que cette opération la supprime seulement de la mémoire et non du fichier réel.
Vous pouvez également supprimer toutes les entrées avec clear map :
Ajouter une nouvelle clé et une nouvelle valeur avec add map :
Modifier une entrée existante avec set map :
Avec show map, nous pouvons obtenir le contenu du fichier, utiliser awk pour le filtrer afin d’avoir que les deuxième et troisième colonnes, puis sauvegarder la représentation en mémoire sur le disque :
Les actions peuvent être enchaînées à l’aide de points-virgules pour effectuer facilement des modifications de script et sauvegarder le résultat :
nbproc, you’ll want to configure one socket per process and then run a loop to update each process individually. vous devrez configurer une socket par processus, puis exécuter une boucle pour mettre à jour chaque processus individuellement. C’est facile avec le multithreading.Modification avec http-request set-map
Et si vous préférez faire une requête HTTP avec un certain paramètre d’URL pour mettre à jour votre fichier map plutôt que de le modifier à la main ou utiliser l’API d’exécution, optez pour http-request set-map.
C’est possible d’utiliser des extractions, des convertisseurs et des ACLs pour décider quand et comment modifier un fichier map pendant l’exécution. En plus de set-map, del-map supprime les entrées du map de la même manière. Comme pour l’API d’exécution, ces modifications ne s’appliquent qu’au processus auquel la requête aboutit.
Pour un fichier map à mettre à jour, passez son chemin à set-map et faites-le suivre d’une clé et d’une valeur, séparées par des espaces. La clé et la valeur supportent la notation log-format que vous pouvez donc spécifier en tant que chaînes simples ou avec des extractions et des convertisseurs. Par exemple, pour ajouter une nouvelle entrée au fichier hosts.map, mais uniquement si l’adresse source se situe dans la plage 192.168.122.0/24, vous utilisez cette configuration :
Vous pourrez effectuer des requêtes web telles que http://192.168.122.64/map/add?domain=example.com&backend=be_static pour une mise à jour rapide et facile de vos fichiers map. L’entrée est mise à jour si elle existe déjà . Notez que vous pouvez utiliser http-request deny deny_status 200 pour empêcher la requête d’aller vers vos serveurs backend.
La commande http-request del-map est suivie de la clé à supprimer du fichier map.
Avec show map vu précédemment, vous pouvez programmer une tâche cron pour sauvegarder vos fichiers map à des intervalles définis. Toutefois, pour répliquer ces modifications sur plusieurs instances de HAProxy, optez pour l’une des autres approches.
Mise en pratique
Nous avons vu l’utilisation de l’en-tête Host pour rechercher une clé dans un fichier map et choisir un backend. Voyons d’autres façons d’utiliser les fichiers map.
Un déploiement blue-green
Pour mettre en œuvre un déploiement blue-green afin de déployer une nouvelle version de votre application Web sur vos serveurs de test, puis de les échanger avec des serveurs de production, créez un fichier appelé bluegreen.map et ajoutez-y une seule entrée :
Dans ce scénario, le backend be_blue contient votre ensemble de serveurs de production actuellement actifs. Voici votre fichier de configuration HAProxy :
Après avoir déployé et testé une nouvelle version de votre application sur les serveurs be_green, vous utilisez l’API d’exécution pour échanger les serveurs be_blue actifs avec les serveurs be_green pour les rendre actifs en production.
Votre trafic est désormais dirigé de vos serveurs be_blue vers vos serveurs be_green. Contrairement à un déploiement continu, cette méthode garantit le transfert de tous vos utilisateurs en même temps vers la nouvelle version de votre application.
Limitation du débit par chemin URL
Dans cet exemple, vous spécifiez des limites de débit pour votre site web. Le fichier map vous permet de définir différentes limites pour différentes URL. Par exemple, celles qui commencent par /api/routeA peuvent accepter un taux de requêtes plus élevé que celles qui commencent par /api/routeB.
Ajoutez un fichier map appelé rates.map et ajoutez les entrées suivantes :
Prenons ce frontend où le taux de requêtes actuel pour chaque client est mesuré sur 10 secondes. Une URL comme /api/routeA/someFunction permettrait jusqu’à quatre requêtes par seconde (40 demandes / 10 secondes = 4 rps).
Ici, la définition de stick-table enregistre les taux de requête des clients sur dix secondes. Notez que nous suivons les clients avec la méthode d’extraction base32+src, qui combine l’en-tête Host, l’URL et l’IP source afin de suivre le taux de requêtes de chaque client basé par chemin. La valeur base32+src est stockée dans la table de persistance sous forme de données binaires.
Ensuite, deux variables sont définies avec http-request set-var. La première, req.rate_limit, est définie comme la limite de débit prédéfinie pour le chemin d’accès actuel à partir du fichier rates.map. La seconde, req.request_rate, est définie comme le taux de requêtes actuel du client.
L’ACL rate_abuse fait un calcul pour voir si le taux de requêtes du client est supérieur à la limite pour ce chemin. Pour ce faire, elle soustrait le taux de requêtes de la limite de requête et vérifie si la différence est inférieure à zéro. Si c’est le cas, la directive http-request deny répond par 429 Too Many Requests.
Conclusion
Maintenant que vous avez vu les possibilités, pensez à vous servir des fichiers map lorsque vous rencontrez un problème. À quoi utilisez-vous des fichiers map ? Laissez-nous un commentaire ici ou engagez une conversation avec nous sur Twitter !
Vous envisagez de mettre à jour des fichiers map sur un cluster de répartiteurs de charge HAProxy ? Obtenez une version d’essai gratuite de HAProxy Enterprise afin de profiter du module lb-update. En tant que client d’HAProxy Enterprise, vous bénéficiez d’une assistance technique experte. Faites vous aider à définir des fichiers map pour résoudre vos problèmes spécifiques.
