Commandes ad hoc et modules Ansible

Une commande ad hoc est une action Ansible lancée directement en ligne de commande, sans playbook : un seul module, appliqué tout de suite à un ou plusieurs hôtes. Ce chapitre explique la syntaxe de ansible, les modules à connaître, le choix entre command, shell et un module dédié, la lecture des facts et la documentation intégrée, ansible-doc.

La syntaxe d'une commande ad hoc

ansible <motif> -m <module> -a "<arguments>" [options]

• le motif désigne les hôtes (chapitre 3) ;
• -m nomme le module, de préférence avec son nom complet (FQCN) ;
• -a donne ses arguments, sous la forme clé=valeur séparés par des espaces.

Sans -m, Ansible utilise le module command. Les options utiles :

Des commandes ad hoc utiles

Interroger le parc, sans rien modifier :

# Depuis quand chaque serveur Linux tourne
ansible linux -a "uptime"

# Place libre sur la partition racine
ansible linux -a "df -h /"

# Version du noyau
ansible linux -a "uname -r"

Chaque hôte répond par une ligne nom | statut | rc=code >>, suivie de la sortie de la commande. Avec ansible linux -a "hostname" :

srv-journaux | CHANGED | rc=0 >>
srv-journaux
srv-web | CHANGED | rc=0 >>
srv-web

L'ordre des réponses dépend de l'hôte qui répond le plus vite. rc est le code de retour de la commande : 0 signifie qu'elle a réussi.

Agir sur le parc, avec des modules idempotents :

# Installer tcpdump sur tous les serveurs Linux
ansible linux -b -m ansible.builtin.apt -a "name=tcpdump state=present update_cache=true"

# S'assurer qu'Apache tourne sur le serveur web
ansible serveurs_web -b -m ansible.builtin.service -a "name=apache2 state=started"

# Déposer un message d'accueil
ansible linux -b -m ansible.builtin.copy -a "content='Serveur de Sorbier Logistique : accès réservé\n' dest=/etc/motd mode=0644"

# Récupérer le journal d'Apache sur le nœud de contrôle (un dossier par hôte)
ansible serveurs_web -b -m ansible.builtin.fetch -a "src=/var/log/apache2/error.log dest=./journaux/"

# Redémarrer les serveurs Linux un par un, en attendant que chacun revienne
ansible linux -b -f 1 -m ansible.builtin.reboot

La première exécution de la commande copy affiche CHANGED et le détail du fichier déposé ; la deuxième affiche SUCCESS avec "changed": false, car le fichier a déjà le bon contenu et les bons droits :

srv-web | SUCCESS => {
    "changed": false,
    "checksum": "a25d38fa32e8f0a29d38110f8d44888908dacb74",
    "dest": "/etc/motd",
    "gid": 0,
    "group": "root",
    "mode": "0644",
    "owner": "root",
    "path": "/etc/motd",
    "size": 49,
    "state": "file",
    "uid": 0
}

command, shell ou un module dédié ?

Trois façons de faire exécuter quelque chose :

command et shell ne savent pas si la commande a déjà été faite : Ansible les marque changed à chaque fois et les relance à chaque exécution. Deux arguments rendent une commande idempotente quand elle produit un fichier :

• creates=<chemin> : ne lance la commande que si le chemin n'existe pas ;
• removes=<chemin> : ne la lance que si le chemin existe.

# Ne génère la clé Diffie-Hellman que si le fichier n'existe pas déjà
ansible serveurs_web -b -m ansible.builtin.command \
  -a "openssl dhparam -out /etc/ssl/dhparam.pem 2048 creates=/etc/ssl/dhparam.pem"

Les modules à connaître

Les modules de ansible.builtin sont livrés avec ansible-core ; les autres viennent des collections installées au chapitre 2.

Lire les facts d'un serveur

Les facts sont les informations qu'Ansible collecte sur un hôte : système, version, adresses IP, interfaces, mémoire, disques, processeur. Le module setup les affiche ; un filtre évite d'en recevoir des centaines :

ansible srv-journaux -m ansible.builtin.setup -a "filter=ansible_distribution*"

srv-journaux | SUCCESS => {
    "ansible_facts": {
        "ansible_distribution": "Debian",
        "ansible_distribution_file_parsed": true,
        "ansible_distribution_file_path": "/etc/os-release",
        "ansible_distribution_file_variety": "Debian",
        "ansible_distribution_major_version": "13",
        "ansible_distribution_release": "trixie",
        "ansible_distribution_version": "13.7",
        "discovered_interpreter_python": "/usr/bin/python3"
    },
    "changed": false
}

Quelques facts courants (le filtre filter= accepte les noms avec le préfixe ansible_ et le joker *) :

Dans un playbook, les facts sont collectés automatiquement au début de chaque play et se lisent dans le dictionnaire ansible_facts, sans le préfixe : ansible_facts['distribution'], ansible_facts['default_ipv4']['address'] (chapitre 6).

Trouver les options d'un module : ansible-doc

Chaque module a sa documentation, installée avec lui et lisible hors ligne :

# La documentation complète : options, valeurs par défaut, exemples, valeurs renvoyées
ansible-doc ansible.builtin.user

# Un squelette de tâche avec toutes les options, à copier dans un playbook
ansible-doc -s ansible.builtin.user

# Les modules d'une collection
ansible-doc -l community.general | grep -i ufw

# Les plugins d'un autre type : connexion, inventaire, filtre, lookup
ansible-doc -t connection -l

Dans la documentation, une option précédée de = est obligatoire, une option précédée de - est facultative ; default: donne sa valeur par défaut et choices: les valeurs permises. La section EXAMPLES vaut souvent mieux que bien des tutoriels. La même documentation est en ligne sur docs.ansible.com, mais ansible-doc a l'avantage de correspondre exactement à la version installée.

Ad hoc ou playbook ?

Une bonne règle : si tu tapes la même commande ad hoc une deuxième fois, elle mérite d'aller dans un playbook.

Exercices

ansible linux -a "free -m"
ansible srv-journaux -b -m ansible.builtin.apt -a "name=rsync state=present"
ansible linux -b -m ansible.builtin.user -a "name=mdiallo comment='Moussa Diallo' groups=sudo append=true"
ansible linux -m ansible.builtin.setup -a "filter=ansible_default_ipv4"
ansible linux -b -C -m ansible.builtin.apt -a "name=telnet state=absent"