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
Comment procéder ?
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.
Résultat à atteindre : Squelette roles/adn_lab créé par ansible-galaxy.
Avant de commencer : Ansible et ansible-galaxy disponibles ; poste local de recette.
01 · CADRAGE
Ce que vous allez mettre en place
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.
Pour qui : 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.
Vérifiez la compatibilité avec votre environnement réel. Les versions ne sont jamais présumées identiques d’un tenant à l’autre.
02 · AVANT DE COMMENCER
Prérequis et points de contrôle
- 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.
03 · VUE D’ENSEMBLE
Comprendre l’architecture et les flux
04 · TUTORIEL
Procédure complète, étape par étape
Chaque étape explique l’action, sa raison, le contrôle attendu et les erreurs habituelles. Adaptez les exemples aux paramètres de votre propre 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 ADN : 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 ADN : 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 ADN : 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 ADN : 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 ADN : Ne pas utiliser une collection Galaxy non vérifiée en production ; pinner sa version et sa provenance.
SOURCES ET FIABILITÉ
Statut de validation du guide
Rédaction : ADN Consulting. Statut : procédure documentée, exécution en laboratoire non attestée.
Les exemples et versions indiqués doivent être vérifiés sur un environnement autorisé. Aucune validation individuelle par un consultant n’est revendiquée sans preuve.
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.
Le conseil de l’expert ADN
Avant de généraliser cette configuration, validez-la sur un périmètre représentatif, documentez les critères de réussite et conservez une procédure de retour arrière. Une automatisation fiable se juge sur l’état final observé, les permissions maîtrisées et un retour arrière testé.
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
Ce tutoriel s’inscrit dans une chaîne technique plus large. Retrouvez les méthodes associées aux technologies voisines.