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é.

# Backup avant migration (archive sur la cible)
- ansible.builtin.archive:
    path: /etc/myapp
    dest: /var/backups/myapp-{{ ansible_date_time.iso8601_basic_short }}.tar.gz
    format: gz
    owner: root
    group: root
    mode: "0600"            # secrets à l'intérieur — accès root only

# Déploiement depuis tarball local du control node (auto-copy)
- ansible.builtin.unarchive:
    src: files/myapp-1.2.3.tar.gz
    dest: /opt/myapp/
    owner: myapp
    group: myapp
    mode: "0750"
    creates: /opt/myapp/VERSION   # idempotence : skip si déjà extrait

# Déploiement depuis URL distante (vérification checksum obligatoire)
- ansible.builtin.unarchive:
    src: https://releases.example.com/myapp-1.2.3.tar.gz
    dest: /opt/myapp/
    remote_src: true
    creates: /opt/myapp/VERSION
    extra_opts:
      - --strip-components=1

Sécurité non négociable :

mode: "0600" sur les archives qui contiennent des secrets ou configs sensibles — lisible root only.
owner: + group: explicites côté unarchive: pour éviter que les fichiers extraits prennent l’UID/GID de l’archive (peut casser les permissions cibles).
creates: mandatory pour l’idempotence — sans ça, unarchive: réextrait à chaque run et marque changed=true.
Pour un téléchargement HTTPS, toujours valider un checksum sur l’URL (via get_url: + checksum: plutôt que unarchive: src: URL directement, qui ne valide pas).

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).

archive — créer un tarball

- name: Archiver les logs Apache
  ansible.builtin.archive:
    path: /var/log/httpd/
    dest: /var/backups/httpd-logs.tar.gz
    format: gz
    remove: false

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
- ansible.builtin.stat:
    path: /opt/myapp/version
  register: version_check

- 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

- 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.

Pratiquer dans le lab

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

Challenge — sur db1.lab :

Préparer 3 fichiers dans /opt/data-source/.
Archiver vers /opt/backup/data.tar.gz (format gz).
Extraire vers /opt/restored/ avec remote_src: true et creates:.

Validation pytest+testinfra :

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

6 tests vérifient les fichiers source, l’archive (taille > 100 octets) et l’extraction.

Prochaines étapes

Module fetch Pour rapatrier l'archive du managed node vers le control node après archivage

Module copy Pour pousser une archive depuis le control node avant unarchive remote_src

Module file Préparer le dossier de destination avant extraction (state: directory)

Pivot Modules Ansible Vue d'ensemble : modules builtin, posix, community.general, FQCN obligatoire