ansible lookup : guide pratique pour exploiter variables, fichiers et secrets sans casser vos playbooks

Avec ansible lookup, vous lisez une donnée depuis le contrôleur Ansible avant l’exécution d’une tâche. En pratique, il faut surtout retenir trois règles : choisir le bon plugin, préférer query() dans les boucles, et protéger tout ce qui touche aux secrets. Bien utilisé, lookup simplifie l’automatisation ; mal utilisé, il rend vos playbooks fragiles et difficiles à relire.

Pourquoi ansible lookup devient critique dans un environnement infra

Sur le papier, lookup paraît anodin. Pourtant, dans une équipe infrastructure, c’est souvent le point de contact entre vos playbooks et le reste du système d’information : variables d’environnement injectées par un runner CI, fragments de configuration stockés dans un dépôt Git, mots de passe protégés dans Vault, enregistrements DNS, fichiers CSV d’inventaire, ou encore données générées par un pipeline. Dès que l’automatisation grandit, ces dépendances deviennent critiques.

Le problème, c’est que beaucoup d’équipes traitent encore lookup comme un simple raccourci syntaxique. Résultat : des tâches qui ne sont pas idempotentes, des loops qui plantent parce qu’une chaîne n’est pas une liste, des secrets qui remontent dans les logs, et des playbooks impossibles à diagnostiquer quand un pipeline de déploiement tombe en erreur à 2 h du matin.

Dans un contexte PME, SaaS ou infogérance, l’objectif n’est pas de connaître toute la documentation Ansible par cœur. Il faut surtout disposer d’un cadre fiable pour savoir quand lookup est pertinent, comment structurer son usage, et à quel moment il faut lui préférer un module standard ou une variable explicitement déclarée.

Diagnostic : comment reconnaître un mauvais usage de lookup

Plusieurs symptômes reviennent régulièrement. Le premier est la boucle qui échoue avec un message flou, parce que le résultat attendu est une liste mais que le plugin renvoie un scalaire. Le deuxième est l’effet tunnel dans les templates Jinja : une variable alimentée par lookup appelle une autre variable, qui dépend elle-même d’un lookup différent, et toute la chaîne devient opaque. Le troisième est le souci de sécurité : un secret récupéré via un plugin est affiché par un debug ou injecté dans une tâche bavarde, ce qui pollue les logs CI/CD.

Un autre signal faible mérite votre attention : quand un playbook fonctionne sur votre poste mais casse dans GitLab CI, GitHub Actions ou AWX. Ce décalage provient très souvent d’un lookup qui dépend d’un chemin local, d’une variable d’environnement absente, ou d’un backend secret non disponible dans le runner.

Enfin, lorsque plusieurs membres de l’équipe écrivent chacun leur propre manière de récupérer une donnée externe, le parc de playbooks perd rapidement en cohérence. Certains utilisent lookup('env', 'VAR'), d’autres une variable de groupe, d’autres encore un template Jinja imbriqué. Sans standard, le troubleshooting devient coûteux.

Causes racines : pourquoi ces erreurs arrivent

La première cause est conceptuelle : Ansible mélange facilement variables, templates, plugins et modules dans le même rendu final. Pour un ingénieur déjà concentré sur le service à déployer, il est tentant de tout faire directement dans la ligne YAML. La deuxième cause est historique : beaucoup d’exemples en ligne utilisent lookup() partout, alors que query() est souvent plus adapté pour préserver un type de retour cohérent.

La troisième cause est organisationnelle. Lorsqu’une équipe n’a pas de conventions claires pour la gestion des secrets, la structure des variables, les chemins de fichiers ou les rôles responsables des données externes, les lookups se multiplient de façon opportuniste. Chaque ajout semble pratique à court terme, mais le coût de maintenance explose ensuite.

Il faut aussi intégrer la dimension performance. Un playbook qui appelle plusieurs plugins de lookup dans des boucles, des templates ou des rôles très sollicités peut ralentir les exécutions, surtout si le backend contacté est distant. Ce n’est pas toujours dramatique, mais c’est une dette technique invisible jusqu’au jour où les pipelines s’allongent fortement.

Solutions : patrons fiables pour utiliser ansible lookup

La bonne approche consiste à réserver lookup aux besoins réellement externes au playbook, puis à centraliser la logique. Au lieu de disperser des appels Jinja partout, créez des variables intermédiaires explicites, documentées, et testables. Cela améliore la lisibilité et simplifie le diagnostic.

Premier cas concret : récupérer une variable d’environnement injectée par un runner CI. C’est simple, efficace, mais cela mérite un garde-fou si la variable est absente.

vars:
  app_env: "{{ lookup('env', 'APP_ENV') | default('prod', true) }}"

tasks:
  - name: Afficher l'environnement retenu
    debug:
      msg: "Déploiement vers {{ app_env }}"

Deuxième cas : charger le contenu d’un fichier local pour alimenter un template ou une configuration. Ici, l’intérêt est d’éviter de dupliquer des blocs texte dans le YAML.

vars:
  banner_text: "{{ lookup('file', 'files/banner.txt') }}"

tasks:
  - name: Déployer la bannière SSH
    copy:
      dest: /etc/issue.net
      content: "{{ banner_text }}"
      owner: root
      group: root
      mode: '0644'

Troisième cas : travailler avec une liste. Pour cela, mieux vaut préférer query() afin de récupérer directement un type compatible avec les boucles.

vars:
  admin_users: "{{ query('fileglob', 'files/admin-users/*.pub') }}"

tasks:
  - name: Installer les clés publiques d'administration
    authorized_key:
      user: admin
      state: present
      key: "{{ lookup('file', item) }}"
    loop: "{{ admin_users }}"

Quatrième cas : les secrets. Si votre équipe travaille déjà avec Ansible Vault, HashiCorp Vault ou un autre backend, gardez la récupération du secret au plus près du besoin, mais évitez de l’afficher, de le journaliser ou de l’utiliser dans un nom de ressource.

tasks:
  - name: Déployer la configuration applicative
    template:
      src: app.env.j2
      dest: /opt/app/.env
      owner: root
      group: root
      mode: '0600'
    vars:
      db_password: "{{ lookup('community.hashi_vault.hashi_vault', 'secret=kv/data/app:password token=' + vault_token + ' url=' + vault_addr) }}"
    no_log: true

Sur des projets plus structurés, je recommande aussi de factoriser les lookups dans les defaults ou dans une couche de variables clairement nommée. Cela évite les surprises quand un rôle évolue, et cela permet de tester plus facilement les comportements attendus avec Molecule ou une pipeline d’intégration.

Si vous industrialisez déjà vos déploiements avec Ansible, je vous conseille aussi de relier cette discipline à une structure de rôles propre. Deux ressources utiles sur linux-man.fr complètent bien ce sujet : industrialiser une infra Linux avec Ansible et gérer les variables de déploiement Ansible dans Bitbucket.

Prévention : standards d’équipe à mettre en place

Pour éviter que lookup ne devienne une dette technique, définissez quelques règles simples. D’abord, documentez les plugins autorisés et leur usage attendu : env pour les variables d’environnement, file pour les contenus locaux, community.hashi_vault.hashi_vault pour les secrets, et ainsi de suite. Ensuite, imposez une convention de nommage pour les variables intermédiaires. Enfin, ajoutez une revue ciblée dans vos pull requests : “ce lookup doit-il vraiment vivre ici ?”

Je recommande aussi de limiter les lookups dans les chemins les plus critiques, notamment quand une donnée peut être chargée une fois puis réutilisée. Sur les pipelines sensibles, quelques secondes de plus par rôle finissent par compter. De même, chaque secret doit être accompagné d’une stratégie de masquage cohérente : no_log: true, variables d’environnement éphémères et rotation documentée.

Si votre activité dépend de la stabilité de vos playbooks, il est pertinent de traiter ce sujet comme un standard d’exploitation, pas comme une simple question de syntaxe. C’est souvent ce niveau de rigueur qui sépare une automatisation “qui marche chez moi” d’une plateforme fiable pour une équipe complète.

Checklist avant de merger un playbook qui utilise lookup

Erreurs courantes à corriger avant la mise en production

FAQ sur ansible lookup

Conclusion

ansible lookup n’est pas qu’un détail de syntaxe. C’est un mécanisme central pour brancher vos playbooks sur leur environnement réel. Si vous l’utilisez avec des conventions simples, des variables explicites et une vraie discipline sur les secrets, vous gagnez en robustesse, en lisibilité et en vitesse de diagnostic. À l’inverse, un usage improvisé crée des playbooks fragiles et difficiles à maintenir.

Si vous voulez, je peux aussi transformer ce brouillon en version orientée audit interne ou en guide pas-à-pas pour industrialiser vos rôles Ansible à l’échelle d’une PME.