Modules Ansible

Ce document poursuit l’objectif d’expliquer le concept, le rôle, la manipulation et les codes de retour des modules. Le développement de modules devrait faire l’objet d’un document spécifique.

Objectifs de certification

RHCE EX294 (RHEL8)

Si vous poursuivez des objectifs de certification voici ceux qui sont suggérés ici :

  • 2. Maîtrise des composants de base d’Ansible
    • 2.2. Modules
    • 2.3. Variables
    • 2.4. Facts
    • 2.8. Utiliser la documentation fournie pour trouver des informations spécifiques aux modules et commandes Ansible
  • 5. Écriture de scripts pour les tâches d’administration
    • 5.2. Créer des scripts shell simples qui exécutent les commandes Ansible ad hoc
  • 7. Utilisation des modules Ansible

1. Introduction

Les modules Ansible sont des “bouts de codes” écrits principalement en Python (mais tout langage supportant les retours JSON est autorisé) pour modifier l’état d’une propriété d’un hôte. Les modules sont invoqués par l’exécution de tâches soit directement dans la ligne de commande ansible ou dans des livres de jeu avec la commande ansible-playbook.

2. Documentation des modules

Certains d’entre nous trouveront la documentation des modules plus agréable à lire en ligne : https://docs.ansible.com/ansible/latest/modules/modules_by_category.html. Mais on obtient exactement le même résultat hors-ligne, sur la machine de contrôle avec la commande ansible-doc :

Pour lister les modules :

ansible-doc -l

Pour appeler directement la documentation d’un module.

ansible-doc <module>
ansible-doc -s <module>

Veuillez vous informer sur les modules suivants :

  • ansible-doc setup
  • ansible-doc ping
  • ansible-doc lineinfile
  • ansible-doc uri

3. Mode Ad-Hoc

La commande ansible offre la possibilité d’exécuter des modules ansible de manière “ad-hoc”, c’est à dire tâche par tâche, commande par commande. L’intérêt est de pouvoir exécuter la même tâche à exécuter en parallèle sur un inventaire (constitué d’un certain nombre de cibles) en tout ou en partie.

ansible --help

offre ce résultat sur la sortie

Usage: ansible <host-pattern> [options]

Define and run a single task 'playbook' against a set of hosts

En général, la commande s’écrit ansible suivie d’un hôte ou d’un groupe d’inventaire suivie -m nom_de_module suivie l’option d’argument -a "clé=valeur clé=valeur clé=valeur", par exemple de manière formelle :

ansible <group_inventaire> -m nom_de_module -a "clé=valeur clé=valeur clé=valeur"

Deux autres exemples fonctionnels :

ansible localhost -m debug -a "msg='Hello World!'"
ansible localhost -m file -a "path=/tmp/test state=touch"

Attention, l’inventaire doit exister et doit être nourri des hôtes à gérer !

On trouvera aussi des options utiles de la ligne de commande comme celles-ci :

  • -b, --become active l’élévation de privilèges (sudo)
  • -e qui permet de placer des variables ponctuelles ou un fichier de variables,
  • -o qui offre la sortie standard en une seule ligne,
  • ou encore -l, --limit qui permet de limiter la tâche à certains hôtes seulement de l’inventaire,
  • ou encore -v ou -vvv pour la verbosité,
  • -i précise le chemin du fichier d’inventaire.

4. Valeurs de retour de l’exécution des tâches et des modules

Ansible génère des valeurs de retour à la suite de l’exécution des tâches et des modules.

Return Values

  • backup_file (fichier_de_sauvegarde) : Pour les modules qui implémentent backup=no|yes lors de la manipulation de fichiers, un chemin vers le fichier de sauvegarde créé.
  • changed (modifié) : Un booléen indiquant si la tâche a dû effectuer des modifications.
  • failed (échoué) : Un booléen qui indique si la tâche a échoué ou non.
  • invocation : Informations sur la manière dont le module a été invoqué.
  • msg : Une chaîne avec un message générique relayé à l’utilisateur.
  • rc : Certains modules exécutent des utilitaires en ligne de commande ou sont conçus pour exécuter des commandes directement (modules raw, shell, command, etc.), ce champ contient le ‘code de retour’ de ces utilitaires.
  • results : Si cette clé existe, elle indique qu’une boucle était présente pour la tâche et qu’elle contient une liste du module normal’résultat’ par élément.
  • skipped (évité) : Un booléen qui indique si la tâche a été ignorée ou non.
  • stderr : Certains modules exécutent des utilitaires en ligne de commande ou sont conçus pour exécuter des commandes directement (modules raw, shell, command, etc.), ce champ contient la sortie d’erreur de ces utilitaires.
  • stderr_lines : Lorsque stderr est retourné, nous fournissons aussi toujours ce champ qui est une liste de chaînes de caractères, un élément par ligne de l’original.
  • stdout : Certains modules exécutent des utilitaires en ligne de commande ou sont conçus pour exécuter directement des commandes (modules raw, shell, command, etc). Cette zone contient l’édition normale de ces utilitaires.
  • stdout_lines : Lorsque stdout est retourné, Ansible fournit toujours une liste de chaînes de caractères, chacune contenant un élément par ligne de la sortie originale.

5. Module Linux

5.1. Paquets logiciels et repos

  • dnf – Manages packages with the dnf package manager
  • package – Generic OS package manager
  • package_facts – package information as facts
  • pip – Manages Python library dependencies
  • rpm_key – Adds or removes a gpg key from the rpm db
  • yum – Manages packages with the yum package manager
  • yum_repository – Add or remove YUM repositories
  • alternatives – Manages alternative programs for common commands
  • apt_rpm – apt_rpm package manager
  • urpmi – Urpmi manager

5.2. Services

5.3. Règles de pare-feu

  • iptables – Modify iptables rules
  • firewalld – Manage arbitrary ports/services with firewalld
  • iptables_state – Save iptables state into a file or restore it from a file

5.4. Systèmes de fichiers

  • fetch – Fetch files from remote nodes
  • file – Manage files and file properties
  • find – Return a list of files based on specific criteria
  • stat – Retrieve file or file system status
  • acl – Set and retrieve file ACL information.
  • xattr – Manage user defined extended attributes
  • get_url – Downloads files from HTTP, HTTPS, or FTP to node
  • git – Deploy software (or files) from git checkouts
  • subversion – Deploys a subversion repository
  • slurp – Slurps a file from remote nodes
  • uri – Interacts with webservices
  • synchronize – A wrapper around rsync to make common tasks in your playbooks quick and easy

5.5. Périphériques de stockage

  • mount – Control active and configured mount points
  • crypttab – Encrypted Linux block devices
  • luks_device – Manage encrypted (LUKS) devices
  • filesystem – Makes a filesystem
  • iso_create – Generate ISO file with specified files or folders
  • iso_extract – Extract files from an ISO image
  • lvg – Configure LVM volume groups
  • lvol – Configure LVM logical volumes
  • open_iscsi – Manage iSCSI targets with Open-iSCSI
  • parted – Configure block device partitions

5.6. Contenus de fichiers

  • assemble – Assemble configuration files from fragments
  • blockinfile – Insert/update/remove a text block surrounded by marker lines
  • lineinfile – Manage lines in text files
  • replace – Replace all instances of a particular string in a file using a back-referenced regular expression
  • copy – Copy files to remote locations
  • tempfile – Creates temporary files and directories
  • template – Template a file out to a remote server
  • patch – Apply patch files using the GNU patch tool

5.7. Archives

  • archive – Creates a compressed archive of one or more files or trees
  • unarchive – Unpacks an archive after (optionally) copying it from the local machine.

5.8. Tâches planifiées

  • cron – Manage cron.d and crontab entries
  • at – Schedule the execution of a command or script file via the at command
  • cronvar – Manage variables in crontabs

5.9. SSH

5.10. SELINUX

  • seboolean – Toggles SELinux booleans
  • selinux – Change policy and state of SELinux
  • sefcontext – Manages SELinux file context mapping definitions
  • selinux_permissive – Change permissive domain in SELinux policy
  • selogin – Manages linux user to SELinux user mapping
  • seport – Manages SELinux network port type definitions

5.11. Utilisateurs et groupes

  • user – Manage user accounts
  • group – Add or remove groups
  • pam_limits – Modify Linux PAM limits
  • pamd – Manage PAM Modules

5.12. Administration divers

  • hostname – Manage hostname
  • ping – Try to connect to host, verify a usable python and return pong on success
  • reboot – Reboot a machine
  • shutdown – Shut down a machine
  • script – Runs a local script on a remote node after transferring it
  • sysctl – Manage entries in sysctl.conf.
  • locale_gen – Creates or removes locales

5.13. Commandes

  • command – Execute commands on targets
  • expect – Executes a command and responds to prompts.
  • raw – Executes a low-down and dirty command
  • shell – Execute shell commands on targets
  • pause – Pause playbook execution
  • wait_for – Waits for a condition before continuing
  • wait_for_connection – Waits until remote system is reachable/usable

5.14. Réseau

  • nmcli – Manage Networking
  • listen_ports_facts – Gather facts on processes listening on TCP and UDP ports.
  • nsupdate – Manage DNS records.
  • ipify_facts – Retrieve the public IP of your internet gateway
  • ipinfoio_facts – Retrieve IP geolocation facts of a host’s IP address

5.15. Informations

  • debug – Print statements during execution
  • gather_facts – Gathers facts about remote hosts
  • set_fact – Set host facts from a task
  • setup – Gathers facts about remote hosts
  • fail – Fail with custom message

5.16. Modules internes

  • add_host – Add a host (and alternatively a group) to the ansible-playbook in-memory inventory
  • assert – Asserts given expressions are true
  • async_status – Obtain status of asynchronous task
  • getent – A wrapper to the unix getent utility
  • group_by – Create Ansible groups based on facts
  • meta – Execute Ansible ‘actions’
  • set_stats – Set stats for the current ansible run

5.17. Include/Import

5.18. Autres Packagers et gestionnaires de dépendances

5.19. Docker Containers

5.20. LXC/LXD

5.21. LDAP

5.22. Web Servers

5.23. PostgreSQL

5.24. RHSM Red Hat software channels

  • redhat_subscription – Manage registration and subscriptions to RHSM using the subscription-manager command
  • rhn_channel – Adds or removes Red Hat software channels
  • rhn_register – Manage Red Hat Network registration using the rhnreg_ks command
  • rhsm_release – Set or Unset RHSM Release version
  • rhsm_repository – Manage RHSM repositories using the subscription-manager command

5.25. Fichiers ini, csv, xml

  • read_csv – Read a CSV file
  • git_config – Read and write git configuration
  • ini_file – Tweak settings in INI files
  • xml – Manage bits and pieces of XML files or strings

5.26. Gestion des processus et du noyau

  • capabilities – Manage Linux capabilities
  • modprobe – Load or unload kernel modules
  • pids – Retrieves process IDs list if the process is running otherwise return empty list

5.27. Surveillance

  • snmp_facts – Retrieve facts for a device using SNMP
  • syslogger – Log messages in the syslog
  • mail – Send an email

5.28. XFS / ZFS

5.29. Debian/Ubuntu

  • apt – Manages apt-packages
  • apt_key – Add or remove an apt key
  • apt_repository – Add and remove APT repositories
  • dpkg_selections – Dpkg package selection selections
  • debconf – Configure a .deb package
  • apt_repo – Manage APT repositories via apt-repo
  • apt_rpm – apt_rpm package manager
  • dpkg_divert – Override a debian package’s version of a file
  • interfaces_file – Tweak settings in /etc/network/interfaces files
  • ufw – Manage firewall with UFW

5.30. Crypto TLS

6. Modules Réseau

7. Modules Windows

8. Pratique des modules Ansible

9. Développement de modules

Laisser un commentaire