Trouver de l'aide sur un module avec `ansible-doc`

`ansible-doc` : votre sésame pour l'univers des modules Ansible

Ansible dispose d'un écosystème riche de milliers de modules, chacun conçu pour accomplir des tâches spécifiques, allant de la simple manipulation de fichiers à l'orchestration complexe d'infrastructures cloud. Face à cette diversité, il est crucial de disposer d'un moyen simple et rapide d'accéder à la documentation de chaque module. C'est précisément le rôle de l'outil en ligne de commande ansible-doc.

ansible-doc est une interface qui vous permet de consulter, directement depuis votre terminal, la documentation complète des modules installés sur votre noeud de contrôle Ansible. Cette documentation inclut une description du module, la liste exhaustive de ses paramètres (avec leurs types, valeurs par défaut, et s'ils sont requis), des notes d'utilisation importantes, des exemples concrets, et parfois des informations sur les valeurs de retour du module. Maîtriser ansible-doc est une compétence fondamentale qui vous rendra autonome et efficace dans l'écriture de vos playbooks et commandes Ad-Hoc.

Plutôt que de naviguer constamment sur le site web de la documentation Ansible (bien qu'il soit une excellente ressource), ansible-doc vous offre un accès instantané à l'information dont vous avez besoin, quand vous en avez besoin, sans quitter votre environnement de travail.

Syntaxe de base et utilisation courante d'`ansible-doc`

L'utilisation la plus fondamentale d'ansible-doc consiste à afficher la documentation d'un module spécifique. La syntaxe est la suivante :

ansible-doc [options] 

Par exemple, pour consulter la documentation du module file, qui permet de gérer les attributs des fichiers et des répertoires :

ansible-doc file

La sortie sera formatée pour le terminal et contiendra plusieurs sections :

• DESCRIPTION : Un résumé de ce que fait le module.
• PARAMETERS : La liste des paramètres acceptés par le module. Pour chaque paramètre, vous trouverez :
  • Son nom (ex: path, state, mode).
  • Une description de son rôle.
  • S'il est requis (required: true).
  • Sa valeur par défaut (default: ...), s'il en a une.
  • Le type de valeur attendu (string, boolean, list, integer, etc.).
  • Parfois, les choix possibles pour ce paramètre (choices: ["present", "absent", ...]).
• NOTES : Informations importantes, avertissements, ou comportements spécifiques à connaître.
• EXAMPLES : Des exemples d'utilisation du module dans un playbook, souvent très utiles pour comprendre rapidement comment l'utiliser.
• RETURN VALUES : Les données que le module retourne après son exécution (utile pour enregistrer le résultat dans une variable et l'utiliser plus tard).

Vous pouvez naviguer dans la sortie en utilisant les touches habituelles de votre pager (souvent less), comme Espace pour descendre, b pour remonter, / pour rechercher, et q pour quitter.

Si vous connaissez le nom complet du module avec sa collection (FQCN - Fully Qualified Collection Name), vous pouvez aussi l'utiliser :

ansible-doc ansible.builtin.file

Cela est particulièrement utile lorsque plusieurs collections pourraient fournir un module avec le même nom court.

Options utiles d'`ansible-doc` pour affiner votre recherche

ansible-doc propose plusieurs options pour faciliter votre recherche et l'affichage de l'information :

• -l, --list : Liste tous les modules (et autres types de plugins si combiné avec -t) disponibles sur votre système. La liste peut être très longue. Il est courant de la combiner avec des outils comme grep pour filtrer les résultats :

# Lister tous les modules contenant 'mysql'
ansible-doc -l | grep mysql

# Lister tous les modules de la collection 'community.docker'
ansible-doc -l | grep community.docker

• -s , --snippet : Affiche uniquement la section EXAMPLES (des extraits de code ou "snippets") pour le module spécifié. C'est extrêmement pratique pour obtenir rapidement un exemple de syntaxe à copier-coller et adapter.

# Afficher les exemples pour le module 'apt'
ansible-doc -s apt

La sortie sera une ou plusieurs tâches de playbook prêtes à l'emploi :

- name: Update apt repo and cache on Debian/Ubuntu
  ansible.builtin.apt:
    update_cache: yes
    force_apt_get: yes
    cache_valid_time: 3600

- name: Upgrade all apt packages
  ansible.builtin.apt:
    upgrade: dist
    force_apt_get: yes

- name: Install the latest version of "apache2" and "postgresql"
  ansible.builtin.apt:
    name: ["apache2", "postgresql"]
    state: latest
# ... et d'autres exemples

• -t , --type : Permet de spécifier le type de plugin Ansible pour lequel vous cherchez de la documentation. Par défaut, c'est module. D'autres types utiles incluent :
  • lookup : Pour les plugins de lookup (ex: ansible-doc -t lookup env).
  • callback : Pour les plugins de callback (ex: ansible-doc -t callback profile_tasks).
  • filter : Pour les filtres Jinja2 (ex: ansible-doc -t filter to_json).
  • strategy : Pour les stratégies d'exécution de playbook.
• -j, --json : Affiche la documentation du module au format JSON. Utile pour un traitement programatique de la documentation par d'autres outils.

Par exemple, pour lister tous les plugins de lookup :

ansible-doc -l -t lookup

Intégrer `ansible-doc` dans votre flux de travail

L'utilisation efficace d'ansible-doc peut grandement accélérer votre apprentissage et votre productivité avec Ansible.

Quand utiliser ansible-doc ?

• Avant d'utiliser un nouveau module : Consultez toujours sa documentation pour comprendre son but, ses paramètres requis et optionnels, et ses comportements par défaut.
• En cas de doute sur un paramètre : Si vous n'êtes pas sûr de ce que fait un paramètre ou des valeurs qu'il accepte, ansible-doc est votre référence.
• Pour trouver des exemples : L'option -s est parfaite pour démarrer rapidement avec la syntaxe correcte d'un module.
• Lors du débogage : Si un module ne se comporte pas comme prévu, relire sa documentation, en particulier la section NOTES et les valeurs de retour, peut souvent éclaircir la situation.
• Pour explorer : Utilisez ansible-doc -l pour découvrir de nouveaux modules qui pourraient simplifier vos tâches.

Astuces pour une utilisation optimale :

• Alias de shell : Si vous utilisez fréquemment ansible-doc -s, vous pourriez créer un alias dans votre shell, par exemple alias ads='ansible-doc -s', pour taper simplement ads copy.
• Combinaison avec grep : Lorsque vous parcourez la documentation complète d'un module (sans -s), vous pouvez utiliser la fonction de recherche de votre pager (souvent /) pour trouver rapidement un paramètre ou un mot-clé spécifique.
• Vérifier la source du module : La documentation indique souvent la collection à laquelle appartient un module (ex: ansible.builtin.file, community.general.ufw). Cela peut être utile pour comprendre d'où vient le module et où trouver plus d'informations si nécessaire (par exemple, sur GitHub pour les collections communautaires).

En résumé, ansible-doc est un compagnon indispensable pour quiconque travaille avec Ansible. Prenez le temps de vous familiariser avec cet outil, et il deviendra une seconde nature, vous permettant de naviguer avec confiance dans le vaste paysage des modules Ansible et d'exploiter pleinement leur potentiel d'automatisation.