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.
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
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
python3 --version
ansible --version
ansible-playbook --versionRé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
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.
É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.
- Créer un répertoire propre et son sous-dossier roles.
- Générer le rôle adn_lab à partir du CLI officiel.
- Inspecter l'arborescence plutôt que de supposer l'existence d'un fichier.
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À 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.
ÉTAPE 2 / 5
Renseigner les valeurs par défaut
defaults/main.yml stocke les valeurs faibles en précédence, surchargeables selon l'environnement.
- Créer le contenu de roles/adn_lab/defaults/main.yml.
- Choisir un message non sensible et identifiable.
- Ne pas y placer de secret réel.
cat > roles/adn_lab/defaults/main.yml <<'EOF'
---
adn_lab_message: "Rôle ADN de recette"
EOFÀ 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.
ÉTAPE 3 / 5
Ajouter une tâche native
tasks/main.yml doit contenir une liste de tâches, sans déclaration de play hosts.
- Créer roles/adn_lab/tasks/main.yml.
- Utiliser ansible.builtin.debug seulement en recette.
- Référencer la variable définie dans defaults/main.yml.
cat > roles/adn_lab/tasks/main.yml <<'EOF'
---
- name: Afficher le message du role
ansible.builtin.debug:
msg: "{{ adn_lab_message }}"
EOFÀ 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.
É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.
- Écrire site.yml à la racine du projet, hors du dossier roles.
- Déclarer hosts localhost et connection local.
- Charger adn_lab sous roles sans dupliquer sa logique.
cat > site.yml <<'EOF'
---
- name: Executer le role de recette
hosts: localhost
connection: local
gather_facts: false
roles:
- adn_lab
EOFÀ 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.
É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.
- Fixer ANSIBLE_ROLES_PATH sur ./roles pour la recette.
- Effectuer --syntax-check puis l'exécution.
- Confirmer l'affichage de Rôle ADN de recette, puis nettoyer le dossier si besoin.
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À 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.
05 · RECETTE
Comment vérifier que tout fonctionne ?
Squelette roles/adn_lab créé par ansible-galaxy.
defaults/main.yml, tasks/main.yml et site.yml ont un chemin explicite.
--syntax-check réussit et le rôle est résolu.
Le message est visible sans modification de l'hôte.
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
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