Ansible — Rôles avancés, collections et Ansible Galaxy

ℹ️ À savoir · En bref

Un rôle regroupe tout ce qu'il faut pour une fonction (installer un VDA, configurer StoreFront). Une collection est le format de distribution moderne : elle embarque des rôles, des modules, des plugins et des playbooks, versionnés ensemble sous un nom namespace.collection.

Objectif : passer de playbooks copiés-collés à une bibliothèque interne versionnée et testée, installée partout de la même façon.

Objectifs de la fiche

Écrire des rôles robustes : contrat d'entrée validé, valeurs par défaut, handlers.
Choisir entre import_role et include_role.
Créer, construire et publier une collection.
Installer ses dépendances de façon reproductible et tester ses rôles.

Un rôle bien conçu

Élément	Bonne pratique
`defaults/main.yml`	Toutes les variables que l'utilisateur peut changer, préfixées par le nom du rôle (`vda_version`, `vda_controllers`)
`vars/main.yml`	Constantes internes uniquement (chemins, noms de paquets par OS)
`meta/argument_specs.yml`	Contrat d'entrée : types, valeurs autorisées, variables obligatoires — validé automatiquement avant le rôle
`tasks/main.yml`	Court : il inclut des fichiers par étape (`install.yml`, `configure.yml`)
`handlers/main.yml`	Redémarrages de services ; `listen` pour qu'un même événement déclenche plusieurs handlers
`meta/main.yml`	Plateformes supportées et dépendances (à limiter)
`README.md`	Variables, exemple d'appel, prérequis

contrat d'entrée

# roles/citrix_vda/meta/argument_specs.yml
argument_specs:
  main:
    short_description: Installe le VDA Citrix sur Windows
    options:
      vda_version:
        type: str
        required: true
        description: Version de l'installeur, ex. "2507"
      vda_controllers:
        type: list
        elements: str
        required: true
      vda_mode:
        type: str
        choices: [masterimage, persistent]
        default: masterimage

💡 Astuce

Avec argument_specs, une variable manquante ou mal typée arrête le play avant la première tâche, avec un message clair. C'est la documentation et le garde-fou du rôle en un seul fichier.

import_role ou include_role ?

	import_role / roles:	include_role
Moment	Statique : résolu au chargement du playbook	Dynamique : résolu à l'exécution
Conditions `when`	Appliquées à chaque tâche du rôle	Appliquées une fois à l'inclusion
Boucles	Impossible	Possible (`loop`)
Tags	Hérités par les tâches, visibles dans `--list-tasks`	Il faut `apply: { tags: … }` pour les propager
Usage typique	Rôles toujours exécutés	Rôle choisi selon une variable, ou répété

Les collections

Structure d'une collection : métadonnées, rôles, plugins et playbooks

galaxy.yml

# galaxy.yml
namespace: contoso
name: citrix
version: 1.2.0
readme: README.md
authors: [Alice <alice@contoso.com>]
description: Rôles et modules pour Citrix CVAD / DaaS
dependencies:
  ansible.windows: ">=2.0.0"
  microsoft.ad: ">=1.0.0"
repository: https://git.contoso.com/infra/contoso.citrix

On appelle tout par son FQCN : contoso.citrix.vda_windows pour un rôle, contoso.citrix.mon_module pour un module.
meta/runtime.yml déclare la version minimale d'ansible-core (requires_ansible) et les redirections de modules renommés.
Les collections s'installent dans collections/ansible_collections/ (chemin réglable par collections_path dans ansible.cfg).

Construire, publier, consommer

Du développement à l'installation : Galaxy, Automation Hub privé ou simple dépôt Git

requirements.yml

# collections/requirements.yml
collections:
  - name: ansible.windows
    version: ">=2.5.0,<3.0.0"
  - name: microsoft.ad
    version: "1.9.0"
  - name: https://git.contoso.com/infra/contoso.citrix.git
    type: git
    version: v1.2.0              # tag, branche ou commit

roles:
  - name: geerlingguy.docker     # rôle « standalone » depuis Galaxy
    version: "7.4.1"

Commande	À quoi ça sert
`ansible-galaxy collection init contoso.citrix`	Créer le squelette d'une collection
`ansible-galaxy role init roles/storefront`	Créer le squelette d'un rôle
`ansible-galaxy collection build`	Produire l'archive contoso-citrix-1.2.0.tar.gz
`ansible-galaxy collection publish *.tar.gz --server hub`	Publier sur Galaxy ou sur un Automation Hub privé
`ansible-galaxy install -r requirements.yml`	Installer rôles et collections listés
`ansible-galaxy collection list`	Voir les collections installées et leurs versions

⚠️ Piège

Sans version figée dans requirements.yml, deux personnes (ou la CI et AWX) n'exécutent pas le même code. Fixe les versions, comme le lock file en Terraform.

Tester ses rôles

Outil	Ce qu'il vérifie
`ansible-lint`	Bonnes pratiques : FQCN, idempotence, noms de tâches, modules dépréciés ; profils de sévérité (`production`)
`Molecule`	Cycle complet sur une machine jetable : create → converge → idempotence → verify → destroy
`ansible-test`	Tests de collection : sanity (qualité du code), unit et integration pour les modules
`--check --diff`	Simulation sur un environnement réel avant exécution

Molecule

molecule init scenario default   # driver docker/podman via le paquet molecule-plugins
molecule test        # crée, applique, rejoue (idempotence), vérifie, détruit
molecule converge    # applique seulement (boucle de développement rapide)
molecule login       # se connecter à l'instance de test

ℹ️ À savoir

Pour des rôles Windows (VDA, StoreFront), Molecule passe par le driver delegated avec une VM de test (Azure, vSphere) créée et détruite par le scénario, car les conteneurs Windows ne conviennent pas.

Pièges classiques

Symptôme	Cause	Parade
Un rôle s'exécute deux fois	Dépendance déclarée dans meta + appel explicite	Limiter les dépendances meta ; `allow_duplicates: false` par défaut
Variable du rôle ignorée	Définie dans `vars/` (priorité haute) au lieu de `defaults/`	Variables réglables dans `defaults/`
Tags sans effet sur include_role	Les tags ne se propagent pas aux tâches incluses	`apply: { tags: [...] }` ou `import_role`
Module introuvable dans AWX	Collection absente de l'environnement d'exécution	`requirements.yml` dans le projet ou EE personnalisé (ANS-04)
Collisions de noms de variables	Variables non préfixées partagées entre rôles	Préfixer par le nom du rôle

🔷 En contexte Citrix

Une collection contoso.citrix regrouperait tes rôles vda_windows, vda_linux, storefront, cloud_connector_prereqs et seal_image (ANS-03), avec un playbook build_image.yml prêt à l'emploi.

Versionnée et taguée, elle devient livrable chez tes clients : mêmes rôles, seules les variables (group_vars) changent d'un environnement à l'autre.

À retenir

Variables réglables dans defaults/, contrat dans meta/argument_specs.yml.
import_role statique, include_role dynamique (boucles, conditions à l'exécution).
Collection = rôles + modules + plugins versionnés, appelés par FQCN.
requirements.yml avec versions figées, pour la CI comme pour AWX.
Molecule pour tester l'idempotence, ansible-lint pour la qualité.

Auto-évaluation

Q1. Où placer une variable que l'utilisateur du rôle doit pouvoir modifier ?

→ Dans defaults/main.yml (priorité la plus basse), idéalement documentée dans meta/argument_specs.yml.

Q2. Tu veux appliquer un rôle pour chaque élément d'une liste. import_role ou include_role ?

→ include_role : seul l'appel dynamique accepte loop.

Q3. Comment installer une collection interne hébergée sur Git à une version précise ?

→ Dans requirements.yml : name: <url>.git, type: git, version: v1.2.0, puis ansible-galaxy install -r requirements.yml.

Q4. Que vérifie la séquence molecule test en plus de l'exécution du rôle ?

→ L'idempotence (second passage sans changement) et les vérifications du scénario, sur une instance détruite à la fin.

Objectifs de la fiche#

Un rôle bien conçu#

import_role ou include_role ?#

Les collections#

Construire, publier, consommer#

Tester ses rôles#

Pièges classiques#

À retenir#

Auto-évaluation#

Pour aller plus loin#

Objectifs de la fiche

Un rôle bien conçu

import_role ou include_role ?

Les collections

Construire, publier, consommer

Tester ses rôles

Pièges classiques

À retenir

Auto-évaluation

Pour aller plus loin