Action plugins Ansible : exécution côté control node, cas d'usage et structure

Un action plugin Ansible s’exécute côté control node, pas sur la cible. C’est la différence fondamentale avec un module Python classique : un module est transféré et exécuté sur le managed node ; un action plugin tourne localement sur le poste qui lance Ansible, avec accès aux variables, aux facts collectés, et au moteur de template. C’est l’outil idéal pour orchestrer plusieurs modules, pré-calculer des données complexes avant de les pousser, ou fusionner des fichiers de configuration sans impliquer la cible. Cette page couvre les cas d’usage légitimes, la structure d’un action plugin, et la frontière avec les modules classiques.

Vous voulez…	Type	Pourquoi
Modifier l’état d’un service / fichier sur la cible	Module	Exécution distante, idempotence, transfert SSH
Appeler une API depuis le control node (ex: récupérer un token)	Action plugin	Pas besoin de Python sur la cible
Fusionner plusieurs templates Jinja avant déploiement	Action plugin	Logique de pré-traitement
Wrapper un module existant avec auto-magic (auto-templating, validation)	Action plugin	Hérite de `ActionBase` et délègue au module
Manipuler des données avec une logique complexe	Filtre Jinja custom	Plus simple qu’un action plugin si pas de side effect

# Squelette minimal — fichier plugins/action/myaction.py
from ansible.plugins.action import ActionBase

class ActionModule(ActionBase):
    TRANSFERS_FILES = False         # True si vous transférez des fichiers générés
    _VALID_ARGS = frozenset(('source', 'dest'))   # validation arguments depuis 2.13+

    def run(self, tmp=None, task_vars=None):
        result = super().run(tmp, task_vars)
        del tmp                       # tmp est obsolète depuis 2.5

        # 1. Récupérer les arguments validés
        source = self._task.args.get('source')
        dest = self._task.args.get('dest')

        # 2. Logique côté control node (lecture, calcul, templating)
        # ...

        # 3. Optionnellement déléguer à un module classique
        # module_result = self._execute_module(
        #     module_name='ansible.builtin.copy',
        #     module_args={'src': generated_file, 'dest': dest},
        #     task_vars=task_vars,
        # )

        result['changed'] = True       # ou False selon l'effet réel
        return result

Sécurité non négociable :

_VALID_ARGS (depuis Ansible 2.13) — déclare les arguments acceptés et fait échouer la tâche avec un message clair en cas d’argument inconnu (typo). Avant 2.13, le plugin acceptait silencieusement n’importe quoi.
del tmp en début de run() — tmp est obsolète depuis 2.5, utiliser self._connection._shell.tmpdir si besoin d’un dossier temporaire.
Pas de side effect côté control node sans utilité — un action plugin qui écrit des fichiers locaux non maîtrisés casse la reproductibilité.
Attention aux secrets : un action plugin a accès à toutes les variables, y compris celles chiffrées Vault déchiffrées en mémoire. Idem no_log: true au niveau de la tâche pour ne pas leak.

Ce que vous allez apprendre

Distinguer un module classique (exécuté sur la cible) d’un action plugin (exécuté sur le control node).
Identifier les 3 cas d’usage légitimes d’un action plugin et ceux où un filtre / module suffit.
Implémenter un action plugin minimal avec ActionBase et _VALID_ARGS.
Déléguer à un module classique depuis l’action plugin (pattern « action wrapper »).
Tester un action plugin avec ansible-test sanity --docker.

Prérequis

Python maîtrisé : classes, héritage, gestion d’exceptions, manipulation de dicts. Voir doc Python.
Avoir développé un module classique pour comprendre la frontière.
Connaître la structure d’une collection.

Module vs action plugin — où s’exécute le code ?

Pour clarifier la différence : quand vous écrivez - ansible.builtin.copy: ..., ce qui se passe vraiment dépend du type de plugin :

┌─────────────────┐                      ┌──────────────────┐
│  Control node   │                      │  Managed node    │
│  (votre poste)  │   ─── SSH ────►      │  (web1.lab)      │
└─────────────────┘                      └──────────────────┘

Module classique :
  1. Le control node prépare les arguments + le module Python
  2. Transfert via SSH (ou Podman si EE)
  3. Exécution Python SUR LA CIBLE
  4. Retour du résultat

Action plugin :
  1. Le code tourne SUR LE CONTROL NODE (votre poste)
  2. Accès à task_vars, facts collectés, secrets déchiffrés
  3. Peut appeler des modules classiques DE-PUIS le control node
  4. Retour direct

Conséquences pratiques :

Aspect	Module	Action plugin
Prérequis Python sur la cible	Oui	Non (sauf si délègue à un module)
Accès à `ansible_facts.*`	Oui (transmis par Ansible)	Oui (directement via `task_vars`)
Accès aux variables Vault	Oui (déchiffrées avant transfert)	Oui (en mémoire)
Performance sur grand parc	Limitée par SSH × N hôtes	Locale, peut paralléliser librement
Accès aux fichiers du projet (templates, files)	Non	Oui

Les 3 cas d’usage légitimes

Cas 1 — Pré-traitement avant déploiement

Vous avez N fichiers de configuration partiels qu’il faut fusionner et templater avant de pousser sur la cible :

# Sans action plugin : 3 tâches successives
- ansible.builtin.template:
    src: base.conf.j2
    dest: /tmp/part1.conf
- ansible.builtin.template:
    src: prod.conf.j2
    dest: /tmp/part2.conf
- ansible.builtin.assemble:                     # module assemble côté cible
    src: /tmp/
    dest: /etc/myapp/full.conf

# Avec action plugin : 1 tâche, fusion sur control node
- mycollection.merge_configs:
    sources:
      - templates/base.conf.j2
      - templates/prod.conf.j2
    dest: /etc/myapp/full.conf

Le pré-traitement côté control node évite 3 transferts SSH et la création de fichiers temporaires sur la cible.

Cas 2 — Wrapper qui ajoute de la magie

Vous voulez un module mycollection.copy_with_audit qui délègue à ansible.builtin.copy mais ajoute un log d’audit dans une BDD locale au control node :

class ActionModule(ActionBase):
    _VALID_ARGS = frozenset(('src', 'dest', 'audit_user'))

    def run(self, tmp=None, task_vars=None):
        result = super().run(tmp, task_vars)
        del tmp

        # Déléguer à ansible.builtin.copy
        copy_result = self._execute_module(
            module_name='ansible.builtin.copy',
            module_args={
                'src': self._task.args.get('src'),
                'dest': self._task.args.get('dest'),
            },
            task_vars=task_vars,
        )

        # Ajouter notre logique : auditer en local
        if copy_result.get('changed'):
            self._log_audit(
                user=self._task.args.get('audit_user'),
                target=self._task.args.get('dest'),
                host=task_vars['inventory_hostname'],
            )

        result.update(copy_result)
        return result

L’utilisateur du plugin écrit mycollection.copy_with_audit: exactement comme copy:, mais bénéficie de l’audit transparent.

Cas 3 — Orchestration multi-modules

Un action plugin peut appeler plusieurs modules dans un ordre conditionnel — utile pour des opérations atomiques où le rollback est intégré :

def run(self, tmp=None, task_vars=None):
    result = super().run(tmp, task_vars)

    # 1. Snapshot
    snap = self._execute_module(module_name='community.general.snapshot', ...)
    if snap.get('failed'):
        result['failed'] = True
        return result

    # 2. Migration
    migrate = self._execute_module(module_name='ansible.builtin.command', ...)
    if migrate.get('failed'):
        # Rollback automatique
        self._execute_module(module_name='community.general.snapshot_restore', ...)
        result['failed'] = True
        result['msg'] = "Migration échouée, rollback appliqué"
        return result

    result['changed'] = True
    return result

Pattern utile pour les migrations BDD ou les opérations critiques qui demandent un rollback intégré.

Ce qui ne justifie pas un action plugin

Vous pensez avoir besoin…	Préférer
Manipuler une string/liste/dict	Filtre Jinja custom (plus léger)
Faire une boucle complexe	`loop:` + `selectattr` + `map`
Capturer une valeur et la réutiliser	`set_fact:` + `register:`
Conditionner l’exécution selon un fact	`when:`

Un action plugin ajoute de la complexité (Python, packaging dans collection, tests). Le réserver aux vraies orchestrations multi-étapes ou aux cas où le pré-traitement local apporte un gain net.

Structure d’un projet

mycollection/
├── galaxy.yml
├── plugins/
│   ├── action/
│   │   └── myaction.py            # le code Python du plugin
│   └── modules/
│       └── myaction.py            # facultatif — un module compagnon
├── meta/
│   └── runtime.yml
└── README.md

Pattern courant : un fichier dans plugins/action/<nom>.py (logique côté control node) et un fichier dans plugins/modules/<nom>.py (module compagnon avec DOCUMENTATION, EXAMPLES, RETURN). Quand l’utilisateur appelle mycollection.<nom>:, Ansible exécute le action/ ; le modules/ sert pour la doc et le fallback si _execute_module est utilisé.

Squelette d’un action plugin moderne (2026)

#!/usr/bin/python
from ansible.errors import AnsibleActionFail
from ansible.plugins.action import ActionBase
from ansible.utils.display import Display

display = Display()


class ActionModule(ActionBase):
    """Action plugin qui fusionne plusieurs templates en un seul fichier."""

    TRANSFERS_FILES = True
    _VALID_ARGS = frozenset(('sources', 'dest', 'mode', 'owner', 'group'))

    def run(self, tmp=None, task_vars=None):
        result = super().run(tmp, task_vars)
        del tmp

        # 1. Validation des arguments
        sources = self._task.args.get('sources')
        dest = self._task.args.get('dest')
        if not sources or not dest:
            raise AnsibleActionFail("'sources' et 'dest' sont obligatoires")

        # 2. Templating local de chaque source
        merged = []
        for src in sources:
            content = self._loader.get_real_file(src)
            templated = self._templar.template(open(content).read())
            merged.append(templated)

        # 3. Écriture d'un fichier temporaire local
        merged_file = '/tmp/merged_{}.conf'.format(task_vars['inventory_hostname'])
        with open(merged_file, 'w') as f:
            f.write('\n'.join(merged))

        # 4. Délégation à copy: pour transférer sur la cible
        copy_args = {
            'src': merged_file,
            'dest': dest,
        }
        for opt in ('mode', 'owner', 'group'):
            if self._task.args.get(opt):
                copy_args[opt] = self._task.args[opt]

        copy_result = self._execute_module(
            module_name='ansible.builtin.copy',
            module_args=copy_args,
            task_vars=task_vars,
        )

        # 5. Nettoyage du fichier temporaire local
        import os
        os.remove(merged_file)

        result.update(copy_result)
        return result

Points-clés :

_VALID_ARGS valide les arguments fournis — typo détecté tôt.
AnsibleActionFail pour échouer proprement avec un message clair (préféré à result['failed'] = True).
self._templar.template() pour interpoler les variables Jinja dans une string.
self._execute_module pour déléguer à un module classique depuis l’action plugin.
Nettoyage explicite du fichier temporaire local (sinon il s’accumule).

Tests

Comme pour les modules, ansible-test sanity --docker default valide :

La conformité PEP8.
Les imports.
L’absence d’erreurs lors du chargement.

cd mycollection/
ansible-test sanity --docker default
ansible-test units --docker default plugins/action/

Pour des tests fonctionnels, écrire un playbook de test dans tests/ qui appelle l’action sur localhost.

À retenir

Action plugin = code côté control node, pas sur la cible. Différent du module classique qui s’exécute distant.
3 cas légitimes : pré-traitement avant déploiement, wrapper avec auto-magic, orchestration multi-modules.
Pas de surcouche sur ce qu’un filtre Jinja, un loop: ou un set_fact: peut faire.
_VALID_ARGS (Ansible 2.13+) + AnsibleActionFail pour validation et erreurs propres.
self._execute_module pour déléguer à un module classique depuis le plugin.
Packager dans une collection dès le départ — plugins/action/ est le dossier standard.

Pour aller plus loin

Modules Python custom L'autre type de plugin — exécuté sur la cible. Compagnon naturel d'un action plugin

Créer une collection custom Packager modules + action plugins + filtres dans une collection publiable

Filtres Jinja avancés L'alternative légère à un action plugin pour la transformation de données

Préparer EX374 Specialist in Developing Automation — la certification dédiée au dev avancé