Créer son premier rôle Ansible : ansible-galaxy role init pas à pas

Ce guide vous fait écrire votre premier rôle Ansible from scratch avec le rôle fil rouge webserver qui sera enrichi au fil des prochains guides. Vous générez la structure avec ansible-galaxy role init, vous écrivez les tâches dans tasks/main.yml, vous appelez le rôle depuis un playbook, et vous validez avec un test pytest+testinfra.

À la fin, vous aurez un rôle fonctionnel et idempotent qui installe nginx, le démarre, et ouvre le firewall, tout ça en respectant la structure conventionnelle des rôles Ansible.

Pressé ? Le squelette d'un rôle minimal

# 1. Générer la structure conforme
mkdir -p roles && cd roles
ansible-galaxy role init webserver
cd ..

# 2. Éditer roles/webserver/defaults/main.yml (variables par défaut overridables)
cat > roles/webserver/defaults/main.yml <<'EOF'
---
webserver_package: nginx
webserver_port: 80
webserver_service: nginx
EOF

# 3. Éditer roles/webserver/tasks/main.yml (FQCN obligatoire)
cat > roles/webserver/tasks/main.yml <<'EOF'
---
- name: Installer le paquet
  ansible.builtin.dnf:
    name: "{{ webserver_package }}"
    state: present

- name: Démarrer et activer le service
  ansible.builtin.systemd_service:
    name: "{{ webserver_service }}"
    state: started
    enabled: true

- name: Ouvrir le port firewalld
  ansible.posix.firewalld:
    port: "{{ webserver_port }}/tcp"
    state: enabled
    permanent: true
    immediate: true
EOF

# 4. Consommer dans un playbook
# site.yml
- hosts: webservers
  become: true
  roles:
    - webserver

Sécurité non négociable :

• defaults/main.yml pour TOUTE variable customisable, niveau 1 (le plus faible), permet à l'utilisateur du rôle de la surcharger via group_vars/. Mettre dans vars/main.yml (niveau 19) = utilisateur ne peut PAS override = mauvais design.
• Préfixer toutes les variables par le nom du rôle (webserver_port, jamais port), sinon collision avec d'autres rôles.
• FQCN partout (ansible.builtin.dnf, ansible.posix.firewalld), c'est la norme RHCE 2026. ansible-lint --profile production plante sans FQCN.
• become: true au niveau du play qui consomme le rôle (pas dans le rôle lui-même), laisse l'utilisateur décider.

Ce que vous allez apprendre

• Générer la structure d'un rôle avec ansible-galaxy role init.
• Écrire tasks/main.yml avec 3 tâches FQCN idempotentes (dnf, systemd, firewalld).
• Définir des variables par défaut dans defaults/main.yml.
• Documenter le rôle via meta/main.yml + README.md.
• Appeler le rôle depuis un playbook avec roles:.
• Valider l'idempotence en relançant le playbook (résultat : changed=0).

Prérequis

• Avoir lu Structure standard d'un rôle.
• Lab fonctionnel avec web1.lab qui répond à ansible web1.lab -m ping.
• Collection ansible.posix installée (ansible-galaxy collection install ansible.posix).

Étape 1, Générer la structure

À la racine du projet, créer un dossier roles/ puis générer le rôle :

mkdir -p roles
ansible-galaxy role init roles/webserver

Sortie :

- Role roles/webserver was created successfully

Arborescence générée :

• Répertoireroles/

  • Répertoirewebserver/

    • Répertoiredefaults/

      • main.yml
    • Répertoirefiles/

      • …
    • Répertoirehandlers/

      • main.yml
    • Répertoiremeta/

      • main.yml
    • Répertoiretasks/

      • main.yml
    • Répertoiretemplates/

      • …
    • Répertoiretests/

      • …
    • Répertoirevars/

      • main.yml
    • README.md

8 dossiers + 2 fichiers racine. Les fichiers main.yml sont créés avec un squelette commenté, à vous de les remplir.

Étape 2, Écrire les tâches dans tasks/main.yml

Trois tâches simples : installer nginx, démarrer le service, ouvrir le firewall.

---
# tasks/main.yml — rôle webserver
- name: Installer nginx
  ansible.builtin.dnf:
    name: nginx
    state: present

- name: Démarrer et activer nginx
  ansible.builtin.systemd_service:
    name: nginx
    state: started
    enabled: true

- name: Ouvrir le service HTTP dans firewalld
  ansible.posix.firewalld:
    service: http
    permanent: true
    immediate: true
    state: enabled

3 modules, 3 FQCN distincts : ansible.builtin.dnf, ansible.builtin.systemd_service, ansible.posix.firewalld. Chacun est idempotent, re-exécuter le rôle ne change rien si l'état est déjà conforme.

firewalld n'est pas dans builtin

Le module firewalld vit dans la collection ansible.posix, pas dans ansible.builtin. Si la collection n'est pas installée, l'erreur sera : couldn't resolve module/action 'ansible.posix.firewalld'. Installer avec : ansible-galaxy collection install ansible.posix.

Étape 3, Définir les variables par défaut

defaults/main.yml contient les variables que l'utilisateur du rôle peut override. Convention : préfixer par le nom du rôle (webserver_).

defaults/main.yml

---
webserver_state: present
webserver_service_state: started
webserver_service_enabled: true

Variables non encore utilisées

Ces 3 variables ne sont pas encore utilisées dans tasks/main.yml, c'est volontaire. La page suivante variables defaults vs vars les branche correctement et explique la précédence.

Étape 4, Documenter le rôle (meta/main.yml)

Le fichier meta/main.yml est la carte d'identité du rôle pour Galaxy.

---
galaxy_info:
  author: Stéphane Robert
  namespace: stephrobert
  role_name: webserver
  description: Installer et configurer nginx
  license: MIT
  min_ansible_version: "2.16"
  platforms:
    - name: EL
      versions:
        - "9"
        - "10"
  galaxy_tags:
    - nginx
    - webserver

dependencies: []

Champs essentiels :

• role_name + namespace : identifiant Galaxy (stephrobert.webserver).
• min_ansible_version : version minimum d'Ansible.
• platforms : OS supportés, Galaxy filtre les recherches selon ces tags.
• dependencies : autres rôles à pré-installer (vide ici).

Étape 5, Ajouter des handlers

handlers/main.yml contient les actions réactives déclenchées par notify:.

handlers/main.yml

---
- name: Restart nginx
  ansible.builtin.systemd_service:
    name: nginx
    state: restarted

- name: Reload nginx
  ansible.builtin.systemd_service:
    name: nginx
    state: reloaded

Les handlers ne s'exécutent pas tout seuls, il faut une tâche qui les notifie via notify: "Restart nginx". C'est le sujet du guide handlers-meta.

Étape 6, Écrire le playbook qui consomme le rôle

À la racine du projet (au-dessus de roles/), créer playbook.yml :

---
- name: Déployer le rôle webserver
  hosts: web1.lab
  become: true

  roles:
    - role: webserver

Pas de tasks: dans le playbook, toutes les tâches viennent du rôle. Pattern recommandé : playbooks fins, rôles épais.

Étape 7, Exécuter le playbook

ansible-playbook playbook.yml

Sortie attendue :

PLAY [Déployer le rôle webserver] *********************************

TASK [Gathering Facts] *****************************************
ok: [web1.lab]

TASK [webserver : Installer nginx] *****************************
changed: [web1.lab]

TASK [webserver : Démarrer et activer nginx] *******************
changed: [web1.lab]

TASK [webserver : Ouvrir le service HTTP dans firewalld] *******
changed: [web1.lab]

PLAY RECAP *****************************************************
web1.lab : ok=4 changed=3 unreachable=0 failed=0

Notez le préfixe webserver : sur chaque tâche, Ansible identifie clairement le rôle exécutant. Très utile pour debugger un play multi-rôles.

Étape 8, Vérifier l'idempotence

Re-lancer immédiatement le playbook :

ansible-playbook playbook.yml

Sortie attendue : changed=0. Tous les modules sont idempotents, l'état désiré est déjà atteint, rien à faire. C'est la propriété fondamentale d'un bon rôle Ansible : convergence vers un état, pas exécution aveugle.

Étape 9, Tester nginx

curl http://web1.lab/

Vous devriez voir la page d'accueil par défaut de nginx (« Welcome to nginx »).

Pratiquer dans le lab

Cette page a un lab d'accompagnement complet : labs/roles/creer-premier-role/ dans stephrobert/ansible-training.

Le lab fournit le rôle webserver pré-écrit + un challenge : créer un second rôle httpd-server pour Apache et le déployer sur db1.lab. Tests automatisés via pytest+testinfra (5 tests).

cd ~/Projets/ansible-training/labs/roles/creer-premier-role/

cat README.md                                    # tuto pas à pas
ansible-playbook playbook.yml                    # déployer webserver sur web1
cat challenge/README.md                          # consigne du challenge
pytest -v challenge/tests/                       # valider le challenge

Pièges courants

Symptôme	Cause	Fix
couldn't resolve module/action 'firewalld'	Collection ansible.posix non installée	ansible-galaxy collection install ansible.posix
Cannot find role 'webserver'	Rôle pas dans roles_path	Vérifier ansible.cfg ou utiliser un path relatif explicite
firewalld is not running	Service firewalld arrêté sur la cible	sudo systemctl enable --now firewalld puis relancer
changed=true à chaque run	Une tâche n'est pas idempotente	Vérifier que tous les modules ont un state: ou creates:
Curl renvoie « Connection refused »	Port 80 pas ouvert	Vérifier firewall-cmd --list-services sur la cible

Glissez pour voir

À retenir

• ansible-galaxy role init <nom> = générer la structure standard automatiquement.
• tasks/main.yml = point d'entrée, exécuté quand le rôle est appelé.
• FQCN partout : ansible.builtin.dnf, ansible.posix.firewalld. Mandatory en 2026.
• Préfixer les variables avec le nom du rôle (webserver_state).
• meta/main.yml = carte d'identité Galaxy. dependencies: = autres rôles requis.
• Idempotence : re-jouer le playbook = changed=0 si l'état est déjà conforme.
• Pattern recommandé : playbooks/ fins + roles/ épais.

Prochaines étapes

Variables : defaults vs vars Brancher les variables aux tâches, comprendre la précédence (8 niveaux dans un rôle)

Handlers et meta Connecter les handlers aux tâches via notify:, enrichir meta/main.yml

argument_specs.yml Validation automatique des variables d'entrée, recommandé 2026

TDD avec Molecule Adopter le développement piloté par les tests dès le rôle suivant

×

📖 Voir la documentation →