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) :

WARNING: PRE RUN: Profile 'production' is selected which has 41 rules.
WARNING: Listing 5 violation(s) that are fatal

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

fqcn[action-core]: Use FQCN for builtin module actions (dnf).
premier-playbook.yml:6 Task/Handler: dnf

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

yaml[indentation]: Wrong indentation: expected 4 but found 2.
premier-playbook.yml:8

risky-file-permissions: File permissions unset or incorrect.
premier-playbook.yml:11 Task/Handler: copy

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

3 niveaux de sévérité : fatal (rouge — corriger absolument), warning (jaune), notice (gris).

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: v25.0.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 41 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)