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.

# 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

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

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

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 :

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 :

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

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

Smoke test post-build :
Fenêtre de terminal
```
podman run --rm $TAG ansible --version | head -1
```
Si vide → bug version: 3. Si OK, passer à 2.
Inspecter les collections :
Fenêtre de terminal
```
podman run --rm $TAG ansible-galaxy collection list 2>&1 | head -20
```
Si une collection attendue manque → bug requirements.yml.
Inspecter les Python deps :
Fenêtre de terminal
```
podman run --rm $TAG pip list 2>&1 | head -30
```
Si une lib attendue manque → bug requirements.txt.
Tester sur cible avec ANSIBLE_KEEP_REMOTE_FILES=1 :
Fenêtre de terminal
```
ANSIBLE_KEEP_REMOTE_FILES=1 ansible-navigator run site.yml -vvv -m stdout
```
Si MODULE FAILURE → inspecter ~/.ansible/tmp/... sur la cible.
Inspecter le Containerfile généré :
Fenêtre de terminal
```
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.