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.

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

Le fichier déclare, entrée par entrée, ce que le rôle attend : un type, une valeur par défaut, une description et, quand c'est utile, la liste des valeurs autorisées. Ansible le lit avant la première tâche et refuse d'exécuter le rôle si une valeur ne correspond pas. L'exemple ci-dessous couvre les six variables publiques du rôle webserver.

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

Le fichier se lit de haut en bas comme un contrat : le point d'entrée concerné, sa description, puis une entrée par variable publique. Les trois sections suivantes détaillent ces niveaux, et c'est la dernière, celle des options, qui porte l'essentiel du travail de validation.

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

Une spécification ne se juge pas à la lecture mais au moment où Ansible refuse une valeur. Les trois cas ci-dessous se jouent avec la même commande, seule la valeur passée en --extra-vars change : une valeur correcte, une valeur hors de la liste autorisée, puis une valeur du mauvais type.

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

Le troisième cas vise le type plutôt que la liste de valeurs : le port est déclaré en entier, la valeur passée est une chaîne. L'erreur tombe au même endroit que la précédente, sur la tâche de validation, avec un message qui nomme la variable et le type attendu.

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.

Mettre en pratique

Une spec de variables ne se juge pas à la lecture, mais au moment où Ansible rejette une valeur. Le lab vous fait écrire meta/argument_specs.yml sur le rôle webserver, typer chaque entrée, puis relancer le playbook avec une valeur hors choices:. La tâche Validating arguments against arg spec 'main' doit alors échouer avant la première tâche réelle : c'est ce rejet automatique qui est vérifié, pas la simple présence du fichier.

Lab pratique

argument_specs : valider les variables d'entrée d'un rôle

$ dsoxlab run roles-argument-specs

Environnement : VM·Durée : ~50 min

Validé : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que dsoxlab et comment l'installer

dsoxlab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Installer la CLI et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/ansible-training

Lancer ce lab, puis valider votre travail :

dsoxlab run roles-argument-specs
dsoxlab check roles-argument-specs

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille l'installation, le calcul du score et les pièges.

Pièges courants

Les deux premières lignes empêchent la validation d'avoir lieu, version trop ancienne ou variable absente de la liste des options. Les trois suivantes la font échouer à tort : une entrée déclarée à la fois obligatoire et pourvue d'un défaut, une valeur issue d'une expression non encore résolue, ou une commande de documentation lancée sur un rôle dépourvu de ce fichier.

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

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

• 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).

Pour aller plus loin

• Cycle TDD complet avec Molecule : la validation des entrées y est traitée comme un cas de test à part entière.
• Profil production d'ansible-lint : le profil strict exige ce fichier, parmi d'autres règles à connaître.
• Auditer un rôle existant : la présence d'argument_specs.yml est un des critères d'adoption d'un rôle tiers.

×

📖 Voir la documentation →