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

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

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

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`

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

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.

À retenir

archive: crée des tarballs (gz, bz2, xz, zip), idempotent.
unarchive: a 3 modes : auto-copy (defaut), 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.

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 dsoxlab, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
git clone https://github.com/stephrobert/ansible-training.git
cd 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.

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.