Debug d'un Execution Environment cassé : version: 3 oublié, collection introuvable, deps Python invalides

Un EE peut "build OK" et pourtant être inutilisable. Le piège le plus fréquent en 2026 : oublier version: 3 dans execution-environment.yml, ansible-builder lit alors en mode v1 hérité, ignore silencieusement les sections de dépendances modernes, et produit une image qui n'a même pas ansible-core installé. Aucune erreur visible. Cette page liste les 4 bugs les plus fréquents avec leur diagnostic et leur fix.

À la fin, vous saurez détecter immédiatement un EE défectueux par smoke test, identifier la cause racine via les logs ansible-builder --verbosity 2, et conserver les modules Ansible exécutés sur la cible (ANSIBLE_KEEP_REMOTE_FILES=1) pour debug forensic.

Pressé ? Le smoke test EE post-build

# 1. Smoke test : ansible-core est-il bien dans l'EE ?
podman run --rm <image> ansible --version

# 2. Collections embarquées
podman run --rm <image> ansible-galaxy collection list

# 3. Python interpréteur
podman run --rm <image> python3 --version

# 4. Build verbeux pour diagnostiquer un échec silencieux
ansible-builder build --verbosity 2 --tag debug-ee 2>&1 | tee build.log

# 5. Inspecter les fichiers internes de l'EE
podman run --rm -it <image> /bin/bash
# Dans le conteneur :
ls -la /usr/share/ansible/collections/
which ansible
cat /etc/os-release

Les 4 bugs les plus fréquents :

Symptôme	Cause	Fix
EE build OK mais ansible: not found	version: 3 oublié dans execution-environment.yml	Ajouter version: 3 en première ligne
Collection not found: my.coll	typo ou collection inexistante	Vérifier ansible-galaxy collection search
Build échoue sur pip install	version Python pinnée inexistante sur PyPI	Vérifier sur pypi.org/project
Permission denied sur volume Podman	SELinux + bind mount sans :Z	Ajouter :Z sur tous les bind mounts

Glissez pour voir

Sécurité non négociable :

• version: 3 MANDATORY, c'est la cause N°1 d'EE silencieusement vide. Smoke test détecte en 1 seconde.
• Smoke test après chaque build, pas optionnel. CI/CD doit l'exécuter avant push.
• ansible-builder build --verbosity 2 quand un build se comporte bizarrement, révèle les pip install skippés, les collections échouées en silence.
• Volumes Podman avec :Z sur SELinux activé (RHEL/AlmaLinux), sinon Permission denied qui ressemble à un bug Ansible alors que c'est SELinux.

Ce que vous allez apprendre

• Diagnostiquer un EE qui build "OK" mais ne contient pas ansible-core.
• Reconnaître une collection Galaxy inexistante dans les logs.
• Détecter une version Python pinnée inexistante sur PyPI.
• Conserver les modules Ansible exécutés (ANSIBLE_KEEP_REMOTE_FILES).
• Smoke test post-build systématique en CI.

Prérequis

• Avoir lu Construire un EE custom.
• ansible-builder ≥ 3.1.0 et Podman installés.

Diagnostic rapide, 4 symptômes, 4 causes

Symptôme	Cause probable	Fix
build OK mais podman run --rm <ee> ansible --version → command not found	version: 3 oublié	Ajouter version: 3 en première ligne
Build échoue : community.does-not-exist:1.2.3 was NOT installed successfully	Collection Galaxy inexistante ou version invalide	Vérifier sur galaxy.ansible.com
Build échoue : Could not find a version that satisfies the requirement <pkg>==<ver>	Version Python inexistante sur PyPI	Vérifier sur pypi.org
MODULE FAILURE à l'exécution avec python: command not found	Mauvais python_interpreter côté cible	Pinner ansible_python_interpreter dans inventory

Glissez pour voir

Bug 1, version: 3 oublié (le piège n°1)

Symptôme : ansible-builder build retourne Successfully tagged ... sans erreur. Mais l'EE est vide :

podman run --rm local/my-ee:dev ansible --version
# /bin/sh: ansible: command not found

Diagnostic : remonter aux logs avec --verbosity 2 :

ansible-builder build \
  --tag local/my-ee:dev \
  --container-runtime podman \
  --file execution-environment.yml \
  --context ./context \
  --verbosity 2 2>&1 | head -20

Vous voyez :

WARNING: No 'version' key found, defaulting to schema v1
[1/2] Building image...

Cause : sans version: 3, ansible-builder utilise le schéma v1 hérité. Les sections dependencies.ansible_core, dependencies.python, dependencies.system modernes sont silencieusement ignorées. L'image est buildée à partir de la base sans ajouter ansible-core.

Fix : ajouter version: 3 en première ligne :

---
version: 3                              # ← OBLIGATOIRE en 2026

images:
  base_image:
    name: quay.io/ansible/community-ee-minimal:latest

dependencies:
  ansible_core:
    package_pip: ansible-core==2.18.1
  ansible_runner:
    package_pip: ansible-runner==2.4.1
  galaxy: requirements.yml
  python: requirements.txt
  system: bindep.txt

Smoke test obligatoire en CI

Toujours ajouter dans la CI un smoke test post-build :

podman run --rm $TAG ansible --version | head -1 | grep -q "^ansible \[core" \
  || (echo "EE invalide : ansible-core absent" && exit 1)

C'est la vérification qui attrape le bug version: 3 oublié immédiatement.

Bug 2, Collection Galaxy inexistante

Symptôme :

[1/3] Galaxy stage:
  ERROR! - community.does-not-exist:1.2.3 was NOT installed successfully:
  could not find versions that match: 1.2.3 for: community.does-not-exist

Diagnostic : le nom de la collection ou sa version n'existe pas sur Galaxy.

ansible-galaxy collection list community.does-not-exist 2>&1
# ou via le navigateur :
# https://galaxy.ansible.com/ui/repo/published/community/does-not-exist/

Causes fréquentes :

• Typo dans le nom : comunity.general au lieu de community.general.
• Version retirée : la collection a été dépréciée et la version 1.2.3 n'est plus distribuée.
• Collection privée : nom valide mais hébergée sur Automation Hub (pas Galaxy), il faut configurer ANSIBLE_GALAXY_SERVER_LIST.

Fix : remplacer par une collection valide :

requirements.yml

collections:
  - name: ansible.posix
    version: 2.0.0
  - name: kubernetes.core           # ← collection valide
    version: 5.1.1

Bug 3, Version Python inexistante sur PyPI

Symptôme :

[2/3] Python deps:
  ERROR: Could not find a version that satisfies the requirement kubernetes==9999.0.0
  ERROR: No matching distribution found for kubernetes==9999.0.0

Diagnostic : la version pinnée n'existe pas sur PyPI.

pip index versions kubernetes 2>&1 | head -5
# ou via le navigateur :
# https://pypi.org/project/kubernetes/

Causes fréquentes :

• Typo : 31.0.O (lettre O) au lieu de 31.0.0 (chiffre 0).
• Version trop récente non encore publiée.
• Version retirée par l'éditeur (rare mais arrive).
• Proxy d'entreprise qui filtre PyPI.

Fix : pinner une version réelle :

requirements.txt

kubernetes==31.0.0
PyYAML==6.0.2
jsonpatch==1.33

Renovate pour pinning auto

Renovate ouvre automatiquement des PR pour bumper ansible-core==2.18.1 → 2.18.2 quand une nouvelle version sort. Configurez-le dans le repo de votre EE pour ne jamais rater une mise à jour de sécurité.

Bug 4, Python interpreter mismatch côté cible

Symptôme : l'EE est OK mais à l'exécution :

fatal: [target]: FAILED! => {"module_stderr": "...python3: command not found", "module_stdout": "", "msg": "MODULE FAILURE\nSee stdout/stderr for the exact error", "rc": 127}

Diagnostic : l'EE embarque python3.11, mais la cible (par exemple AlmaLinux 8) n'a que python3.6. Le module Ansible transféré par l'EE essaie de lancer python3.11 qui n'existe pas sur la cible.

Investigation forensique : conserver le module sur la cible :

ANSIBLE_KEEP_REMOTE_FILES=1 ansible-navigator run site.yml -vvv -m stdout

Sur la cible, le module est dans ~ansible/.ansible/tmp/ansible-tmp-*/AnsiballZ_<module>.py. Inspecter :

ssh ansible@target
cd ~/.ansible/tmp/ansible-tmp-*/
head -1 AnsiballZ_copy.py
# → #!/usr/bin/python3.11    (or whatever interpreter the EE expected)

Fix : pinner explicitement l'interpréteur dans l'inventaire selon la cible :

[webservers:vars]
ansible_python_interpreter=/usr/bin/python3

Ou dans execution-environment.yml, choisir une base alignée avec les cibles :

images:
  base_image:
    name: quay.io/ansible/community-ee-minimal:latest    # UBI 9, Python 3.11

# Si cibles AlmaLinux 8 (Python 3.6) → choisir une base UBI 8 plutôt

Workflow de debug systématique

1. Smoke test post-build :

   podman run --rm $TAG ansible --version | head -1

   Si vide → bug version: 3. Si OK, passer à 2.

2. Inspecter les collections :

   podman run --rm $TAG ansible-galaxy collection list 2>&1 | head -20

   Si une collection attendue manque → bug requirements.yml.

3. Inspecter les Python deps :

   podman run --rm $TAG pip list 2>&1 | head -30

   Si une lib attendue manque → bug requirements.txt.

4. Tester sur cible avec ANSIBLE_KEEP_REMOTE_FILES=1 :

   ANSIBLE_KEEP_REMOTE_FILES=1 ansible-navigator run site.yml -vvv -m stdout

   Si MODULE FAILURE → inspecter ~/.ansible/tmp/... sur la cible.

5. Inspecter le Containerfile généré :

   cat ./context/Containerfile

   Vérifier les 4 stages (base, galaxy, builder, final).

Lab pratique

Le lab ee/debug (labs/ee/debug/) fournit un execution-environment-buggy.yml avec 3 bugs volontaires (version: 3 oublié, collection inexistante, version Python invalide). À diagnostiquer + corriger. Validation par 6 tests pytest.

Sécurité, bonnes pratiques 2026

• version: 3 mandatory en première ligne, jamais oublié.
• Smoke test post-build dans la CI : podman run --rm $TAG ansible --version.
• --verbosity 2 minimum en CI pour capter les warnings comme « schema v1 default ».
• Pinning par digest SHA-256 sur la base image en production : community-ee-minimal@sha256:abc....
• Renovate / Dependabot pour bumper les pinning automatiquement (PR-driven).
• hadolint sur le Containerfile généré pour détecter les anti-patterns.

À retenir

• Un EE peut "build OK" sans contenir ansible-core, le smoke test post-build est obligatoire.
• version: 3 oublié → schéma v1 hérité utilisé silencieusement, 95 % des cas de debug.
• Collection Galaxy inexistante → vérifier sur galaxy.ansible.com avec le nom + version.
• Version PyPI inexistante → vérifier sur pypi.org.
• ANSIBLE_KEEP_REMOTE_FILES=1 pour conserver les modules sur la cible et debug forensic.
• Renovate pour ne jamais rater une mise à jour de sécurité sur les pinning.

Prochaines étapes

Vue d'ensemble Execution Environments Retour à la page pivot pour relier tous les sujets.

Construire un EE custom Bonnes pratiques pinning + multi-stage Containerfile.

Pipeline CI/CD pour EE Build + scan Trivy + signature cosign keyless.

Lab 88 sur GitHub 3 bugs volontaires à diagnostiquer avec tests pytest.

×

📖 Voir la documentation →