Migration rôle Ansible standalone vers collection : plugin

En 2026, les rôles standalone Galaxy v1 sont legacy. Galaxy NG (backend Galaxy v3) ne supporte que les collections. Si vous maintenez un rôle public, il faut le migrer en collection sans casser les playbooks downstream qui l’utilisent encore avec son ancien nom court. Le mécanisme officiel : meta/runtime.yml avec plugin_routing.redirect, qui maintient la rétrocompatibilité avec un warning de dépréciation et une removal_version planifiée.

Cette page montre la migration complète d’un mini-rôle (avec un module Python custom dans library/ legacy) vers une collection conforme, avec le redirect qui permet aux deux noms (ancien court + nouveau FQCN) de fonctionner pendant la période de transition.

# meta/runtime.yml de la nouvelle collection
---
requires_ansible: ">=2.18"

plugin_routing:
  modules:
    # ancien nom court → nouveau FQCN (redirect avec warning)
    my_module:
      redirect: my_namespace.my_collection.my_module
      deprecation:
        warning_text: "Use my_namespace.my_collection.my_module instead"
        removal_version: "2.0.0"      # version où l'alias sera retiré

  action:
    my_module:
      redirect: my_namespace.my_collection.my_module

Workflow de migration :

Initialiser la collection : ansible-galaxy collection init my_namespace.my_collection
Déplacer tasks/, handlers/, defaults/, templates/ du rôle vers roles/<name>/
Déplacer les modules de library/ vers plugins/modules/
Ajouter plugin_routing.redirect dans meta/runtime.yml pour chaque ancien module
CHANGELOG.rst annonce la dépréciation avec removal_version planifiée
Build + publish la collection
Maintenir l’ancien rôle en 1.x pour 1-2 cycles de release avant retrait

Sécurité non négociable :

plugin_routing.redirect mandatory — sans ça, vous cassez silencieusement tous les playbooks downstream qui utilisent l’ancien nom. Vos utilisateurs ne pardonneront pas.
removal_version explicite dans la dépréciation — pas un removal_version: "future" flou. Les utilisateurs doivent pouvoir planifier leur migration.
2 cycles de release minimum entre annonce de dépréciation et retrait — laisse le temps aux équipes de migrer leurs playbooks.
Documenter dans CHANGELOG.rst ET dans le README.md de l’ancien rôle — multi-canal pour ne pas surprendre.

Ce que vous allez apprendre

Identifier un rôle standalone candidat à la migration.
Initialiser la collection cible avec ansible-galaxy collection init.
Déplacer tasks/, handlers/, defaults/, templates/ vers roles/<name>/.
Déplacer un module custom de library/ vers plugins/modules/.
Configurer plugin_routing.redirect dans meta/runtime.yml.
Tester que l’ancien nom déclenche un warning mais fonctionne.
Planifier la removal_version (semver de la collection).

Prérequis

Avoir lu Créer une collection custom.
Un rôle standalone existant à migrer (ou en créer un fictif pour pratiquer).

Le rôle de départ — format legacy

Un rôle standalone Galaxy v1 a typiquement cette structure :

my-old-role/
├── tasks/main.yml
├── handlers/main.yml
├── defaults/main.yml
├── templates/
└── library/                ← DÉPRÉCIÉ : modules custom à la racine du rôle
    └── my_module.py

Avec un tasks/main.yml qui invoque le module par son nom court :

- name: Status check
  my_module:               # ← nom court (sans FQCN), legacy
  register: status

🔍 Observation : ce format est rejeté par Galaxy NG. Le library/ n’est plus reconnu dès qu’un rôle vit dans une collection. Les modules custom doivent vivre dans plugins/modules/ au niveau de la collection.

Étape 1 — Initialiser la collection cible

mkdir -p ansible_collections
ansible-galaxy collection init mycoll.webapp \
  --init-path ansible_collections/

🔍 Observation : génère la structure conforme avec roles/, plugins/modules/, meta/runtime.yml. Les nouveaux emplacements sont prêts à recevoir le contenu migré.

Étape 2 — Déplacer le rôle dans `roles/<name>/`

mkdir -p ansible_collections/mycoll/webapp/roles/myrole/tasks
cp my-old-role/tasks/main.yml \
   ansible_collections/mycoll/webapp/roles/myrole/tasks/main.yml

cp -r my-old-role/handlers \
      my-old-role/defaults \
      my-old-role/templates \
   ansible_collections/mycoll/webapp/roles/myrole/

Adapter tasks/main.yml pour utiliser le nouveau FQCN :

- name: Status check
  mycoll.webapp.my_module:    # ← nouveau FQCN
  register: status

🔍 Observation : à l’intérieur de la collection, on peut écrire des noms courts (my_module:) car Ansible les résout dans le contexte de la collection. Mais toujours préférer le FQCN explicite pour la lisibilité et la portabilité.

Étape 3 — Déplacer le module dans `plugins/modules/`

mkdir -p ansible_collections/mycoll/webapp/plugins/modules
cp my-old-role/library/my_module.py \
   ansible_collections/mycoll/webapp/plugins/modules/my_module.py

Compléter le module avec les sections obligatoires si elles manquent (cf Créer une collection) :

DOCUMENTATION : description + options + author.
EXAMPLES : usage YAML copiable avec FQCN complet.
RETURN : structure des valeurs retournées.

🔍 Observation : ansible-test sanity exige ces 3 sections. Sans, l’import Galaxy échoue silencieusement.

Étape 4 — Configurer `plugin_routing.redirect` — le cœur de la migration

C’est l’étape clé : permettre à un playbook qui invoque l’ancien nom court my_module: de continuer à marcher.

ansible_collections/mycoll/webapp/meta/runtime.yml :

---
requires_ansible: ">=2.18.0"

plugin_routing:
  modules:
    my_module:                    # ← l'ancien nom court
      redirect: mycoll.webapp.my_module    # ← le nouveau FQCN cible
      deprecation:
        removal_version: 2.0.0    # ← retrait planifié au bump majeur
        warning_text: |
          Le module 'my_module' (rôle standalone) est déprécié.
          Utilisez 'mycoll.webapp.my_module' (FQCN collection).

🔍 Observation cruciale : plugin_routing.modules.<old_name>.redirect déclare la cible. deprecation: ajoute un warning au runtime mais n’échoue pas. removal_version indique quand l’alias sera retiré (semver de la collection).

Étape 5 — Tester l’ancien nom + le nouveau FQCN

Créer un playbook de test :

---
- hosts: db1.lab
  collections:
    - mycoll.webapp                # ← déclare la collection (rétrocompat)
  tasks:
    - name: Test ancien nom court (avec deprecation warning)
      my_module:                    # ← l'ancien nom, qui sera redirigé
      register: legacy

    - name: Test nouveau FQCN explicite
      mycoll.webapp.my_module:
      register: new

    - ansible.builtin.copy:
        dest: /tmp/migration-proof.txt
        content: |
          legacy: {{ legacy.msg }}
          new: {{ new.msg }}
        mode: "0644"

Lancer :

ANSIBLE_COLLECTIONS_PATH=ansible_collections \
  ansible-playbook lab.yml

Sortie attendue :

[DEPRECATION WARNING]: Le module 'my_module' (rôle standalone) est déprécié...
TASK [Test ancien nom court (avec deprecation warning)] ***
ok: [db1.lab]
TASK [Test nouveau FQCN explicite] ***
ok: [db1.lab]

🔍 Observation : les deux noms fonctionnent. L’ancien nom déclenche un warning mais ne casse pas. Les playbooks downstream peuvent migrer progressivement vers le FQCN au gré des releases mineures.

Étape 6 — Planifier le retrait

Workflow release par release :

Version	Action
`1.0.0`	Première release de la collection avec `plugin_routing.redirect` actif
`1.x.x`	Releases mineures successives. Le warning est affiché. Les downstream migrent.
`2.0.0`	Retrait de l’alias court. `removal_version` atteinte → `plugin_routing` est retiré du `meta/runtime.yml`. Les playbooks qui n’ont pas migré cassent.

🔍 Observation : la removal_version doit être annoncée bien à l’avance (≥1 an typique) et documentée dans le CHANGELOG.rst comme breaking_changes au bump majeur.

Builder + publier la collection migrée

cd ansible_collections/mycoll/webapp/
ansible-galaxy collection build --output-path ../../../build/

# Publier sur Galaxy
ansible-galaxy collection publish \
  ../../../build/mycoll-webapp-1.0.0.tar.gz \
  --token "$GALAXY_TOKEN"

🔍 Observation : dépublier l’ancien rôle Galaxy v1 doit se faire après une période de transition (≥6 mois recommandé). En attendant, mettre un README sur le rôle standalone avec un lien vers la collection cible.

Lab pratique

Le lab collections/migration-role (labs/collections/migration-role/) reproduit ce parcours avec 7 tests pytest : structure conforme, plugin_routing.redirect présent, deprecation configurée, fichier preuve sur db1.lab qui montre le résultat des deux noms.

Pièges courants

Renommer le module sans plugin_routing.redirect : casse tous les playbooks downstream silencieusement.
library/ legacy à la racine du rôle dans la collection : ignoré par Ansible. Toujours déplacer les modules dans plugins/modules/.
Oublier meta/runtime.yml : ansible-test sanity échoue avec No requires_ansible.
Pas de removal_version : pattern incomplet, on ne sait pas quand retirer l’alias.
Bumper en 1.x au lieu de 2.0 quand on retire l’alias : casse semver.

À retenir

Rôles standalone = legacy. Galaxy NG (2026) ne supporte que les collections.
Migration = tasks/, handlers/, defaults/ → roles/<name>/. library/ → plugins/modules/.
plugin_routing.redirect dans meta/runtime.yml permet la rétrocompatibilité.
deprecation: ajoute un warning au runtime + removal_version planifie la suppression.
L’ancien nom continue de marcher — les downstream migrent progressivement.
Retrait au bump majeur : 2.0.0 retire l’alias, breaking change documenté dans CHANGELOG.rst.

Prochaines étapes

Vue d'ensemble Collections Retour au pivot pour relier tous les sujets de la section.

Pipeline CI matrice GitHub Actions + GitLab CI durcis 2026 pour collections.

Lab 97 sur GitHub Migration complète d'un rôle vers collection avec 7 tests pytest.

Migration rôle Ansible standalone vers collection : plugin_routing.redirect et meta/runtime.yml