Module fetch Ansible : rapatrier des fichiers du managed node

ansible.builtin.fetch est l’inverse exact de copy: — il rapatrie un fichier depuis un managed node vers le control node. Il sert à collecter des logs, sauvegarder des configurations existantes avant migration, ou récupérer des rapports générés par les managed nodes.

fetch: gère deux modes d’organisation : arborescence par hôte (flat: false, défaut) ou fichier unique (flat: true). Le second nécessite d’interpoler inventory_hostname dans le dest: pour éviter les écrasements quand plusieurs hôtes sont concernés.

# Mode par défaut : arborescence par hôte (collected/web1.lab/etc/hostname)
- ansible.builtin.fetch:
    src: /etc/hostname
    dest: collected/
    fail_on_missing: true

# Mode flat : 1 fichier par host avec inventory_hostname (évite l'écrasement)
- ansible.builtin.fetch:
    src: /var/log/myapp/audit.log
    dest: "collected/{{ inventory_hostname }}-audit.log"
    flat: true
    fail_on_missing: true

Sécurité : dest: est résolu depuis playbook_dir — toujours un chemin relatif clair pour éviter les surprises ; ajouter collected/ au .gitignore pour ne jamais committer accidentellement des logs ou configs sensibles rapatriés. fail_on_missing: true est non négociable en production : sans ça, un fichier manquant passe inaperçu et le rapport est faussé.

Ce que vous allez apprendre

Le mode par défaut (arborescence par hôte) et le mode flat (fichier unique).
Comment éviter les écrasements quand plusieurs hôtes envoient le même fichier.
L’option fail_on_missing: true pour échouer explicitement si le fichier manque.
Le piège des chemins relatifs dans dest: (résolus depuis playbook_dir, pas le cwd).

Prérequis

Connaître copy: — fetch: est son miroir.
Comprendre le concept d’inventory_hostname (cf. Magic vars).

Mode par défaut — arborescence par hôte (`flat: false`)

- name: Backup des sshd_config
  ansible.builtin.fetch:
    src: /etc/ssh/sshd_config
    dest: backup/

Résultat sur le control node :

backup/
├── web1.lab/etc/ssh/sshd_config
├── web2.lab/etc/ssh/sshd_config
└── db1.lab/etc/ssh/sshd_config

Ansible reproduit l’arborescence absolue sous un dossier nommé d’après l’hôte. Pas de risque d’écrasement entre hôtes — chacun a son sous-dossier. Mode idéal pour des audits ou des collectes systématiques sur un parc.

Mode flat — fichier unique (`flat: true`)

- name: Recuperer le rapport audit
  ansible.builtin.fetch:
    src: /tmp/audit-report.txt
    dest: ./reports/audit-{{ inventory_hostname }}.txt
    flat: true

Résultat :

reports/
├── audit-web1.lab.txt
├── audit-web2.lab.txt
└── audit-db1.lab.txt

flat: true demande à Ansible de placer le fichier directement dans dest:, sans recréer l’arborescence absolue. Mais sans interpolation de inventory_hostname dans le dest:, chaque hôte écrase le précédent — un seul fichier reste à la fin.

Règle : avec flat: true sur plusieurs hôtes, toujours interpoler inventory_hostname dans dest:.

Validation et sécurité

fetch: valide le checksum du fichier après transfert (option validate_checksum: true par défaut). Si le fichier est modifié pendant le transfert, l’opération échoue.

- name: Recuperer un fichier critique
  ansible.builtin.fetch:
    src: /etc/passwd
    dest: ./backups/
    fail_on_missing: true  # Echoue explicitement si /etc/passwd absent

fail_on_missing: true est important pour les collectes critiques : sans cette option, un fichier absent côté managed node renvoie ok: skipped, et l’opérateur peut ne pas remarquer que les backups manquent pour certains hôtes.

Cas d’usage typiques

Cas	Pattern
Backup config avant migration	`flat: false`, `dest: backup-2026-04-25/`
Collecte de logs	`flat: true` + `inventory_hostname` dans `dest:`
Récupération de licences	`flat: true`, un seul hôte ciblé (pas de boucle)
Audit sécurité multi-hôtes	`flat: false`, exploite l’arborescence sortie pour `diff` croisé

Pièges courants

Symptôme	Cause	Fix
Un seul fichier dans `dest:` malgré 5 hôtes	`flat: true` sans `{{ inventory_hostname }}` dans `dest:`	Interpoler `inventory_hostname`
Les fichiers atterrissent dans `solution/<lab>/`	`dest:` relatif résolu depuis `playbook_dir`, pas le cwd	Utiliser `{{ inventory_dir }}/../collected/`
`fetch:` ignoré silencieusement	Fichier source absent + `fail_on_missing: false` (défaut)	Mettre `fail_on_missing: true`
Permission denied côté control node	Le `dest:` n’est pas writable par l’utilisateur qui lance Ansible	Vérifier les permissions du dossier local

Différence avec `slurp:`

slurp: (autre module Ansible) lit le contenu d’un fichier distant et le retourne en base64 dans une variable, sans écrire localement. À utiliser quand on veut inspecter le contenu en mémoire (vérifier une config, alimenter un template:), pas le sauvegarder. fetch: reste le bon choix dès qu’on veut un fichier persistant côté control node.

À retenir

fetch: = inverse de copy: — du managed node vers le control node.
Mode défaut : arborescence par hôte (sûr, jamais d’écrasement).
Mode flat : fichier unique, mais toujours interpoler inventory_hostname sur multi-hôtes.
fail_on_missing: true sur les collectes critiques (sinon les manques sont silencieux).
Chemin relatif dest: est résolu depuis playbook_dir, pas le cwd — préférer inventory_dir-relatif ou absolu.

Pratiquer dans le lab

Cette page a un lab d’accompagnement : labs/modules-fichiers/fetch/ dans stephrobert/ansible-training.

Challenge — sur web1.lab ET db1.lab :

fetch: /etc/os-release vers ./collected/<host>-os-release.txt (flat, interpolation hostname).
Sur web1.lab uniquement : écrire un fichier de tag puis le rapatrier.

Validation pytest :

ansible-playbook solution.yml
pytest -v labs/modules-fichiers/fetch/challenge/tests/

4 tests vérifient les fichiers côté control node (pas via SSH — c’est l’inverse de copy:).

Prochaines étapes

Module copy Le miroir de fetch — pour pousser un fichier dans l'autre sens

archive et unarchive Pour rapatrier des arborescences entières (compresser puis fetch)

Variables magiques inventory_hostname, hostvars, groups — la mécanique multi-hôtes

Pivot Modules Ansible Vue d'ensemble des modules de gestion de fichiers