Facts et magic vars Ansible : ansible_facts, gather

Au début de chaque play, Ansible peut collecter automatiquement des centaines de variables sur chaque managed node : distribution, version, IP, mémoire, CPU, montages, packages, services, utilisateurs. Ce sont les facts, exposés sous la racine ansible_facts.* (et historiquement aussi en ansible_* directement). Cette page explique comment les utiliser, comment limiter leur collecte pour gagner en performance (gather_subset:), et comment lire les magic vars d'Ansible : inventory_hostname, groups, hostvars, play_hosts.

Maîtriser cette couche, c'est passer du playbook qui cible 1 hôte au playbook qui s'adapte automatiquement à la distribution, à la mémoire disponible, à la composition du groupe, sans aucune config manuelle.

# Facts essentiels (Ansible les collecte si gather_facts: true)
- ansible.builtin.debug:
    msg: |
      Distribution : {{ ansible_distribution }} {{ ansible_distribution_version }}
      Famille OS   : {{ ansible_os_family }}        # RedHat / Debian / Suse
      IP par défaut: {{ ansible_default_ipv4.address }}
      Mémoire (MB) : {{ ansible_memtotal_mb }}
      CPU          : {{ ansible_processor_vcpus }}

# Magic vars (toujours disponibles, ne dépendent pas de gather_facts)
- ansible.builtin.debug:
    msg: |
      Hôte courant : {{ inventory_hostname }}
      Groupes      : {{ group_names }}
      Tous les webs: {{ groups['webservers'] }}
      IP de db1    : {{ hostvars['db1.lab'].ansible_default_ipv4.address }}

# Performance : ne collecter qu'un sous-ensemble (gain typique 2-5 s/host)
- hosts: all
  gather_facts: true
  gather_subset:
    - "!all"        # désactive tout
    - network        # réactive seulement network
    - distribution   # + distribution

Sécurité & performance :

Préférer ansible_os_family (3 valeurs : RedHat / Debian / Suse) à ansible_distribution (qui change à chaque distrib : AlmaLinux / Rocky / CentOS).
ansible_facts (avec underscore) plutôt que ansible_*, la première forme est officielle 2026 ; la seconde est legacy mais toujours supportée.
gather_subset: réduit massivement le temps de gather sur un grand parc, 5 secondes/host × 200 hôtes = ~17 minutes économisées.
hostvars[<host>] permet de lire les facts d'un autre hôte (cf. exemple IP de db1 ci-dessus), pratique pour générer un template qui contient les IPs de tous les pairs.
Ne JAMAIS faire confiance aux facts pour des décisions de sécurité critiques sans validation supplémentaire, ils viennent du managed node qui pourrait être compromis.

Ce que vous allez apprendre

Activer / désactiver gather_facts: au niveau du play
Limiter la collecte avec gather_subset: pour gagner du temps sur grandes fleets
Lire les facts les plus utiles : ansible_distribution, ansible_default_ipv4, ansible_memtotal_mb, ansible_memory_mb
Utiliser les magic vars : inventory_hostname, groups, hostvars, play_hosts, ansible_play_batch
Accéder aux facts d'un autre hôte via hostvars['<host>'].ansible_*

Prérequis

Avoir lu Variables, déclaration et Types collections ;
Avoir un lab opérationnel (ansible all -m ping répond pong).

La phase `gather_facts`

Au démarrage de chaque play (par défaut), Ansible exécute le module setup sur chaque hôte cible. Ce module remonte des centaines de variables :

ansible web1.lab -m setup | head -40

Sortie (extrait) :

web1.lab | SUCCESS => {
    "ansible_facts": {
        "ansible_distribution": "AlmaLinux",
        "ansible_distribution_version": "10.1",
        "ansible_distribution_major_version": "10",
        "ansible_default_ipv4": {
            "address": "10.10.20.21",
            "interface": "eth0",
            "netmask": "255.255.255.0"
        },
        "ansible_memtotal_mb": 1740,
        "ansible_processor_cores": 1,
        ...
    }
}

Ces facts sont disponibles dans toutes les tâches qui suivent, directement par leur nom ({{ ansible_distribution }}) ou via ansible_facts.*.

Les facts les plus utiles

Fact	Type	Exemple
`ansible_distribution`	string	`AlmaLinux`, `Ubuntu`, `Debian`
`ansible_distribution_version`	string	`10.1`
`ansible_distribution_major_version`	string	`10`
`ansible_os_family`	string	`RedHat`, `Debian`
`ansible_default_ipv4.address`	string	`10.10.20.21`
`ansible_all_ipv4_addresses`	list	`["10.10.20.21"]`
`ansible_memtotal_mb`	int	`1740`
`ansible_processor_cores`	int	`1`
`ansible_processor_count`	int	`1`
`ansible_kernel`	string	`5.14.0-...el10.x86_64`
`ansible_hostname`	string	`web1` (court)
`ansible_fqdn`	string	`web1.lab` (FQDN)
`ansible_python_version`	string	`3.12.x`
`ansible_pkg_mgr`	string	`dnf`, `apt`

Désactiver les facts pour la performance

La phase gather_facts: true prend 2-5 secondes par hôte. Sur 100 hôtes, c'est 5 minutes perdues si vous n'utilisez aucun fact :

- name: Tâche simple sans facts
  hosts: webservers
  gather_facts: false       # désactive la collecte
  tasks:
    - name: Install nginx
      ansible.builtin.dnf:
        name: nginx
        state: present

become_method: sudo et les modules courants (dnf, systemd) n'ont pas besoin des facts. Les variables comme ansible_distribution ne sont en revanche plus disponibles.

Limiter la collecte avec `gather_subset:`

Plutôt que tout collecter ou rien, filtrez :

- name: Collecter uniquement les facts réseau
  hosts: webservers
  gather_facts: true
  gather_subset:
    - "!all"          # ne pas tout collecter
    - "!min"          # même pas le minimum
    - network         # mais inclure le réseau

Subsets disponibles :

Subset	Contient
`all`	Tout (par défaut)
`min`	Sous-ensemble minimal (distribution, kernel, hostname)
`network`	Interfaces, IPs, MAC
`hardware`	CPU, mémoire, disques
`virtual`	Virtualisation détectée
`facter`, `ohai`	External fact gatherers

Préfixer avec ! = exclure. Combinaisons typiques :

['!all', '!min', 'network'] : seulement le réseau (le plus rapide)
['!all', 'min'] : juste le minimum vital

Sur 100 hôtes, passer de all à min peut réduire le temps de gather de 50 %.

Les magic vars

Variables automatiquement injectées par Ansible, pas issues du gather :

`inventory_hostname`

Le nom de l'hôte courant tel que défini dans l'inventaire (web1.lab, pas web1).

- name: Saluer
  ansible.builtin.debug:
    msg: "Bonjour depuis {{ inventory_hostname }}"

`groups`

Dict des groupes de l'inventaire. groups['webservers'] retourne la liste des hôtes du groupe :

- name: Lister les webservers
  ansible.builtin.debug:
    msg: "{{ groups['webservers'] }}"
# → ['web1.lab', 'web2.lab']

- name: Compter les webservers
  ansible.builtin.debug:
    msg: "{{ groups['webservers'] | length }} webservers"
# → "2 webservers"

`hostvars`

Dict indexé par hostname qui contient toutes les variables et facts de chaque hôte. Pour lire un fact d'un autre hôte :

- name: Afficher l'IP de web2 depuis web1
  ansible.builtin.debug:
    msg: "{{ hostvars['web2.lab'].ansible_default_ipv4.address }}"

Pour que hostvars['<other>'].ansible_* retourne quelque chose, l'hôte <other> doit avoir été gather dans un play précédent ou le play courant. Sinon les facts sont vides.

Cas typique : un pre-gather play qui cible le groupe complet sans tâches, puis un play qui exploite les hostvars :

- name: Pre-gather
  hosts: all
  gather_facts: true
  tasks: []

- name: Utiliser hostvars
  hosts: db1.lab
  tasks:
    - name: Lire l'IP de web1
      ansible.builtin.debug:
        msg: "{{ hostvars['web1.lab'].ansible_default_ipv4.address }}"

`play_hosts` et `ansible_play_batch`

play_hosts : liste des hôtes ciblés par le play avant filtrage par serial:.
ansible_play_batch : liste des hôtes du batch courant (pertinent quand serial: N).

- name: Liste du batch courant
  ansible.builtin.debug:
    msg: "Batch : {{ ansible_play_batch }}"

Cas pratique, synthèse cross-host (lab `ecrire-code/facts-magic-vars`)

Voici l'exemple validé sur le lab 14-ecrire-code-facts-magic-vars :

---
- name: Pre-gather facts sur web1 (rend hostvars web1 disponibles)
  hosts: web1.lab
  gather_facts: true
  tasks: []

- name: Synthese facts sur db1
  hosts: db1.lab
  become: true
  gather_facts: true
  tasks:
    - name: Poser le fichier de synthese
      ansible.builtin.copy:
        dest: /tmp/facts-summary.txt
        content: |
          db1_hostname={{ inventory_hostname }}
          db1_os={{ ansible_distribution }}
          db1_memory={{ ansible_memtotal_mb }}
          webservers_count={{ groups['webservers'] | length }}
          web1_ip={{ hostvars['web1.lab'].ansible_default_ipv4.address }}
        mode: "0644"

Contenu du fichier sur db1.lab :

db1_hostname=db1.lab
db1_os=AlmaLinux
db1_memory=1740
webservers_count=2
web1_ip=10.10.20.21

Le pre-gather sur web1.lab est nécessaire pour que hostvars['web1.lab'] soit peuplé au moment du second play.

Quand utiliser quoi

Situation	Mécanisme
Adapter une commande à la distribution	`when: ansible_distribution == 'AlmaLinux'`
Calculer une mémoire dépendante de la machine	`nginx_workers: "{{ ansible_processor_cores * 2 }}"`
Connaître l'IP d'un hôte voisin	`hostvars['<host>'].ansible_default_ipv4.address`
Itérer sur tous les membres d'un groupe	`loop: "{{ groups['webservers'] }}"`
Identifier l'hôte courant dans un template	`{{ inventory_hostname }}`
Connaître quels hôtes sont dans le batch courant	`{{ ansible_play_batch }}`

Pièges fréquents

Symptôme	Cause	Fix
`'NoneType' object has no attribute 'ansible_default_ipv4'`	hostvars de l'hôte n'a pas été gather	Ajouter un pre-gather play sur le groupe
`gather_facts: false` mais le playbook utilise `ansible_distribution`	Désactivation accidentelle	Réactiver `gather_facts: true` ou utiliser le module `setup` ad-hoc
`groups` vide ou incorrect	Mauvais nom de groupe ou inventaire pas chargé	Vérifier avec `ansible-inventory --graph`
`gather_subset` ignore mes choix	Mauvaise syntaxe de l'expression	Vérifier l'ordre `['!all', 'network']` (l'ordre compte)
`ansible_*` direct (sans `ansible_facts.`)	`INJECT_FACTS_AS_VARS` désactivé (futur Ansible)	Toujours préférer `ansible_facts.distribution` à `ansible_distribution`

À retenir

gather_facts: true (défaut) collecte les facts via le module setup au début de chaque play.
gather_subset: filtre la collecte, passer de all à min peut diviser par 2 le temps de gather.
Les magic vars essentielles : inventory_hostname, groups, hostvars, play_hosts, ansible_play_batch.
hostvars['<host>'].ansible_* lit les facts d'un autre hôte, nécessite que cet hôte ait été gather au préalable.
À l'avenir, ansible_facts.distribution sera la forme canonique, ansible_distribution deprecated.

Pratiquer dans le lab

Cette page a un lab d'accompagnement : labs/ecrire-code/facts-magic-vars/ dans stephrobert/ansible-training. Il contient un README.md guidé, un Makefile (make verify lance les tests), et un challenge final auto-évalué : synthèse cross-host : facts db1 + IP web1 via hostvars (pre-gather sur web1).

Une fois le lab provisionné :

cd ~/Projets/ansible-training/labs/ecrire-code/facts-magic-vars/

cat README.md           # tuto pas à pas
cat challenge/README.md # consigne du challenge final
pytest -v challenge/tests/   # lancer les tests testinfra

Si les tests passent, vous maîtrisez les concepts couverts dans ce guide. En cas de blocage, docs/troubleshooting.md à la racine du repo couvre les pièges fréquents (rate-limit SSH, clé absente, collection manquante).

Prochaines étapes

Précédence des variables (RHCE) Les 22 niveaux officiels Ansible, objectif explicite RHCE EX294

Filtres Jinja2 essentiels default, regex_replace, dict2items, combine, selectattr, map en profondeur