Modules archive et unarchive Ansible : compresser et extraire

archive et unarchive sont les deux modules complémentaires pour gérer des tarballs et zips dans Ansible. archive: crée une archive sur le managed node à partir d'un ou plusieurs chemins. unarchive: extrait une archive vers un dossier, depuis le control node (auto-copy), une URL, ou une archive déjà présente sur le managed node.

Cas d'usage typiques : backup avant migration (archive d'un /etc/myapp/), déploiement applicatif depuis un tarball stocké sur S3, restauration d'un dump SQL compressé.

Ce que vous allez apprendre

• Les formats supportés par archive: (gz, bz2, xz, zip, tar).
• Les 3 modes de unarchive: : auto-copy, URL, remote_src: true.
• L'option creates: pour rendre unarchive: idempotent.
• Le piège du slash final sur archive: path: qui change la structure de l'archive.

Prérequis

• Connaître copy: et file: (souvent enchaînés avec archive/unarchive).

Deux modules, deux collections

Une asymétrie surprend à la première utilisation, et elle vaut d'être posée avant les exemples. Ces deux modules qui semblent aller par paire ne vivent pas au même endroit :

• ansible.builtin.unarchive est livré avec le moteur, rien à installer.
• community.general.archive appartient à la collection community.general, qu'il faut donc avoir installée.

Écrire ansible.builtin.archive fonctionne par redirection, mais ce n'est pas le nom canonique, et ansible-lint le signale en profil production. La raison de cette séparation est historique : décompresser une archive est un besoin universel, la créer l'est moins, et le découpage de 2020 en collections a tranché ainsi.

archive, créer un tarball

- name: Archiver les logs Apache
  community.general.archive:
    path: /var/log/httpd/
    dest: /var/backups/httpd-logs.tar.gz
    format: gz
    remove: false
    mode: "0600"

Option	Rôle
path:	Chemin(s) source, string ou liste, sur le managed node
dest:	Archive de sortie sur le managed node
format:	gz (défaut), bz2, xz, zip, tar
remove: true	Supprime les sources après l'archivage (utile pour rotation logs)
exclude_path:	Liste de chemins à exclure de l'archive

Glissez pour voir

Piège du slash final : path: /var/log/httpd/ (avec slash) archive le contenu du dossier au niveau racine de l'archive. path: /var/log/httpd (sans slash) archive le dossier lui-même. Conséquence : à l'extraction, le résultat diffère.

# Avec slash : fichiers a la racine de l archive
$ tar tzf httpd-logs.tar.gz
access.log
error.log

# Sans slash : fichiers sous httpd/
$ tar tzf httpd-logs.tar.gz
httpd/
httpd/access.log
httpd/error.log

unarchive, 3 modes d'extraction

Le module fait toujours la même chose, extraire une archive vers un dossier ; ce qui change d'un mode à l'autre, c'est d'où vient l'archive. Un fichier rangé dans files/ transite par le control node, une URL est téléchargée par la machine cible elle-même, une archive déjà posée sur cette machine n'est pas transférée du tout. Les deux derniers cas partagent la même option, remote_src: true, ce qui explique qu'on les confonde souvent.

Mode 1 : auto-copy (src: local au control node)

- name: Deployer myapp depuis tarball local
  ansible.builtin.unarchive:
    src: ./files/myapp-1.0.tar.gz
    dest: /opt/myapp
    creates: /opt/myapp/bin/myapp

Ansible copie d'abord le tarball depuis files/ du playbook vers le managed node, puis l'extrait. creates: rend l'opération idempotente, si /opt/myapp/bin/myapp existe déjà, la tâche est skipped.

Mode 2 : URL distante

- name: Telecharger et extraire grafana
  ansible.builtin.unarchive:
    src: https://dl.grafana.com/oss/release/grafana-10.4.0.linux-amd64.tar.gz
    dest: /opt/grafana
    remote_src: true
    creates: /opt/grafana/grafana-10.4.0/bin/grafana-server
    extra_opts:
      - "--strip-components=1"

Ansible télécharge depuis l'URL directement sur le managed node (pas de passage par le control node). extra_opts: ["--strip-components=1"] est l'astuce classique pour enlever le dossier racine de l'archive, utile quand la convention upstream est archive-X.Y.Z/....

Mode 3 : archive déjà sur le managed node (remote_src: true)

- name: Restaurer le dump deja copie
  ansible.builtin.unarchive:
    src: /var/backups/dump-2026-04-25.tar.gz
    dest: /var/restore
    remote_src: true

remote_src: true indique que src: est sur le managed node, pas sur le control node. Pas de copy automatique. Mode utilisé après un fetch: + redéploiement ou pour restaurer un backup local.

Idempotence avec creates:

unarchive: n'est pas idempotent par défaut, il extrait à chaque run. Pour rendre l'opération idempotente, deux options :

# Option 1 : creates (le plus simple)
unarchive:
  src: …
  dest: /opt/myapp
  creates: /opt/myapp/bin/myapp  # Skip si ce fichier existe deja

# Option 2 : verifier le checksum manuellement
- name: Relever l'état de version
  ansible.builtin.stat:
    path: /opt/myapp/version
  register: version_check

- name: Déployer l'archive myapp
  ansible.builtin.unarchive:
    src: …
    dest: /opt/myapp
  when: not version_check.stat.exists

Privilégier creates:, c'est le pattern standard et le plus lisible.

Permissions et propriétaire

- name: Déployer l'archive myapp
  ansible.builtin.unarchive:
    src: app.tar.gz
    dest: /opt/myapp
    owner: myapp
    group: myapp
    mode: "0750"
    remote_src: true

Les options owner:, group:, mode: s'appliquent aux fichiers extraits, pas à l'archive elle-même. Pratique pour s'assurer que les fichiers déployés ont le bon propriétaire sans tâche file: state: directory recurse: true séparée.

Pièges courants

Ces cinq pannes se répartissent en deux familles, et les reconnaître fait gagner le temps du diagnostic. Trois viennent d'une option absente, creates: pour l'idempotence, remote_src: true pour une URL, extra_opts: pour le dossier racine de trop. Les deux autres viennent de la structure de l'archive ou des droits de lecture sur les sources, et une seule commande les départage, tar tzf sur l'archive produite.

Symptôme	Cause	Fix
Extraction à chaque run	Pas de creates:	Ajouter creates: <fichier_marqueur>
Structure de l'archive inattendue	Slash final sur path:	Vérifier avec tar tzf ; ajuster le slash
Téléchargement échoue	Pas de remote_src: true sur URL	Toujours remote_src: true avec URL HTTPS
Dossier racine archive-1.0/ non voulu	Convention upstream	extra_opts: ["--strip-components=1"]
archive: échoue avec "permission denied"	path: contient des fichiers non lisibles par become	Vérifier les permissions ou ajouter become: true

Glissez pour voir

Quand préférer archive: à command: tar

Un command: tar -czf fonctionne, et c'est précisément ce qui le rend tentant. Trois différences justifient malgré tout le module, et la première pèse plus que les deux autres : une commande brute ne compare rien, elle réécrit l'archive à chaque passage et le recap annonce un changement qui n'en est pas un. Sur un playbook joué toutes les nuits, cette fausse alerte finit par masquer les vraies.

• Idempotence : archive: ne recrée pas si rien n'a changé. command: tar -czf recrée à chaque run.
• Multi-format : archive: gère gz/bz2/xz/zip via une seule option. tar ne fait pas de zip.
• Lisibilité : archive: est explicite, un lecteur comprend l'intention sans connaître les flags tar.

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• archive: crée des tarballs (gz, bz2, xz, zip), idempotent.
• unarchive: a 3 modes : auto-copy (défaut), URL (remote_src: true), local-au-managed (remote_src: true).
• creates: est obligatoire pour rendre unarchive: idempotent.
• Slash final sur archive: path: change la structure, toujours vérifier avec tar tzf.
• extra_opts: ["--strip-components=1"] = le pattern pour enlever le dossier racine d'une archive upstream.

Mettre en pratique

Le vrai test de ces deux modules, c'est de les enchaîner sur une même machine. Ce lab vous fait préparer des fichiers sur db1.lab, produire une archive tar.gz avec community.general.archive, puis la réextraire avec remote_src: true et creates:. La correction rejoue le playbook une seconde fois : sans creates:, l'extraction repart et l'idempotence tombe.

Lab pratique

Modules archive et unarchive : compresser et extraire

$ dsoxlab run modules-fichiers-archive-unarchive

Environnement : VM·Durée : ~30 min

Validé : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que dsoxlab et comment l'installer

dsoxlab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Installer la CLI et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/ansible-training

Lancer ce lab, puis valider votre travail :

dsoxlab run modules-fichiers-archive-unarchive
dsoxlab check modules-fichiers-archive-unarchive

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille l'installation, le calcul du score et les pièges.

Pour aller plus loin

• Module systemd_service : redémarrer l'application juste après l'extraction d'une nouvelle release.
• Module cron : planifier la création régulière d'une archive de sauvegarde.
• Module mount : préparer le volume qui reçoit les archives, avec les bonnes options dans /etc/fstab.

×

📖 Voir la documentation →