Résolution des conflits de précédence de variables dans les configurations Ansible

Les problèmes de précédence de variables se manifestent généralement par une question simple : « Pourquoi Ansible a-t-il utilisé cette valeur ? » Un port est 8080 alors que vous attendiez 80. Un rôle déploie la version 1.6 même si le playbook indique 1.5. Un job CI passe -e environment=prod, et soudainement, la moitié de votre structure d'inventaire soigneusement construite cesse d'avoir de l'importance.

La solution consiste rarement à mémoriser chaque ligne de la table de précédence d'Ansible. La solution consiste à réduire les sources possibles, à inspecter la valeur sur l'hôte concerné et à déplacer la variable vers la couche appropriée. Ce guide se concentre sur ce flux de travail.

Comprendre la précédence des variables Ansible

Ansible évalue les variables dans un ordre spécifique, appelé ordre de précédence des variables. La valeur qui apparaît plus tard dans cette liste remplace toute valeur définie précédemment pour la même variable. Il est essentiel de se souvenir de cet ordre lors du dépannage.

Voici une manière simplifiée de considérer les sources courantes, de la plus facile à remplacer à la plus difficile à remplacer :

Valeurs par défaut des rôles : Variables définies dans le fichier defaults/main.yml d'un rôle. Elles ont la précédence la plus basse et sont destinées à des valeurs par défaut qui peuvent être facilement remplacées.
Variables d'inventaire (tous ou groupe) : Variables définies dans les fichiers d'inventaire à l'aide du mot-clé vars: pour des groupes spécifiques ou tous les hôtes.
Variables d'inventaire (hôte) : Variables définies directement pour un hôte spécifique dans le fichier d'inventaire.
Variables du playbook : Variables définies à l'aide du mot-clé vars: directement dans un playbook.
Variables de rôle : Variables définies dans le fichier vars/main.yml d'un rôle. Elles ont une précédence plus élevée que les valeurs par défaut.
Inclure des variables et des fichiers de variables : Variables chargées explicitement par un play ou une tâche.
Variables au niveau des tâches, variables de bloc, résultats enregistrés et faits : Ceux-ci peuvent affecter les tâches ultérieures et peuvent être facilement négligés car ils vivent à l'intérieur du flux d'exécution.
Variables Set Fact : Variables définies à l'aide du module set_fact ont une précédence élevée pour l'exécution en cours.
Variables supplémentaires : Les variables passées en ligne de commande à l'aide de -e ou --extra-vars sont intentionnellement très fortes et remplacent presque tout le reste.

Ceci est un modèle de travail, pas la table complète. La documentation officielle d'Ansible contient la liste exhaustive, y compris les paramètres de rôle, les paramètres d'inclusion, le comportement des plugins d'inventaire et d'autres cas particuliers. Pour le débogage en production, comparez votre cas avec les règles officielles de précédence des variables.

Scénarios courants de conflit de variables et solutions

Examinons quelques scénarios courants où des conflits de précédence de variables peuvent se produire et comment les diagnostiquer et les résoudre.

Scénario 1 : Variables de groupe vs. Variables d'hôte

Souvent, vous pouvez définir un paramètre général pour un groupe de serveurs (par exemple, app_servers) puis un paramètre spécifique pour un serveur de ce groupe (par exemple, webserver01).

Exemple d'inventaire (inventory.ini) :

[app_servers]
webserver01.example.com
webserver02.example.com

[databases]
dbserver01.example.com

[app_servers:vars]
http_port = 8080

[webserver01.example.com:vars]
http_port = 80

Résultat attendu : Pour webserver01.example.com, http_port devrait être 80. Pour webserver02.example.com, qui est dans app_servers mais non défini spécifiquement, http_port devrait être 8080.

Problème : Si http_port ne se comporte pas comme prévu, le problème probable est une méprise sur la définition qu'Ansible utilise.

Étapes de diagnostic :

Utiliser le module debug : Ajoutez une tâche debug dans votre playbook pour afficher explicitement la valeur de la variable.
```
- name: Afficher http_port
  debug:
    msg: "Le http_port pour cet hôte est {{ http_port }}"
```
Utiliser ansible-inventory --host <hostname> : Cet utilitaire en ligne de commande affiche toutes les variables associées à un hôte spécifique, y compris leur précédence.
```
ansible-inventory --host webserver01.example.com --list --yaml
```
Recherchez la variable http_port et notez où elle est définie. La sortie indique souvent la source de la variable.

Solution : Dans ce cas, les variables d'hôte ([webserver01.example.com:vars]) ont une précédence plus élevée que les variables de groupe ([app_servers:vars]), donc http_port = 80 remplacera correctement http_port = 8080 pour webserver01.example.com.

Scénario 2 : Variables du playbook vs. Variables de rôle

Vous pouvez définir un paramètre dans la section vars de votre playbook et également dans un rôle que le playbook inclut.

Exemple de playbook (deploy_app.yml) :

--- 
- name: Déployer l'application web
  hosts: webservers
  vars:
    app_version: "1.5"
    db_host: "prod.db.local"
  roles:
    - common
    - webapp

Exemple de rôle (webapp/vars/main.yml) :

app_version: "1.6"
db_host: "shared.db.local"

Résultat attendu : Lorsque ce playbook s'exécute, que seront app_version et db_host ?

Étapes de diagnostic :

Module debug : Comme précédemment, utilisez le module debug pour inspecter les valeurs.

- name: Afficher app_version et db_host
  debug:
    msg: "Version de l'application : {{ app_version }}, Hôte de la base de données : {{ db_host }}"

Examiner la structure du rôle : Assurez-vous que vars/main.yml fait bien partie du rôle inclus et qu'il n'y a pas d'autres fichiers vars/main.yml dans les dépendances du rôle qui pourraient prendre le dessus.

Solution : Selon les règles de précédence, les variables de rôle (webapp/vars/main.yml) ont une précédence plus élevée que les variables du playbook (vars: dans deploy_app.yml). Par conséquent :

app_version sera 1.6.
db_host sera shared.db.local.

Si vous aviez l'intention que les variables du playbook prennent le dessus, vous devriez déplacer ces définitions à un niveau de précédence plus élevé, comme extra_vars ou utiliser vars_files avec une précédence plus élevée.

Scénario 3 : Remplacement avec `extra-vars`

Les variables de ligne de commande (extra-vars) ont une précédence très élevée et peuvent remplacer presque tout le reste.

Exemple d'inventaire (inventory.ini) :

[webservers]
webserver01.example.com

[webservers:vars]
http_port = 8080

Exemple de playbook (configure_web.yml) :

--- 
- name: Configurer le serveur web
  hosts: webservers
  tasks:
    - name: Afficher http_port
      debug:
        msg: "Le http_port est {{ http_port }}"

Exécution du playbook :

Sans extra-vars :
```
ansible-playbook -i inventory.ini configure_web.yml
```
Sortie : Le http_port sera 8080 (provenant des variables de groupe).

Avec extra-vars :

ansible-playbook -i inventory.ini configure_web.yml -e "http_port=80"

Sortie : Le http_port sera 80.

Étapes de diagnostic : Vérifiez toujours si extra-vars sont utilisées, en particulier dans les exécutions complexes ou orchestrées, car elles sont une cause fréquente de valeurs de variables inattendues.

Solution : Soyez attentif aux extra-vars. Si vous devez remplacer des valeurs par programmation ou pour des exécutions spécifiques, extra-vars est la solution. Si vous ne voulez pas qu'elles remplacent, assurez-vous qu'elles ne sont pas passées ou ajustez votre playbook/inventaire pour prioriser d'autres sources de variables si nécessaire (bien que cela soit généralement déconseillé car cela affaiblit la prévisibilité).

Techniques avancées de dépannage

Lorsque vous traitez des problèmes complexes de précédence de variables, les techniques suivantes peuvent être inestimables :

ansible-inventory --host : Utilisez-le pour les variables dérivées de l'inventaire avant l'exécution du play.
```
ansible-inventory -i inventory.ini --host webserver01.example.com --yaml
```
Cela n'affichera pas les valeurs créées plus tard par les tâches, mais c'est le moyen le plus rapide de vérifier le comportement de l'inventaire, de group_vars et de host_vars.

Tâches debug ciblées : Utilisez debug dans le play lorsqu'une valeur peut provenir d'un rôle, d'une inclusion, d'un résultat enregistré ou de set_fact.

- name: Afficher les paramètres de l'application résolus
  ansible.builtin.debug:
    msg:
      app_version: "{{ app_version | default('undefined') }}"
      db_host: "{{ db_host | default('undefined') }}"

--skip-tags et --limit : Lors du débogage, essayez d'isoler le problème. Exécutez le playbook avec --limit pour cibler uniquement l'hôte problématique. Utilisez --skip-tags pour désactiver les tâches ou les rôles qui pourraient définir involontairement des variables.
Ordre des vars_files : Si vous utilisez vars_files dans votre playbook, leur ordre compte. Ansible les charge dans l'ordre spécifié, et les fichiers ultérieurs peuvent remplacer les variables définies dans les fichiers précédents.
```
- name: Déployer l'application
  hosts: webservers
  vars_files:
    - vars/common_settings.yml
    - vars/environment_specific.yml # Cela remplacera common_settings.yml si les variables se chevauchent
```

Meilleures pratiques pour la gestion des variables

Pour minimiser les conflits de précédence de variables :

Soyez explicite : Évitez de définir la même variable à trop d'endroits. Si une variable est vraiment globale, envisagez group_vars/all.yml ou group_vars/all/.
Utilisez des noms descriptifs : Utilisez des noms clairs et uniques pour vos variables afin de réduire le risque de collisions de noms accidentelles.
Documentez vos variables : Gardez une trace de l'endroit où les variables importantes sont définies et de leur portée prévue.
Tirez parti des valeurs par défaut des rôles : Utilisez les valeurs par défaut des rôles pour les paramètres non critiques destinés à être remplacés. Cela rend les rôles plus flexibles.
Comprenez l'ordre : Gardez une note mentale (ou physique !) de l'ordre de précédence. Lorsqu'une variable n'est pas ce que vous attendez, consultez l'ordre.
Testez de manière incrémentielle : Lorsque vous introduisez de nouvelles définitions de variables ou modifiez des définitions existantes, testez d'abord vos playbooks à petite échelle.

Une routine de débogage qui fonctionne réellement

Lorsqu'une variable est erronée, ne commencez pas par la déplacer. Prouvez d'abord d'où vient la valeur actuelle.

Je commence généralement par la plus petite exécution possible :

ansible-playbook -i inventory.ini deploy_app.yml --limit webserver01.example.com --check -vv

--limit supprime le bruit des autres hôtes. --check est utile lorsque le play le supporte, bien que tous les modules ne puissent pas prédire pleinement les changements. -vv donne plus de contexte sans transformer la sortie en un mur d'informations internes. Si la valeur est toujours déroutante, ajoutez une tâche de débogage temporaire immédiatement avant la tâche qui se comporte incorrectement.

Placez le débogage près de la tâche défaillante. Une valeur peut changer pendant un play, surtout si le rôle utilise include_vars, set_fact ou register. Une tâche de débogage en haut du play peut afficher la bonne valeur, tandis qu'une tâche de débogage à l'intérieur du rôle affiche la valeur après qu'elle a été écrasée.

Par exemple :

- name: Afficher app_version avant le rendu du template
  ansible.builtin.debug:
    var: app_version

- name: Rendre la configuration de l'application
  ansible.builtin.template:
    src: app.conf.j2
    dest: /etc/app/app.conf

Si la sortie de débogage est correcte mais que la sortie du template est erronée, le problème peut être à l'intérieur du template, pas la précédence. Peut-être que le template référence app.version au lieu de app_version, ou qu'un filtre par défaut masque une valeur non définie :

version={{ app_version | default('latest') }}

Cette ligne peut faire ressembler une variable manquante à une valeur délibérée. Les valeurs par défaut sont utiles, mais elles peuvent cacher des erreurs lorsqu'elles sont utilisées pour des paramètres obligatoires.

Ensuite, inspectez l'inventaire :

ansible-inventory -i inventory.ini --host webserver01.example.com --yaml
ansible-inventory -i inventory.ini --graph

La vue de l'hôte montre les variables d'inventaire fusionnées qu'Ansible voit avant l'exécution des tâches. La vue graphique montre l'appartenance au groupe. L'appartenance au groupe est importante car un hôte peut hériter de variables de plusieurs groupes. Si deux groupes frères définissent la même variable, le résultat dépend du chargement de l'inventaire et des règles de priorité de groupe. Dans cette situation, compter sur le hasard est un problème de maintenance.

Si vous avez vraiment besoin qu'un groupe l'emporte sur un autre, utilisez ansible_group_priority dans la source d'inventaire qui définit les groupes. Mieux encore, évitez la collision et choisissez un nom de variable qui reflète l'intention :

nginx_listen_port: 80
app_healthcheck_port: 8080

C'est plus clair qu'un seul http_port générique réutilisé dans des rôles non liés.

Soyez méfiant envers extra-vars. Dans les systèmes CI/CD, les valeurs sont souvent injectées par des modèles de pipeline ou des scripts d'encapsulation. Recherchez dans la définition du job -e, --extra-vars et les fichiers passés avec la syntaxe @ :

ansible-playbook site.yml -e @release-vars.yml -e app_version=1.6

Les variables supplémentaires sont conçues pour être puissantes. Si un pipeline passe app_version=1.6, n'attendez pas que l'inventaire ou les valeurs par défaut du rôle les remplacent. La correction plus propre consiste à arrêter de passer la valeur lorsqu'elle ne doit pas être forcée, ou à la renommer en quelque chose d'intentionnellement spécifique à l'exécution, comme release_app_version.

Les rôles méritent une attention particulière. defaults/main.yml est destiné aux valeurs que l'appelant est censé remplacer. vars/main.yml est destiné aux valeurs que le rôle possède principalement. Si vous mettez une configuration ordinaire dans vars/main.yml, les utilisateurs du rôle auront du mal à la modifier à partir de l'inventaire ou des variables du play. Dans de nombreux rôles réels, déplacer une valeur de vars/main.yml vers defaults/main.yml est la bonne correction car cela rétablit le contrat du rôle.

Surveillez également les boucles include_vars :

- name: Charger les paramètres d'environnement
  ansible.builtin.include_vars:
    file: "vars/{{ env }}.yml"

C'est un modèle utile, mais cela signifie que la valeur dépend de env, du contenu du fichier inclus et du point du play où l'inclusion s'exécute. Si env provient de variables supplémentaires, l'inclusion peut charger silencieusement un fichier différent de celui attendu.

L'habitude à long terme la plus fiable est de donner à chaque variable un foyer :

Les valeurs par défaut des rôles pour le comportement paramétrable du rôle.
L'inventaire et group_vars pour les différences d'environnement et d'hôte.
Les variables du play pour les valeurs locales à un seul play.
Les variables enregistrées pour la sortie de commande qui appartient à l'exécution en cours.
Les variables supplémentaires pour les remplacements ponctuels délibérés, en particulier les entrées de version.

Lorsqu'une variable ne correspond à aucun de ces foyers, faites une pause avant de l'ajouter. La plupart des bugs de précédence commencent comme une commodité : « Je vais juste la définir ici pour l'instant. » Trois mois plus tard, personne ne se souvient quel « ici » l'emporte.