Aller au contenu

GUIDE TECHNIQUE · ANSIBLE

Structurer un projet avec les rôles Ansible

Créer un rôle Ansible complet avec ses vrais chemins defaults/main.yml et tasks/main.yml, l'appeler depuis site.yml et tester sa résolution via ANSIBLE_ROLES_PATH.

Niveau Intermédiaire4 min de lecture— vuesAnsible

L’ESSENTIEL EN BREF

Les étapes clés

Ce guide présente 5 étapes, de « Créer le squelette du rôle » à « Tester la syntaxe puis l'exécution ».

Avant de commencer : Ansible et ansible-galaxy disponibles ; poste local de recette.

01 · CADRAGE

Périmètre et résultat visé

Résultat attendu : Squelette roles/adn_lab créé par ansible-galaxy.

Public concerné : Administrateurs, ingénieurs DevOps, SRE et équipes de recette

Environnement et versions

ansible-core récent ; structure de rôle classique créée avec ansible-galaxy role init. Démonstration locale sans module nécessitant root.

02 · AVANT DE COMMENCER

Prérequis et points de contrôle

Un projet Ansible local et un inventaire testé ; les rôles seront créés dans le chemin indiqué par le guide.

  • Ansible et ansible-galaxy disponibles ; poste local de recette.
  • Droit d'écrire un répertoire roles et site.yml sous le dossier de travail.
  • Aucune collection externe ni identifiant secret requis.

Votre environnement de départ

Environnement
Un contrôleur Linux/macOS ou WSL avec Python 3 et ansible-core ; les exercices fournis utilisent d’abord localhost.
Outils
Bash, Python 3, Ansible CLI et éditeur.
Comptes et droits
Écriture dans le projet de recette ; aucune élévation nécessaire pour les fichiers sous le répertoire personnel. Les cibles SSH demandent des droits distincts.
Réseau et accès
Les exercices localhost ne demandent pas SSH. Une cible distante exige DNS, TCP 22, une identité SSH et Python supporté sur la cible.

Contrôles avant de commencer

Où effectuer le contrôle : Contrôleur Ansible

Commandes et configuration
python3 --version
ansible --version
ansible-playbook --version

Résultat attendu : Le binaire, la version Python et les chemins de configuration Ansible sont identifiés.

03 · VUE D’ENSEMBLE

Comprendre l’architecture et les flux

ARCHITECTURE TECHNIQUEComprendre la chaîne de bout en bout
01Inventaire
02Playbook
03Modules
04État cible
05Contrôle
Le plan de contrôle Ansible applique les modules depuis le poste de pilotage ; check, diff et seconde passe permettent d'évaluer les modifications.

04 · TUTORIEL

Procédure complète, étape par étape

Suivez les étapes dans l’ordre et contrôlez chaque résultat avant de poursuivre. Renseignez les paramètres adaptés à votre environnement.

01

ÉTAPE 1 / 5

Créer le squelette du rôle

Un rôle doit être trouvable par Ansible à partir d'un chemin connu ; le squelette standard prévient les chemins inventés.

  1. Créer un répertoire propre et son sous-dossier roles.
  2. Générer le rôle adn_lab à partir du CLI officiel.
  3. Inspecter l'arborescence plutôt que de supposer l'existence d'un fichier.
Commandes et configuration
mkdir -p ansible-roles-lab && cd ansible-roles-lab
mkdir -p roles
ansible-galaxy role init roles/adn_lab
find roles/adn_lab -maxdepth 2 -type f | sort
Ce qui se passe à cette étape
1Inventaire
2Créer le squelette du rôle
3Contrôle

À vérifier : roles/adn_lab/tasks/main.yml et roles/adn_lab/defaults/main.yml existent.

Point de vigilance : Si le rôle existe déjà, ne pas relancer role init sur des fichiers de travail non sauvegardés.

02

ÉTAPE 2 / 5

Renseigner les valeurs par défaut

defaults/main.yml stocke les valeurs faibles en précédence, surchargeables selon l'environnement.

  1. Créer le contenu de roles/adn_lab/defaults/main.yml.
  2. Choisir un message non sensible et identifiable.
  3. Ne pas y placer de secret réel.
Commandes et configuration
cat > roles/adn_lab/defaults/main.yml <<'EOF'
---
adn_lab_message: "Rôle ADN de recette"
EOF
Ce qui se passe à cette étape
1Playbook
2Renseigner les valeurs par défaut
3Contrôle

À vérifier : Le rôle possède une valeur par défaut adn_lab_message.

Point de vigilance : Les variables defaults ont une précédence faible ; les variables sensibles doivent être protégées hors de ce fichier.

03

ÉTAPE 3 / 5

Ajouter une tâche native

tasks/main.yml doit contenir une liste de tâches, sans déclaration de play hosts.

  1. Créer roles/adn_lab/tasks/main.yml.
  2. Utiliser ansible.builtin.debug seulement en recette.
  3. Référencer la variable définie dans defaults/main.yml.
Commandes et configuration
cat > roles/adn_lab/tasks/main.yml <<'EOF'
---
- name: Afficher le message du role
  ansible.builtin.debug:
    msg: "{{ adn_lab_message }}"
EOF
Ce qui se passe à cette étape
1Modules
2Ajouter une tâche native
3Contrôle

À vérifier : Une tâche valide existe dans tasks/main.yml et consomme la variable.

Point de vigilance : Si la tâche appelle un handler, définir celui-ci dans roles/adn_lab/handlers/main.yml.

04

ÉTAPE 4 / 5

Créer le playbook d'appel

Le playbook racine doit préciser le rôle, le contexte de connexion et le périmètre.

  1. Écrire site.yml à la racine du projet, hors du dossier roles.
  2. Déclarer hosts localhost et connection local.
  3. Charger adn_lab sous roles sans dupliquer sa logique.
Commandes et configuration
cat > site.yml <<'EOF'
---
- name: Executer le role de recette
  hosts: localhost
  connection: local
  gather_facts: false
  roles:
    - adn_lab
EOF
Ce qui se passe à cette étape
1État cible
2Créer le playbook d'appel
3Contrôle

À vérifier : Le fichier site.yml référence le rôle adn_lab.

Point de vigilance : Pour un parc, utiliser un inventaire explicite et review des rôles importés.

05

ÉTAPE 5 / 5

Tester la syntaxe puis l'exécution

La réussite dépend autant des chemins de rôle que de la syntaxe des YAML.

  1. Fixer ANSIBLE_ROLES_PATH sur ./roles pour la recette.
  2. Effectuer --syntax-check puis l'exécution.
  3. Confirmer l'affichage de Rôle ADN de recette, puis nettoyer le dossier si besoin.
Commandes et configuration
ANSIBLE_ROLES_PATH=./roles ansible-playbook -i localhost, -c local site.yml --syntax-check
ANSIBLE_ROLES_PATH=./roles ansible-playbook -i localhost, -c local site.yml
Ce qui se passe à cette étape
1Contrôle
2Tester la syntaxe puis l'exécution
3Contrôle

À vérifier : Le playbook s'exécute avec ok=1 et affiche le message défini dans defaults/main.yml.

Point de vigilance : Ne pas utiliser une collection Galaxy non vérifiée en production ; pinner sa version et sa provenance.

RÉFÉRENCES TECHNIQUES

Documentation officielle

Retrouvez les fonctionnalités, les paramètres et les matrices de compatibilité de Ansible.

Consulter la documentation officielle

05 · RECETTE

Comment vérifier que tout fonctionne ?

Résultat attenduContrôles avant de considérer la procédure terminée
01

Squelette roles/adn_lab créé par ansible-galaxy.

02

defaults/main.yml, tasks/main.yml et site.yml ont un chemin explicite.

03

--syntax-check réussit et le rôle est résolu.

04

Le message est visible sans modification de l'hôte.

05

Les précédences de variables sont décrites.

06 · DIAGNOSTIC

Problèmes fréquents et résolution

Échec de syntaxe

Cause probable : Format du fichier ou option incompatible

Que faire : Vérifier indentation YAML, version et documentation officielle.

Accès refusé

Cause probable : Droits ou contexte de connexion incorrects

Que faire : Contrôler l'utilisateur, le namespace et les permissions.

État non conforme

Cause probable : Configuration non appliquée ou ressource différente

Que faire : Relire les sorties détaillées, événements et paramètres effectifs.

07 · QUESTIONS PRATIQUES

Questions fréquentes

Où placer les paramètres par défaut ?

Dans roles/<nom_du_role>/defaults/main.yml. Ne confondez pas avec vars/main.yml, qui a une précédence plus forte.

Pourquoi rôle introuvable ?

Vérifiez le nom exact du rôle, le chemin roles/ et ANSIBLE_ROLES_PATH ou ansible.cfg.

AUTRES TECHNOLOGIES

Guides complémentaires

Tous les guides Ansible

VOTRE ENVIRONNEMENT

Besoin d’aller plus loin sur votre environnement ?

Automatisation, gouvernance et exploitation : identifions les priorités pour vos pratiques Ansible.

Découvrir notre accompagnement IT

Échanger avec ADN Consulting

Pour aller plus loin