Documentation Ansible¶

Référence synthétique pour démarrer ou maintenir un projet Ansible : structure, exemples réutilisables et bonnes pratiques.

ℹ️ Note de lecture : les modules de base (copy, template, package...) sont utilisés ici sans leur préfixe ansible.builtin. pour la lisibilité. Voir la légende des collections en fin de document.

1. Arborescence d'un projet Ansible¶

mon-projet/
├── ansible.cfg              # Configuration locale (inventaire, user, etc.)
├── inventory/
│   ├── hosts.ini            # Inventaire statique
│   └── group_vars/
│       ├── all.yml          # Variables communes à tous les hôtes
│       └── webservers.yml   # Variables propres à un groupe
├── playbooks/
│   └── site.yml             # Playbook principal
└── roles/
    └── nginx/
        ├── defaults/main.yml   # Variables par défaut (priorité basse)
        ├── vars/main.yml       # Variables du rôle (priorité haute)
        ├── tasks/main.yml      # Tâches du rôle
        ├── handlers/main.yml   # Handlers (restart service, etc.)
        ├── templates/          # Fichiers Jinja2 (.j2)
        ├── files/              # Fichiers statiques à copier
        └── meta/main.yml       # Dépendances du rôle

Exemple d'inventaire `hosts.ini`¶

[webservers]
web01 ansible_host=192.168.1.10

[windows]
win01 ansible_host=192.168.1.20

[windows:vars]
ansible_connection=winrm
ansible_user=Administrator
ansible_winrm_transport=ntlm
ansible_winrm_server_cert_validation=ignore

Exemple de `ansible.cfg`¶

[defaults]
inventory = ./inventory/hosts.ini
remote_user = ansible
host_key_checking = False
retry_files_enabled = False
stdout_callback = yaml

[privilege_escalation]
become = True
become_method = sudo

Squelette d'un playbook `site.yml`¶

---
- name: Configurer les serveurs web
  hosts: webservers
  become: yes
  vars:
    app_version: "1.2.3"
  roles:
    - common
    - nginx

2. Exemples réutilisables¶

Copier un fichier sur une machine distante¶

- name: Copier un fichier de configuration
  copy:
    src: files/app.conf            # Chemin local (relatif au rôle ou au playbook)
    dest: /etc/app/app.conf        # Chemin distant
    owner: root
    group: root
    mode: '0644'
    backup: yes                    # Sauvegarde l'ancien fichier si modifié

Générer un fichier via un template Jinja2¶

templates/nginx.conf.j2

server {
    listen {{ http_port | default(80) }};
    server_name {{ domain_name }};
    root {{ web_root }};
}

Tâche associée :

- name: Déployer la configuration Nginx
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/sites-available/{{ domain_name }}.conf
    mode: '0644'
  notify: Restart nginx          # Déclenche le handler si le fichier change

Handler associé (handlers/main.yml) :

- name: Restart nginx
  service:
    name: nginx
    state: restarted

Installer / désinstaller des paquets¶

Le module package est générique (détecte apt, yum, dnf, etc.).

- name: Installer plusieurs paquets
  package:
    name:
      - nginx
      - git
      - htop
    state: present              # present = installé, latest = mis à jour

- name: Désinstaller un paquet
  package:
    name: apache2
    state: absent

Exécuter des commandes shell (Linux)¶

- name: Exécuter une commande shell
  shell: |
    echo "Déploiement en cours" >> /var/log/deploy.log
    systemctl reload nginx
  args:
    creates: /var/log/deploy.log  # Idempotence : ne s'exécute que si le fichier n'existe pas

- name: Commande simple sans shell (préféré quand possible)
  command: /usr/bin/uptime
  register: uptime_result
  changed_when: false             # Marquer comme non-changeant (lecture seule)

Exécuter du PowerShell via WinRM (Windows)¶

- name: Créer un dossier sous Windows
  ansible.windows.win_file:
    path: C:\Apps\MonApp
    state: directory

- name: Exécuter une commande PowerShell
  ansible.windows.win_shell: |
    Get-Service -Name 'Spooler' | Restart-Service
    Write-Output "Service redémarré"
  register: ps_result

- name: Installer un paquet via Chocolatey
  chocolatey.chocolatey.win_chocolatey:
    name: googlechrome
    state: present

3. Modules complémentaires utiles¶

Gestion des utilisateurs et groupes¶

- name: Créer un groupe
  group:
    name: developers
    state: present

- name: Créer un utilisateur avec clé SSH
  user:
    name: alice
    groups: developers
    shell: /bin/bash
    state: present

- name: Déployer une clé SSH
  ansible.posix.authorized_key:
    user: alice
    state: present
    key: "{{ lookup('file', 'files/alice.pub') }}"

Gestion des services¶

- name: Activer et démarrer un service
  service:
    name: nginx
    state: started        # started, stopped, restarted, reloaded
    enabled: yes          # Démarrage automatique au boot

Gestion des fichiers et dossiers¶

- name: Créer un répertoire
  file:
    path: /opt/monapp
    state: directory
    owner: monapp
    group: monapp
    mode: '0755'

- name: Supprimer un fichier
  file:
    path: /tmp/oldfile.log
    state: absent

- name: Créer un lien symbolique
  file:
    src: /opt/monapp/current
    dest: /usr/local/bin/monapp
    state: link

Modifier une ligne dans un fichier¶

- name: Activer une option dans sshd_config
  lineinfile:
    path: /etc/ssh/sshd_config
    regexp: '^#?PermitRootLogin'
    line: 'PermitRootLogin no'
    backup: yes
  notify: Restart sshd

- name: Ajouter un bloc de configuration
  blockinfile:
    path: /etc/hosts
    block: |
      192.168.1.10 web01
      192.168.1.11 web02
    marker: "# {mark} ANSIBLE MANAGED"

Télécharger un fichier (HTTP/HTTPS)¶

- name: Télécharger une archive
  get_url:
    url: https://example.com/app-1.0.tar.gz
    dest: /tmp/app.tar.gz
    checksum: sha256:abc123...     # Optionnel mais recommandé
    mode: '0644'

- name: Décompresser une archive
  unarchive:
    src: /tmp/app.tar.gz
    dest: /opt/
    remote_src: yes                # Le fichier est déjà sur la machine distante

Variables et secrets avec Vault¶

# Créer un fichier chiffré
ansible-vault create group_vars/all/secrets.yml

# Éditer un fichier chiffré
ansible-vault edit group_vars/all/secrets.yml

# Chiffrer une simple chaîne
ansible-vault encrypt_string 'mon_mot_de_passe' --name 'db_password'

# Utilisation dans une tâche
- name: Configurer la base de données
  template:
    src: db.conf.j2
    dest: /etc/app/db.conf
  vars:
    password: "{{ db_password }}"   # Variable chiffrée par Vault

4. Structures de contrôle¶

Boucles¶

- name: Créer plusieurs utilisateurs
  user:
    name: "{{ item.name }}"
    groups: "{{ item.group }}"
  loop:
    - { name: 'alice', group: 'dev' }
    - { name: 'bob', group: 'ops' }

Conditions¶

- name: Installer un paquet uniquement sur Debian
  apt:
    name: nginx
    state: present
  when: ansible_os_family == "Debian"

- name: Action selon la version de l'OS
  debug:
    msg: "Ubuntu récent"
  when:
    - ansible_distribution == "Ubuntu"
    - ansible_distribution_major_version | int >= 22

Enregistrer et réutiliser un résultat¶

- name: Vérifier si un service tourne
  command: systemctl is-active nginx
  register: nginx_status
  changed_when: false
  failed_when: false

- name: Afficher le résultat
  debug:
    msg: "Nginx est {{ nginx_status.stdout }}"

Bloc d'erreurs (`block` / `rescue` / `always`)¶

- name: Déploiement avec gestion d'erreur
  block:
    - name: Tenter le déploiement
      command: /opt/deploy.sh
  rescue:
    - name: Restaurer la sauvegarde
      command: /opt/rollback.sh
  always:
    - name: Notifier la fin
      debug:
        msg: "Procédure terminée"

5. Bonnes pratiques¶

Pratique	Pourquoi
Nommer toutes les tâches (`name:`)	Logs lisibles et auditables
Préférer les modules dédiés à `shell`/`command`	Idempotence native
`become: yes` au niveau du play	Plus lisible que sur chaque tâche
Variables dans `group_vars`/`host_vars`	Séparation config / logique
Mots de passe via `ansible-vault`	Aucun secret en clair dans Git
Tester avec `--check --diff`	Simulation avant exécution réelle
Découper en rôles dès ~50 lignes	Réutilisabilité et clarté
Utiliser des handlers	Évite les redémarrages inutiles
Versionner avec Git	Historique et collaboration

À propos des collisions de modules¶

Les noms courts (copy, user, file…) peuvent entrer en collision si plusieurs collections définissent un module portant le même nom. En production, la notation complète (FQCN) est recommandée pour lever toute ambiguïté :

# Recommandé en production
- name: Copier un fichier
  ansible.builtin.copy:
    src: app.conf
    dest: /etc/app.conf

Dans cette documentation, le préfixe est omis pour les modules de base afin d'améliorer la lisibilité. Il est conservé uniquement pour les modules issus de collections externes (ansible.windows, chocolatey.chocolatey, ansible.posix).

Astuces pratiques¶

Idempotence avec shell : utiliser creates: ou removes: pour éviter les ré-exécutions inutiles.
changed_when / failed_when : contrôlent finement quand une tâche est marquée modifiée ou en échec.

Tags pour exécuter une partie du playbook :

- name: Installer nginx
  package:
    name: nginx
  tags: [install, web]

Mode debug verbeux : -v, -vv, -vvv pour plus de détails.
Délégation : exécuter une tâche sur un autre hôte avec delegate_to: localhost.

6. Commandes utiles¶

Exécution¶

ansible all -m ping                          # Tester la connectivité
ansible-playbook -i inventory/hosts.ini site.yml
ansible-playbook site.yml --check --diff     # Mode simulation
ansible-playbook site.yml --limit web01      # Sur un seul hôte
ansible-playbook site.yml --tags deploy      # Sur certains tags
ansible-playbook site.yml --skip-tags slow   # Exclure certains tags
ansible-playbook site.yml --start-at-task "Nom de la tâche"

Vault¶

ansible-vault create secrets.yml             # Créer un fichier chiffré
ansible-vault edit secrets.yml               # Éditer
ansible-vault view secrets.yml               # Lire sans déchiffrer
ansible-vault rekey secrets.yml              # Changer le mot de passe
ansible-playbook site.yml --ask-vault-pass

Inspection¶

ansible-inventory --list                     # Voir l'inventaire parsé
ansible-inventory --graph                    # Vue arborescente
ansible all -m setup                         # Récupérer les facts d'un hôte
ansible-doc copy                             # Documentation d'un module
ansible-galaxy init roles/mon-role           # Squelette de rôle
ansible-galaxy install -r requirements.yml   # Installer des rôles/collections

7. Variables intégrées (facts) utiles¶

Variable	Description
`ansible_hostname`	Nom court de la machine
`ansible_fqdn`	Nom de domaine complet
`ansible_os_family`	`Debian`, `RedHat`, `Windows`, etc.
`ansible_distribution`	`Ubuntu`, `CentOS`, `Debian`...
`ansible_distribution_major_version`	Version majeure de l'OS
`ansible_default_ipv4.address`	IP principale
`ansible_processor_vcpus`	Nombre de vCPU
`ansible_memtotal_mb`	RAM totale en Mo
`inventory_hostname`	Nom de l'hôte tel qu'il apparaît dans l'inventaire

💡 Utiliser ansible <host> -m setup pour découvrir tous les facts disponibles.

8. Légende — Collections utilisées¶

Les modules présentés dans cette documentation appartiennent aux collections suivantes :

Module dans la doc	Collection complète (FQCN)	Usage
`copy`	`ansible.builtin.copy`	Copier un fichier
`template`	`ansible.builtin.template`	Générer un fichier depuis un template Jinja2
`file`	`ansible.builtin.file`	Gérer fichiers, dossiers, liens
`package`	`ansible.builtin.package`	Gestion générique de paquets
`apt`	`ansible.builtin.apt`	Gestion APT (Debian/Ubuntu)
`service`	`ansible.builtin.service`	Gérer les services système
`user`	`ansible.builtin.user`	Gérer les comptes utilisateurs
`group`	`ansible.builtin.group`	Gérer les groupes
`shell`	`ansible.builtin.shell`	Exécuter une commande via un shell
`command`	`ansible.builtin.command`	Exécuter une commande sans shell
`lineinfile`	`ansible.builtin.lineinfile`	Modifier une ligne dans un fichier
`blockinfile`	`ansible.builtin.blockinfile`	Insérer un bloc dans un fichier
`get_url`	`ansible.builtin.get_url`	Télécharger via HTTP(S)
`unarchive`	`ansible.builtin.unarchive`	Décompresser une archive
`debug`	`ansible.builtin.debug`	Afficher un message de debug
`ansible.windows.win_file`	`ansible.windows.win_file`	Gestion de fichiers Windows
`ansible.windows.win_shell`	`ansible.windows.win_shell`	Exécuter du PowerShell
`ansible.posix.authorized_key`	`ansible.posix.authorized_key`	Gérer les clés SSH autorisées
`chocolatey.chocolatey.win_chocolatey`	`chocolatey.chocolatey.win_chocolatey`	Installer des paquets Windows via Chocolatey

🔧 Installer une collection externe : ansible-galaxy collection install ansible.windows