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.

Pourquoi linter dès le départ

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

# 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

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

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 :

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

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

À 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.

Prochaines étapes

Page complète ansible-lint Profils, configuration avancée, CI/CD, customisation des règles, tout ce qui dépasse l'onboarding

Premier playbook Le playbook sur lequel appliquer ansible-lint pour la première fois

Modules essentiels La cheat-sheet des 15 modules, utiliser ansible-lint pour valider leur usage

Debug premières erreurs Une fois ansible-lint passé, gérer les erreurs runtime restantes (Permission, MODULE FAILURE, YAML)