ansible-lint dès le premier playbook : prendre le bon réflexe

Linter avant de débugger, c'est le réflexe qui transforme un débutant en praticien. ansible-lint détecte en secondes les erreurs prévisibles : oubli de FQCN, mode: non quoté, with_items legacy, command: sans changed_when, missing name:. Sans linter, vous découvrez ces problèmes au runtime sur 50 hôtes, bien plus douloureux.

Cette page vous fait passer de 0 à "linter activé" en 10 minutes. Pour creuser (profils, CI/CD, configuration avancée), allez sur la page complète ansible-lint.

Ce que vous allez apprendre

• Pourquoi linter dès le premier playbook (et pas plus tard).
• Installer ansible-lint en 1 commande.
• Lancer ansible-lint et lire la sortie (rule IDs, sévérités).
• Corriger automatiquement avec --fix.
• Top 5 règles que vous croiserez sur vos premiers playbooks.

Le réflexe à prendre

Avant chaque ansible-playbook foo.yml, faire ansible-lint foo.yml. Si le lint passe sans erreur, vous éliminez 80% des bugs prévisibles avant même de toucher au managed node. Sur la durée, c'est des heures de debug économisées.

Pourquoi linter dès le départ

Un playbook qui fonctionne n'est pas un playbook correct : il peut casser l'idempotence, employer une syntaxe dépréciée ou laisser fuir un secret dans une sortie. L'analyseur attrape ces défauts avant qu'ils n'atteignent une machine, et il coûte quelques secondes là où le diagnostic en production coûte une heure.

Trois bénéfices concrets :

• Erreurs catchées en local (sans utiliser SSH ni les managed nodes), feedback en quelques secondes.
• Conformité RHCE 2026, le linter applique les conventions modernes (FQCN obligatoire, loop: au lieu de with_*, etc.). En suivant ses recommandations, vous apprenez les bons réflexes.
• Lecture de code par d'autres, le code linté est homogène et plus facile à reviewer en équipe.

Inversement, ne pas linter mène à :

• Apprendre des anti-patterns sans s'en rendre compte (mode: 0644 non quoté, with_items: legacy).
• Découvrir des erreurs au runtime sur le managed node, moins lisible, plus long.
• Faire des review code chronophages où chaque convention doit être discutée à la main.

Installation

L'outil s'installe sur le poste de contrôle, jamais sur les machines administrées : il lit des fichiers, il n'exécute rien. Deux chemins existent selon la façon dont le reste de l'outillage a été installé, un environnement Python isolé ou le gestionnaire de paquets de la distribution.

# Via pip (recommandé, version la plus récente)
pip install --user ansible-lint

# Ou via dnf sur RHEL/AlmaLinux/Rocky
sudo dnf install ansible-lint

# Vérifier
ansible-lint --version

Premier run sur votre playbook

Sur le playbook que vous avez créé dans le premier playbook :

ansible-lint premier-playbook.yml

Sortie typique (sur un playbook débutant, ansible-lint 26) :

# Rule Violation Summary

  1 name                   profile:moderate  tags:idiom
  3 fqcn                   profile:moderate  tags:formatting
  1 no-changed-when        profile:moderate  tags:command-shell,idempotency
  1 risky-file-permissions profile:moderate  tags:unpredictability

Failed: 6 failure(s), 0 warning(s) in 1 files processed.
Last profile that met the validation criteria was 'basic'. Rating: 1/5 star

name[casing]: All names should start with an uppercase letter.
premier-playbook.yml:6 Task/Handler: install httpd

fqcn[action-core]: Use FQCN for builtin module actions (dnf).
premier-playbook.yml:7 Use `ansible.builtin.dnf` or `ansible.legacy.dnf` instead.

risky-file-permissions: File permissions unset or incorrect.
premier-playbook.yml:10 Task/Handler: Copier la page

no-changed-when: Commands should not change things if nothing needs doing.
premier-playbook.yml:14 Task/Handler: Verifier la version

Lire la sortie

Chaque ligne suit le format :

<rule-id>: <description courte>
<fichier>:<ligne> <contexte>

Élément	Rôle
rule-id	Identifiant unique (fqcn[action-core], name[casing]), utilisable pour --skip-list ou config
Description	Ce qui ne va pas, en 1 phrase
Fichier:ligne	Localisation précise dans votre playbook

Glissez pour voir

En tête, un récapitulatif (Rule Violation Summary) compte les violations par règle, suivi d'une note sur 5 étoiles (Rating) qui mesure la conformité au profil visé. Chaque violation est ensuite classée en failure (bloquante pour le profil) ou warning (informative).

Top 5 règles que vous croiserez

Rule ID	Cas typique	Fix
fqcn[action-core]	dnf: au lieu de ansible.builtin.dnf:	Préfixer avec ansible.builtin.
name[missing]	Tâche sans name:	Ajouter name: "Description claire"
name[casing]	name: "install httpd" (minuscule)	name: "Install httpd" (majuscule initiale)
risky-file-permissions	copy: sans mode:	Toujours préciser mode: "0644"
no-changed-when	command: sans changed_when:	Ajouter changed_when: false (lecture seule) ou expression

Glissez pour voir

Plus de détails par règle dans la page complète.

Auto-correction avec --fix

# Voir ce qui SERAIT modifie (dry-run)
ansible-lint --fix --dry-run premier-playbook.yml

# Appliquer pour de vrai
ansible-lint --fix premier-playbook.yml

Migrations automatiques courantes :

• with_items: / with_dict: / with_subelements: → loop: + filtres Jinja2.
• dnf: → ansible.builtin.dnf: (FQCN).
• name: foo → name: Foo (capitalisation).

À auditer après --fix :

• Cas où la migration with_* → loop: change la sémantique (rare mais possible).
• Cas où le linter ne sait pas combler une règle (vous devez le faire à la main).

Toujours committer avant --fix, vous pouvez vouloir revenir en arrière.

Configuration .ansible-lint

Pour skipper des règles dans un projet (rarement justifié, mais utile) :

# .ansible-lint a la racine du projet
profile: production   # production | shared | safety | basic | min

skip_list:
  - 'no-changed-when'   # Pour des labs ou les commands sont demonstratives

exclude_paths:
  - .cache/
  - tests/integration/

Profils :

• min, bare minimum (syntaxe valide).
• basic, quelques règles essentielles.
• safety, sécurité (no shell pipe, no risky perms).
• shared, pour rôles partagés.
• production, toutes les règles (défaut RHCE 2026).

Plus de détails dans la page complète, section profils.

Intégrer dans votre workflow

Trois options, du plus simple au plus automatisé :

En CLI manuel

# Avant chaque ansible-playbook
ansible-lint premier-playbook.yml && ansible-playbook premier-playbook.yml

Le && garantit que le playbook ne tourne pas si le lint a échoué.

Dans VS Code (extension)

Installer l'extension redhat.ansible : elle intègre ansible-lint au fil de la frappe. Erreurs visibles directement dans le code, sans même lancer ansible-lint en CLI.

En pre-commit hook

Bloquer les commits qui ne passent pas le lint :

.pre-commit-config.yaml

repos:
  - repo: https://github.com/ansible/ansible-lint
    rev: v26.6.0
    hooks:
      - id: ansible-lint

pre-commit install

Désormais chaque git commit lance ansible-lint automatiquement, un commit avec des erreurs lint est refusé.

Pièges typiques

Les règles qui remontent le plus souvent sur un premier playbook tiennent en quelques familles : tâches sans nom, qui rendent la sortie illisible, commandes brutes non gardées, qui cassent l'idempotence, et noms de modules courts là où la forme pleinement qualifiée est attendue. Aucune n'empêche le playbook de tourner, toutes le rendent plus difficile à maintenir.

Symptôme	Cause	Fix
Could not find Ansible config	ansible-lint cherche ansible.cfg ou roles/	Ignorer le warning, ou créer ansible.cfg minimal
Règle skip silencieusement	Règle dans skip_list: du .ansible-lint	Auditer le skip_list, chaque entrée mérite une justification
--fix casse l'idempotence	Migration with_subelements → loop: mal interprétée	Toujours tester après --fix, lire le diff
Profile trop strict	production impose toutes les règles	Démarrer avec profile: basic, monter progressivement

Glissez pour voir

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• Linter avant de débugger = réflexe n°1 du praticien Ansible.
• pip install --user ansible-lint suffit pour démarrer.
• ansible-lint <fichier>.yml = run, --fix = auto-correction.
• Top 5 règles : fqcn, name, risky-file-permissions, no-changed-when, yaml[indentation].
• VS Code + extension redhat.ansible = lint en temps réel.
• pre-commit hook = bloquer les commits non-lintés.

Pour aller plus loin

• Style guide : le référentiel de style que le linter applique, règle par règle.
• YAML pour Ansible : les avertissements yaml[...] remontés par le linter viennent tous de là.
• Structure d'un projet : un ansible.cfg et un layout standard font disparaître une partie des avertissements.

×

📖 Voir la documentation →