Chapitre 179 minIntermédiaire
Aide-mémoire : les commandes Ansible
Par Josselyn C., prof de BTS SIO. Mis à jour le .
À la fin de ce chapitre, tu sauras
- retrouver vite une commande ou une option ;
- choisir le module d'une tâche courante ;
- comprendre les messages d'erreur fréquents.
Cet aide-mémoire rassemble les commandes, les options, les modules, les variables et les messages d'erreur d'Ansible les plus utiles, pour ansible-core 2.22. Il sert de référence rapide pendant un TP ou avant un oral ; chaque notion est expliquée dans le chapitre indiqué.
Installer et vérifier
| Commande | Effet |
|---|---|
pipx install ansible-core | Installer ansible-core (chapitre 2) |
pipx inject ansible-core pywinrm | Ajouter une bibliothèque à l'environnement d'Ansible |
pipx upgrade ansible-core | Mettre à jour |
ansible --version | Version, fichier de configuration lu, chemins |
ansible-config dump --only-changed | Réglages modifiés et leur origine |
ansible-galaxy collection install -r requirements.yml -p collections | Installer les collections du projet |
ansible-galaxy collection list | Collections installées |
ansible-galaxy role init roles/<nom> | Créer le squelette d'un rôle |
Inventaire et commandes ad hoc
| Commande | Effet |
|---|---|
ansible-inventory --graph | Arbre des groupes et des hôtes (chapitre 3) |
ansible-inventory --host <hôte> | Variables d'un hôte après fusion |
ansible <motif> --list-hosts | Hôtes visés par un motif |
ansible <motif> -m ansible.builtin.ping | Tester la connexion (chapitre 4) |
ansible <motif> -a "<commande>" | Lancer une commande (module command) |
ansible <motif> -b -m <module> -a "<arguments>" | Lancer un module avec élévation de privilèges |
ansible <motif> -m ansible.builtin.setup -a "filter=ansible_distribution*" | Lire des facts |
ansible-doc <module>, ansible-doc -s <module> | Documentation, squelette de tâche |
ansible-doc -l <collection> | Modules d'une collection |
Motifs : all, groupe, hôte, a:b (union), a:!b (exclusion), a:&b (intersection), srv-* (joker), ~regex (expression régulière).
ansible-playbook
| Option | Effet |
|---|---|
--syntax-check | Vérifier la syntaxe sans rien exécuter |
--list-hosts, --list-tasks, --list-tags | Afficher hôtes, tâches, tags |
-C, --check | Simuler (chapitre 5) |
-D, --diff | Montrer les différences dans les fichiers |
-l <motif>, --limit | Restreindre aux hôtes du motif |
-t <tags>, --skip-tags <tags> | Filtrer par tags |
--start-at-task "<nom>" | Commencer à une tâche |
--step | Confirmer chaque tâche |
-e "<var>=<valeur>", -e @fichier.yml | Variables supplémentaires (priorité maximale) |
-b, -K | Élévation de privilèges, mot de passe d'élévation |
-u <compte>, -k | Compte SSH, mot de passe SSH |
--ask-vault-pass, --vault-password-file <fichier>, --vault-id <id>@<source> | Mot de passe du coffre (chapitre 9) |
-f <n> | Nombre d'hôtes en parallèle |
--force-handlers | Exécuter les handlers notifiés même après un échec |
-v à -vvvv | Niveau de détail |
Codes de retour : 0 succès, 2 au moins un hôte en échec, 4 au moins un hôte injoignable.
Les commandes d'Ansible Vault
| Commande | Effet |
|---|---|
ansible-vault create <fichier> | Créer un fichier chiffré |
ansible-vault encrypt <fichier>, decrypt <fichier> | Chiffrer, déchiffrer |
ansible-vault view <fichier>, edit <fichier> | Lire, modifier |
ansible-vault rekey <fichier> | Changer le mot de passe |
ansible-vault encrypt_string --stdin-name <variable> | Chiffrer une valeur saisie au clavier |
Structure d'un playbook
---
- name: Nom du play
hosts: groupe
become: true
gather_facts: true
vars:
variable: valeur
vars_files:
- vars/fichier.yml
pre_tasks: [] # avant les rôles
roles:
- nom_du_role
tasks:
- name: Nom de la tâche
espace.collection.module:
option: valeur
register: resultat
when: condition
loop: "{{ liste }}"
notify: Nom du handler
tags: [etiquette]
post_tasks: [] # après les tâches
handlers:
- name: Nom du handler
espace.collection.module:
option: valeur
Ordre d'exécution d'un play : collecte des facts, pre_tasks, rôles, tasks, post_tasks ; les handlers notifiés s'exécutent après les pre_tasks, après l'ensemble rôles et tasks, puis après les post_tasks.
Les modules les plus utilisés
| Linux | Windows | Réseau et virtualisation |
|---|---|---|
ansible.builtin.apt, dnf, package | ansible.windows.win_feature | cisco.ios.ios_facts |
ansible.builtin.service, systemd_service | ansible.windows.win_service | cisco.ios.ios_vlans |
ansible.builtin.copy, template | ansible.windows.win_copy, win_template | cisco.ios.ios_l2_interfaces |
ansible.builtin.file | ansible.windows.win_file | cisco.ios.ios_config |
ansible.builtin.lineinfile, blockinfile | ansible.windows.win_lineinfile | cisco.ios.ios_command |
ansible.builtin.user, group | ansible.windows.win_user, win_group | community.proxmox.proxmox_kvm |
ansible.posix.authorized_key | microsoft.ad.user, group, ou | community.proxmox.proxmox_disk |
ansible.builtin.cron | ansible.windows.win_scheduled_task | pfsensible.core.pfsense_alias, pfsense_rule |
community.general.ufw, ansible.posix.firewalld | ansible.windows.win_firewall_rule | |
ansible.builtin.reboot | ansible.windows.win_reboot, win_updates | |
ansible.builtin.command, shell | ansible.windows.win_powershell, win_command, win_shell | |
ansible.builtin.debug, set_fact, stat, wait_for, uri | ansible.windows.win_ping, win_stat |
Variables de connexion
| Variable | Linux | Windows (WinRM) | Cisco |
|---|---|---|---|
ansible_connection | ssh (par défaut) | winrm | ansible.netcommon.network_cli |
ansible_host | Adresse ou nom | Nom complet pour Kerberos | Adresse de gestion |
ansible_port | 22 | 5986 (HTTPS) | 22 |
ansible_user | ansible | svc-ansible@AD.SORBIER.EXAMPLE | ansible |
ansible_password | (clé SSH) | "{{ vault_… }}" | "{{ vault_… }}" |
| Autres | ansible_become: true | ansible_winrm_transport: kerberos | ansible_network_os: cisco.ios.ios |
Priorité des variables (de la plus faible à la plus forte)
defaults d'un rôle → group_vars/all → group_vars/<groupe> → host_vars/<hôte> → facts → vars du play → vars_files → vars d'un rôle → variables de bloc et de tâche → set_fact et register → -e (chapitre 6).
Structure d'un rôle
roles/<nom>/
├── defaults/main.yml variables réglables (priorité minimale)
├── vars/main.yml variables internes (priorité élevée)
├── tasks/main.yml tâches (point d'entrée)
├── handlers/main.yml handlers
├── templates/ modèles Jinja2 (.j2)
├── files/ fichiers copiés tels quels
├── meta/main.yml métadonnées et dépendances
└── README.md documentation
Jinja2 en bref
| Écriture | Sens |
|---|---|
{{ variable }} | Afficher une valeur |
{% for x in liste %} … {% endfor %} | Boucle (dans un template) |
{% if condition %} … {% else %} … {% endif %} | Condition (dans un template) |
{{ v | default('x') }} | Valeur de secours |
{{ liste | join(', ') }} | Joindre une liste |
{{ v | bool }}, {{ v | int }} | Convertir |
{{ dict | dict2items }} | Dictionnaire en liste de paires key, value |
{{ liste | map(attribute='x') | list }} | Extraire un champ |
{{ v | quote }} | Protéger pour le shell |
{{ omit }} | Retirer l'option de la tâche |
Les messages d'erreur fréquents
| Message (extrait) | Cause | Correction |
|---|---|---|
UNREACHABLE! … Permission denied (publickey) | Clé SSH refusée | Clé chargée, authorized_keys, compte |
Host key verification failed | Empreinte inconnue ou changée | Première connexion à la main ; enquêter si elle a changé |
Missing sudo password | Pas de NOPASSWD | -K, ou corriger sudoers.d |
couldn't resolve module/action | Collection absente, faute de nom | ansible-galaxy collection install -r requirements.yml |
Unsupported parameters for (…) module | Option mal nommée | ansible-doc du module |
mapping values are not allowed in this context | Indentation, : non protégé | Aligner, mettre entre guillemets |
found character that cannot start any token | Tabulation | Espaces uniquement |
The task includes an option with an undefined variable | Variable inconnue | ansible-inventory --host, orthographe |
Conditionals must have a boolean result | Condition sur une chaîne (2.19 et suivantes) | Booléen YAML ou | bool |
Attempting to decrypt but no vault secrets found | Mot de passe du coffre non fourni | --ask-vault-pass ou --vault-password-file |
winrm or requests is not installed | pywinrm absent | pipx inject ansible-core pywinrm |
Server not found in Kerberos database | Connexion Windows par adresse IP | Nom complet dans ansible_host |
paramiko is not installed | Bibliothèque SSH réseau absente | pipx inject ansible-core ansible-pylibssh |