argument_specs.yml : validation automatique des variables d'un rôle Ansible

meta/argument_specs.yml est le contrat d’API d’un rôle Ansible. Il déclare le type, les choix possibles, la valeur par défaut, et la description de chaque variable d’entrée. Au runtime, Ansible valide automatiquement les valeurs passées au rôle — erreur claire si l’utilisateur fournit une string là où on attend un int, ou une valeur hors d’une liste de choix.

Disponible depuis Ansible 2.11, argument_specs.yml est devenu standard de fait en 2026 — ansible-lint --profile=production l’attend et ansible-doc --type role l’utilise pour générer la documentation. C’est l’une des meilleures pratiques 2026 à adopter dès vos premiers rôles.

Pressé ? Le squelette argument_specs.yml

roles/webserver/meta/argument_specs.yml

---
argument_specs:
  main:
    short_description: "Déploie nginx sur RHEL/AlmaLinux"
    description:
      - "Installe le paquet nginx, démarre le service et ouvre le port firewalld."
      - "Idempotent — peut être joué plusieurs fois sans effet de bord."
    options:
      webserver_package:
        description: "Nom du paquet nginx (rare cas où ce n'est pas 'nginx')"
        type: str
        default: nginx
        required: false

      webserver_port:
        description: "Port HTTP (1024-65535)"
        type: int
        default: 80
        required: false

      webserver_state:
        description: "État désiré du service"
        type: str
        choices: [started, stopped, restarted, reloaded]
        default: started

      webserver_admin_email:
        description: "Email de l'admin (pour ServerAdmin)"
        type: str
        required: true        # mandatory — fail si non fourni

      webserver_extra_modules:
        description: "Liste de modules nginx supplémentaires à installer"
        type: list
        elements: str
        default: []

Sécurité non négociable :

• required: true sur les variables sans valeur par défaut sensée — fail-fast si l’utilisateur oublie. Bien plus clair qu’un 'X' is undefined à la 5ᵉ tâche du rôle.
• choices: [...] sur les énumérations (state, env, log_level) — bloque les valeurs aberrantes au runtime.
• type: explicite (str, int, bool, list, dict) — Ansible convertit/valide automatiquement.
• elements: str sur les listes typées (type: list) — sinon une liste mixte passe sans erreur.
• description: mandatory pour chaque variable — ansible-doc --type role <role> la lit pour générer la doc.
• Mettre à jour argument_specs.yml dès qu’on ajoute/modifie/supprime une variable du rôle. Sans ça, l’API publique du rôle dérive et casse les utilisateurs.

Ce que vous allez apprendre

• Écrire meta/argument_specs.yml complet pour le rôle webserver.
• Valider les types (str, int, bool, list, dict).
• Imposer une liste de choix (choices: [...]).
• Marquer des variables comme required: true.
• Tester la validation : passage d’une valeur invalide → échec immédiat.
• Générer la documentation auto via ansible-doc --type role.

Prérequis

• Ansible 2.11+ (vérifier : ansible --version).
• Avoir suivi Variables defaults vs vars.

Le fichier meta/argument_specs.yml

meta/argument_specs.yml

---
argument_specs:
  main:                              # ← entrypoint principal du rôle (tasks/main.yml)
    short_description: "Installer et configurer nginx avec validation"
    description:
      - >
        Ce rôle installe nginx, le configure via un template, et ouvre le port
        HTTP. Toutes les variables d'entrée sont validées automatiquement
        avant l'exécution des tâches.
    author:
      - Stéphane Robert

    options:
      webserver_package:
        type: str
        default: nginx
        description: Nom du paquet à installer
        choices:
          - nginx

      webserver_state:
        type: str
        default: present
        description: État du paquet
        choices:
          - present
          - absent
          - latest

      webserver_listen_port:
        type: int
        default: 80
        description: Port d'écoute HTTP (1-65535)

      webserver_worker_processes:
        type: str
        default: auto
        description: |
          Nombre de worker_processes nginx. 'auto' = un par cœur CPU.
          Sinon une chaîne représentant un entier.

      webserver_worker_connections:
        type: int
        default: 1024
        description: "Connexions max par worker (typique : 1024-8192)"

      webserver_index_content:
        type: str
        required: false
        description: Contenu HTML de la page d'accueil

Anatomie ligne par ligne

main: — entrypoint

Le rôle peut exposer plusieurs entrypoints (tasks/main.yml, tasks/configure.yml, tasks/secure.yml). Chaque entrypoint a sa propre section dans argument_specs:. Le plus courant : main: qui valide les variables de tasks/main.yml.

short_description + description

Documentation lisible. Affichée dans ansible-doc --type role <role>. Obligatoire pour la qualité.

options.<var_name>: — la spec d’une variable

options:
  webserver_listen_port:
    type: int                  # ← type Python attendu
    default: 80                # ← valeur par défaut si absente
    description: "Port HTTP"   # ← documentation
    required: false            # ← obligatoire ou non
    choices: [80, 8080, 8443]  # ← liste de valeurs autorisées

Types supportés : str, int, float, bool, list, dict, path, raw.

Étape — Tester la validation

Cas 1 — Valeur valide

ansible-playbook playbook.yml -e "webserver_listen_port=8080"

Sortie : la tâche Validating arguments against arg spec 'main' apparaît, ok. Le play continue.

Cas 2 — Valeur invalide (hors choices)

ansible-playbook playbook.yml -e "webserver_state=installed"

Sortie :

TASK [stephrobert.webserver : Validating arguments against arg spec 'main'] ***
fatal: [web1.lab]: FAILED! => {
  "argument_errors": [
    "value of webserver_state must be one of: present, absent, latest, got: installed"
  ],
  "msg": "Validation of arguments failed:..."
}

Erreur claire : Ansible refuse d’exécuter le rôle. Aucune tâche n’a tourné — pas de demi-déploiement.

Cas 3 — Type incorrect

ansible-playbook playbook.yml -e "webserver_listen_port=cinquante"

Sortie :

"argument_errors": [
  "argument 'webserver_listen_port' is of type <class 'str'> and we were unable to convert to int"
]

Validation de structures complexes

argument_specs.yml supporte les dicts imbriqués et listes de dicts. Exemple pour un rôle users :

options:
  users_to_create:
    type: list
    elements: dict
    required: false
    default: []
    description: Liste des utilisateurs à créer
    options:
      name:
        type: str
        required: true
        description: Nom de l'utilisateur
      shell:
        type: str
        required: false
        choices:
          - /bin/bash
          - /bin/zsh
          - /sbin/nologin
      groups:
        type: list
        elements: str
        required: false
        default: []

L’utilisateur peut passer :

users_to_create:
  - name: alice
    shell: /bin/zsh
    groups: [wheel, developers]
  - name: bob
    shell: /bin/bash

Et Ansible valide que chaque entrée a le bon format. Une shell: /bin/csh ferait échouer la validation (pas dans choices:).

Documentation auto via ansible-doc

Une fois argument_specs.yml posé, le rôle est documenté automatiquement :

ansible-doc --type role stephrobert.webserver

Sortie :

> STEPHROBERT.WEBSERVER

ENTRY POINT: main - Installer et configurer nginx avec validation

OPTIONS (= is mandatory):

= webserver_package
    Nom du paquet à installer
    choices: [nginx]
    default: nginx
    type: str

- webserver_listen_port
    Port d'écoute HTTP (1-65535)
    default: 80
    type: int

...

Documentation à jour à 100 % — synchro avec le code, pas de drift entre code et README.

Pratiquer dans le lab

Cette page a un lab d’accompagnement : labs/roles/argument-specs/ dans stephrobert/ansible-training.

Le lab ajoute meta/argument_specs.yml au rôle webserver et prouve la validation par 5 tests testinfra dont un qui lance le playbook avec une valeur invalide et vérifie que l’échec contient le message attendu.

cd ~/Projets/ansible-training/labs/roles/argument-specs/

ansible-doc --type role webserver       # doc auto-générée
pytest -v challenge/tests/               # 5 tests dont validation négative

Pièges courants

Symptôme	Cause	Fix
argument_specs ignoré	Ansible < 2.11	Mettre à jour
Variable non validée	Pas dans options: du argument_specs.yml	Ajouter chaque variable de defaults/ dans la spec
default: ignoré	required: true + default: (incompatible)	Choisir : soit obligatoire, soit avec défaut
Erreur sur valeur Jinja	Templates non résolus avant validation	Définir la variable en clair dans le play, pas via lookup
ansible-doc --type role plante	Pas de meta/argument_specs.yml	Créer le fichier (au moins squelette main:)

Glissez pour voir

À retenir

• meta/argument_specs.yml = contrat d’API d’un rôle. Standard 2026.
• Validation automatique : type, choix, required, valeurs imbriquées.
• Erreur claire au runtime si valeur invalide — pas de demi-déploiement.
• Documentation auto via ansible-doc --type role.
• ansible-lint --profile=production vérifie la présence du fichier.
• Supporte dicts imbriqués et listes de dicts (rôles complexes).

Prochaines étapes

TDD avec Molecule Adopter le développement piloté par les tests — change votre pratique

Handlers et meta Connecter les handlers via notify, enrichir meta/main.yml pour Galaxy

Auditer un rôle existant argument_specs.yml est un critère d'audit majeur d'un rôle Galaxy

ansible-lint profile production Le profil le plus strict — vérifie aussi la présence d'argument_specs

×

📖 Voir la documentation →