Ecrire correctement des roles Ansible
Mise à jour :
Dans le monde de l’automatisation IT, Ansible se distingue par sa simplicité et sa puissance, permettant une gestion de configurations et un déploiement d’applications efficaces et sans heurts. À travers mon parcours en tant que professionnel DevOps, j’ai adopté Ansible pour sa facilité d’intégration dans divers environnements et sa capacité à simplifier des tâches complexes avec des playbooks clairs et concis. Ce guide vise à partager mon expérience dans l’écriture de rôles Ansible, des blocs essentiels pour réutiliser et organiser le code Ansible. Je vous guiderai à travers les étapes de création, de test, et d’optimisation de rôles, en mettant l’accent sur les meilleures pratiques et en fournissant des exemples concrets pour vous aider à maîtriser cet outil incontournable.
La structure des répertoires de rôles Ansible
La structure d’un rôle Ansible est un élément clé pour organiser et
réutiliser le code d’automatisation. Un rôle est divisé en plusieurs dossiers,
chacun ayant un objectif spécifique. Les dossiers tasks contiennent les tâches
principales à exécuter, handlers sont utilisés pour les tâches qui ne
s’exécutent qu’en réponse à un changement, defaults et vars définissent les
variables avec des valeurs par défaut et spécifiques au rôle, files et
templates pour les fichiers statiques et les templates
jinja et enfin, meta pour
décrire le rôle.
Plutôt que de créer la structure d’un role Ansible manuellement, je vous
conseille d’utiliser ansible-galaxy :
ansible-galaxy role init stephrobert.usersVérifions la structure créée :
Répertoiredefaults
- main.yml
Répertoirefiles/
- …
Répertoirehandlers
- main.yml
Répertoiremeta
- main.yml
Répertoiretasks
- main.yml
Répertoiretemplates/
- …
Répertoiretests
- inventory
- test.yml
Répertoirevars
- main.yml
- README.md
Le fichier README.md est la documentation du rôle. Il doit indiquer comment
installer et utiliser celui-ci. Il doit également décrire toutes les variables
permettant de le configurer. Afin de vous simplifier cette tâche, j’ai écrit un
outil répondant au nom de
ansible-gendoc.
Avant toute chose, il faut renseigner le fichier meta/main.yml qui contient
toutes les informations nécessaires à l’enregistrement de votre rôle dans un
serveur ansible galaxy :
---galaxy_info: author: Stephane ROBERT role_name: users namespace: stephrobert description: Create new users company: none license: MLP2 min_ansible_version: "2.11" platforms: - name: Debian versions: - bullseye - bookworm - name: Ubuntu versions: - jammy galaxy_tags: - usersdependencies: []Les champs les plus importants à renseigner :
- role_name : le nom du role
- namespace: le nom de l’espace déclaré dans ansible galaxy.
- dependencies : des roles et/ou des collections indispensables au fonctionnement du rôle
Utilisation du TDD pour coder notre rôle
L’adoption du Test-Driven Development (TDD) pour le développement de rôles Ansible améliore significativement la qualité et la fiabilité du code. TDD implique d’écrire des tests avant même de développer les fonctionnalités. Dans le contexte d’Ansible, cela signifie utiliser des outils comme Molecule pour créer un environnement de test où l’on définit les comportements attendus de nos rôles. On écrit d’abord des tests qui échouent, puis on développe le rôle jusqu’à ce que ces tests passent. Cette approche encourage une conception plus réfléchie et permet d’identifier rapidement les régressions.
Installation et Configuration de molecule
Commençons par installer molecule :
pip install molecule==5.0.1 --userpip install molecule-plugins --userVotre premier scenario molecule
Molecule utilise ce qu’on appelle des scénarios. Les scénarios Molecule sont des configurations définies par l’utilisateur pour tester les rôles Ansible. Ils spécifient comment Molecule doit créer l’environnement de test, exécuter les tests et valider le comportement du rôle. Chaque scénario peut avoir des environnements de test différents, permettant de tester le rôle dans diverses conditions et configurations. Le scenario par défaut s’appelle default. Pour le créer, utilisez cette commande :
molecule init scenario --verifier-name ansible --driver-name vagrant
INFO Initializing new scenario default...INFO Initialized scenario in /home/bob/Projects/perso/stephrobert.users/molecule/default successfully.Les drivers existants :
- azure :
- containers :
- delegated :
- docker :
- ec2 :
- gce :
- podman :
- vagrant :
Dans mon cas, je vais utiliser le plugin vagrant.
Configuration du scenario molecule
Le paramétrage se trouve dans le fichier molecule/default/molecule.yml. Le
sous-dossier default se trouvant dans le répertoire molecule est le dossier
du scenario par défaut. On peut créer d’autres scenarios, pour cela, il faudra
utiliser la même commande indiquée ci-dessus en ajoutant en argument le nom de
celui-ci.
Détaillons le contenu du fichier de configuration molecule.yml :
---dependency: name: galaxydriver: name: vagrantplatforms: - name: instance box: generic/ubuntu2204 memory: 512 cpus: 1provisioner: name: ansibleverifier: name: ansiblelint: | yaml-lintTout est documenté ici ↗, mais voyons ensemble chacun des paramètres :
- dependency : Molecule utilise le repository ansible-galaxy par défaut pour installer les dépendances de rôle.
- driver : Molecule utilise un driver, docker par défaut, pour déléguer la tâche de création d’instances.
- platforms : Permet d’indiquer à Molecule quelles instances de linux sont à
créer. Pour le driver docker, il faut donner le nom de l’image à utiliser. Le
pre_build_imagepermet de customiser une image en soit un fichier portant le<nom_de_la-plateforme>.dockerfilesoit le fichierDokerfile.j2se trouvant dans le dossiertemplate. - provisioner : On indique à Molecule que le provisioner est Ansible.
- verifier : Molecule utilise Ansible par défaut pour lancer des tests de vérification d’état sur les instances.
- test : Lance toutes les séquences de la création à la destruction.
Description du fonctionnement de molecule
Un peu ardu à expliquer ! La CLI de Molecule utilise des sous-commandes pour lancer des séquences (paramétrables). Voici la liste des principales sous-commandes :
- dependency : installe les dépendances ansible-galaxy nécessaires à l’exécution du rôle.
- create : création de l’instance avec le driver indiqué. Le rôle ne sera pas exécuté.
- prepare : exécution du playbook
prepare.ymlsur l’instance (installation des prérequis) - converge : exécution du playbook
playbook.ymlsur la l’instance (exécution du rôle lui-même) - verify : exécution du playbook
verify.ymlsur l’instance (tests unitaires) - destroy : destruction de l’environnement et de la VM
Les autres sont : check, cleanup, idempotence, side-effect,
syntax.
C’est là où ça se complique. Chaque sous-commande lance en fait des séquences de
sous-commandes. Pour en connaitre la composition, il faut utiliser la commande
molecule matrix <sous-commandes> :
molecule matrix converge
INFO Test matrix---default: - dependency - create - prepare - convergeOn voit donc que la sous-commande converge lance dans l’ordre indiqué
dependency, puis create et ainsi de suite.
Paramétrage du scenario
Par défaut lors de l’initialisation, il y a un paramètre qui n’est pas mis dans la configuration, mais qui permet de décrire le scenario qui sera utilisé : scenario.
Molecule s’appuie sur cette configuration pour contrôler la composition et l’ordre des séquences du scénario. Plus d’infos ici ↗
Vous pouvez modifier les séquences par défaut. Par exemple pour ne pas lancer
prepare dans lors de la création de l’instance :
scenario: create_sequence: - dependency - createVérifions avec la sous-commande matrix :
molecule matrix create
INFO Test matrix---default: - dependency - createPassons à la pratique
Maintenant commençons à coder notre rôle. Ce rôle créé des users, donc users
est une variable et comme il doit pouvoir être modifié lors de l’appel de votre
rôle dans un de vos playbooks, nous le plaçons dans defaults/main.yml. Ce qui
donne :
---# defaults file for monroleusers: []Vous avez remarqué, j’utilise une liste, car oui notre rôle doit pouvoir créer plusieurs utilisateurs. Par défaut cette liste est vide.
Que dois-je faire maintenant ? Écrire un test, vérifier qu’il échoue et ensuite écrire le code permettant de résoudre cet échec. Notre premier test est : l’utilisateur existe-t-il sur notre serveur ?
Éditons le fichier molecule/default/verify.yml dont voici son contenu par
défaut :
- name: Verify hosts: all gather_facts: false tasks: - name: Example assertion ansible.builtin.assert: that: truePour éviter de définir la variable dans les valeurs par défauts du rôle, j’inclus un fichier de variables :
users: - bobMais comment écrire ce test avec Ansible ? Eh bien, comme on le ferait
normalement sauf que l’on va indiquer que la tache échoue également si son
status est changed en plus de celui de failed.
- name: Verify hosts: all gather_facts: false tasks: # - name: Example assertion # ansible.builtin.assert: # that: true - name: Load vars ansible.builtin.include_vars: file: vars.yml - name: User exist ansible.builtin.user: name: "{{ item }}" state: present with_items: "{{ users }}" check_mode: true register: user failed_when: user is changed or user is failedPour éviter que le test ne change quoi que ce soit nous utilisons le mode
dry_run avec check_mode à true.
Mais on doit indiquer notre liste d’utilisateurs quelque part non ? Oui dans le
fichier molecule/default/converge.yml car c’est le playbook qui est exécuté et
qui appel votre rôle par molecule :
---- name: Converge hosts: all vars: users: - bob tasks: - name: Load vars ansible.builtin.include_vars: file: vars.yml - name: "Include stephrobert.users" ansible.builtin.include_role: name: "stephrobert.users"Vous voyez l’intérêt de molecule ! On peut tester son rôle et ce même dans un pipeline CI/CD. Tout se passe dans une instance vagrant (ici).
On lance le test :
molecule converge # On créé l'instance et on lance le role....
molecule verifyTASK [User exist] **************************************************************failed: [instance] (item=bob) => {"ansible_facts": {"discovered_interpreter_python": "/usr/bin/python3"}, "ansible_loop_var": "item", "changed": true, "failed_when_result": true, "item": "bob"}
PLAY RECAP *********************************************************************instance : ok=1 changed=0 unreachable=0 failed=1 skipped=0 rescued=0 ignored=0
WARNING Retrying execution failure 2 of: ansible-playbook --inventory /home/bob/.cache/molecule/stephrobert.users/default/inventory --skip-tags molecule-notest,notest /home/bob/Projects/perso/stephrobert.users/molecule/default/verify.ymlCRITICAL Ansible return code was 2, command was: ['ansible-playbook', '--inventory', '/home/bob/.cache/molecule/stephrobert.users/default/inventory', '--skip-tags', 'molecule-notest,notest', '/home/bob/Projects/perso/stephrobert.users/molecule/default/verify.yml']Notre test en bien sorti en échec. Maintenant, écrivons le code qui permet de résoudre cet échec.
On copie le code du test pour le mettre dans les taches du rôle. Sauf qu’on
retire la ligne failed_when et register. Ca se passe dans le fichier
tasks/main.yml :
---# tasks file for monrole- name: Create user ansible.builtin.user: name: "{{ item }}" state: present with_items: "{{ users }}"On relance :
molecule converge # On relance le role....
molecule verify
TASK [User exist] **************************************************************ok: [instance] => (item=bob)
PLAY RECAP *********************************************************************instance : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
INFO Verifier completed successfully.Vous avez compris le principe. Allez à présent, essayons de tester que
l’utilisateur a comme shell /bin/zsh. Il faut modifier la structure de
l’utilisateur :
users: - name: bob shell: /bin/zshComment contrôler avec ansible qu’user est configuré avec le shell zsh ? Tout
simplement dans le fichier /etc/passwd :
toto:x:1000:1000::/home/toto:/bin/zshNous allons donc utiliser le module lineinfile :
- name: Verify hosts: all gather_facts: false tasks: # - name: Example assertion # ansible.builtin.assert: # that: true - name: Load vars ansible.builtin.include_vars: file: vars.yml - name: User exist ansible.builtin.user: name: "{{ item.name }}" state: present with_items: "{{ users }}" check_mode: true register: user failed_when: user is changed or user is failed - name: Check shell ansible.builtin.lineinfile: path: "/etc/passwd" regexp: '^{{ item.name }}(.*){{ item.shell }}$' line: '{{ item.name }}\1{{ item.shell }}' state: present check_mode: true register: shell failed_when: (shell is changed) or (shell is failed) with_items: "{{ users }}"On relance le test:
molecule verify
TASK [Check shell] *************************************************************failed: [instance] (item={'name': 'bob', 'shell': '/bin/zsh'}) => {"ansible_loop_var": "item", "backup": "", "changed": true, "failed_when_result": true, "item": {"name": "bob", "shell": "/bin/zsh"}, "msg": "line added"}
PLAY RECAP *********************************************************************instance : ok=2 changed=0 unreachable=0 failed=1 skipped=0 rescued=0 ignored=0Il échoue bien. Maintenant corrigeons notre task user dans le fichier
tasks/main.yml:
---# tasks file for monrole- name: Create user become: true ansible.builtin.user: name: "{{ item.name }}" state: present shell: "{{ item.shell }}" with_items: "{{ users }}"On relance converge et verify et ça passe.
Je ne vais pas écrire tous les tests possibles, mais sachez que les modules les
plus utiles sont services_facts
pour charger l’état des services, le module
assert et les facts bien sûr (module setup).
Par contre, bonne nouvelle depuis la version 2.11 d’Ansible, nous ne sommes plus obligés de faire des tests sur les variables d’entrée. En effet, il existe un mécanisme automatique. Voyons cela maintenant.
Spécification d’arguments pour les rôles Ansible.
Pour activer ce mécanisme, il faut créer un fichier meta/argument_specs.yml
Dans ce fichier, nous allons indiquer pour chaque variable d’entrée de notre role
ce qui est attendu. C’est-à-dire le type, la valeur par défaut, sa description,
la liste des valeurs possibles…
Reprenons notre exemple ci-dessus. Notre variable d’entrée est une liste de dictionnaires requis :
---argument_specs: main: short_description: "Create Users on the servers." description: - Create an configure a list of users on the servers. author: Stephane ROBERT
options: users: type: list required: true description: - List of users elements: dict options: name: description: - The username type: str required: true shell: description: - The usr shell type: str default: /bin/bash choices: - /bin/bash - /bin/zshIci, nous décrivons les variables en entrée de la tache main.yml
Si nous lançons molecule converge nous allons voir une tache supplémentaire
apparaître :
TASK [stephrobert.users : Validating arguments against arg spec 'main' - Create Users on the servers.] ***ok: [instance]Cette tâche vérifie que les données en entrées sont celles attendues. Essayez de modifier les choix possibles de shell en retirant zsh et relancez :
TASK [stephrobert.users : Validating arguments against arg spec 'main' - Create Users on the servers.] ***fatal: [instance]: FAILED! => {"argument_errors": ["value of shell must be one of: /bin/bash, got: /bin/zsh found in users"], "argument_spec_data": {"users": {"description": ["List of users"], "elements": "dict", "options": {"name": {"description": ["The username"], "required": true, "type": "str"}, "shell": {"choices": ["/bin/bash"], "default": "/bin/bash", "description": ["The usr shell"], "type": "str"}}, "required": true, "type": "list"}}, "changed": false, "msg": "Validation of arguments failed:\nvalue of shell must be one of: /bin/bash, got: /bin/zsh found in users", "validate_args_context": {"argument_spec_name": "main", "name": "stephrobert.users", "path": "/home/bob/Projects/perso/stephrobert.users", "type": "role"}}Trop fort. N’est-ce pas ? Vous imaginez le nombre d’assert à taper pour valider cette structure, alors avec la structure du rôle nginx_config ↗ je ne vous raconte pas. Elle fait un millier de lignes.
Autre chose, grâce à ce système la documentation des rôles peut être obtenu avec
la commande ansible-doc.
ansible-doc --type role --list
sensu.sensu_go.agent configure Configure Sensu Go agentsensu.sensu_go.agent start Start Sensu Go agentsensu.sensu_go.agent main Install, configure, and start Sensu Go agentsensu.sensu_go.backend configure Configure Sensu Go backendsensu.sensu_go.backend start Start Sensu Go backendsensu.sensu_go.backend main Install, configure, and start Sensu Go backendsensu.sensu_go.install repositories Enable Sensu Go repossensu.sensu_go.install packages Install selected Sensu Go packagessensu.sensu_go.install main Enable Sensu Go repos and install selected packagesstephrobert.bootstrap main Bootsrap a machine for Ansible.stephrobert.users main Create Users on the servers.Si nous voulons afficher la documentation du fichier main de notre role :
ansible-doc --type role --entry-point main stephrobert.users
> STEPHROBERT.USERS (/home/bob/.ansible/roles/stephrobert.users)
ENTRY POINT: main - Create Users on the servers.
Create an configure a list of users on the servers.
OPTIONS (= is mandatory):
= users List of users elements: dict type: list
OPTIONS:
= name The username type: str
- shell The usr shell choices: [/bin/bash] default: /bin/bash type: str
AUTHOR: Stephane ROBERTCe n’est pas parfait, mais c’est un bon début non ? D’ailleurs ce mécanisme, je vais l’inclure dans mon outil de génération de documentation de rôles. Cela va permettre d’ajouter la description des variables, leur type, valeur par défaut…
Je ne vais pas documenter plus cette partie, car l’exemple que je vous ai écrit permet de construire des spécifications complexes de listes de dictionnaires. Tout est documenté ici ↗. Un exemple de spécifications ↗.
Quelques commandes molecule utiles
Vérifier l’état des scenarios
Molecule possède une commande permettant de vérifier l’état des scenarios :
molecule listWARNING Driver vagrant does not provide a schema.INFO Running default > list ╷ ╷ ╷ ╷ ╷ Instance Name │ Driver Name │ Provisioner Name │ Scenario Name │ Created │ Converged╶───────────────┼─────────────┼──────────────────┼───────────────┼─────────┼───────────╴ instance │ vagrant │ ansible │ default │ true │ trueIci on voit que l’instance de nom instance a été créé (created) et le role a
été appliqué (converged).
Contrôler l’idem potence de vos rôles
La commande idempotence doit être lancé sur une instance ou le rôle a été appliqué. En fait cette commande relance le rôle et vérifie que toutes les tâches ne modifie rien à nouveau :
TASK [Load vars] ***************************************************************ok: [instance]
TASK [Include stephrobert.users] ***********************************************
TASK [stephrobert.users : Validating arguments against arg spec 'main' - Create Users on the servers.] ***ok: [instance]
TASK [stephrobert.users : Create user] *****************************************ok: [instance] => (item={'name': 'bob', 'shell': '/bin/zsh'})
PLAY RECAP *********************************************************************instance : ok=4 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
INFO Idempotence completed successfully.Très pratique !
Publier vos rôles sur Ansible Galaxy
Ansible Galaxy est une registry où les développeurs de rôles, collections,
plugins, modules peuvent partager leurs productions. C’est dans cette base que la
commande ansible-galaxy va puiser lors de l’installation des rôles et
collections.
Avant de publier un rôle sur Ansible Galaxy, il est important de compléter les
informations du fichier meta/main.yml. C’est en sorte sa carte d’identité.
Le fichier meta/main.yml.
Voici le contenu minimal à fournir :
galaxy_info: author: Stephane ROBERT namespace: steph description: Mon premier role ansible company: steprobert license: MLP2 min_ansible_version: 2.11 platforms: - name: Debian versions: - 11 - name: Ubuntu versions: - 22.04 galaxy_tags: - user - systemdependencies: []Certains champs sont explicites, donc je vais me limiter à l’explication de :
- dependencies: Ce sont des dépendances d’autres rôles
- platforms: la liste des plateformes prises en charge par votre role. Elles
doivent correspondre à celles que vous avez déclarées dans vos tests
molecule. - galaxy_tags: la liste des mots clés qui permettront de retrouver votre rôle sur le site Ansible-Galaxy ↗.
La publication
Il est indispensable que le code source de votre rôle soit stocké dans un
repository github. Une fois déposé, il suffit de se rendre sur le site
Ansible-Galaxy ↗, de vous connecter avec votre
compte Github et d’autoriser ansible-galaxy à accéder à votre compte en lecture
seul. Ensuite aller dans la section [My content] et cliquer sur [Add Content].
Puis d’importer votre role avec le bouton [import Role from Github].
Utilisation de vos rôles dans vos playbooks
Il est possible d’intégrer vos rôles de 3 façons différentes :
- Le classique
rolesqui est prioritaire sur lestasksdu playbook :
---- hosts: webservers roles: - common - webservers tasks:Pour ordonner l’exécution des rôles, vous pouvez utiliser :
- Un appel dynamique de role :
include_role.
---- hosts: webservers tasks: - name: Print a message ansible.builtin.debug: msg: "this task runs before the example role"
- name: Include the example role ansible.builtin.include_role: name: example vars: dir: '/opt/a' app_port: 5000- Un appel statique de rôle :
import_role.
---- hosts: webservers tasks: - name: Print a message ansible.builtin.debug: msg: "this task runs before the example role" - name: Import the example role ansible.builtin.import_role: name: exampleLa différence entre les deux est que pour import_role le(s) role(s) sont
parsés au démarrage du playbook alors que pour include_role cela est fait
durant son exécution.
Quelques recommandations sur l’écriture des rôles
- Un rôle doit être limité à une tâche précise. Par exemple l’installation de votre serveur http.
- Un rôle doit pouvoir être exécuté de manière autonome.
- Même si on peut mettre des rôles en dépendances d’un autre rôle, éviter de faire des rôles, de rôles, de rôles. À déboguer c’est l’horreur.
- Tous les résultats de vos tâches de vos rôles doivent être testé.
- Pensez à décrire les variables dans le fichier
meta/argument_specs.yml. Gain ansible se charge de lancer lesassertscorrespondants. - Tous les packages et librairies que vous installez ou que vous utilisez dans
votre role doivent être versionné. Utilisez pour cela des variables. Exemple :
nginx_version: 1.18.0. - Éviter de créer un role
baseoucommondans lequel on retrouve un gros mélange de taches qui devraient être plutôt découpé en plusieurs rôles.