ansible-proxy-chain/openspec/changes/archive/2026-04-22-fix-python-interpreter/design.md

Context

Ansible requires Python on remote hosts to execute modules. The relay-server is a minimal server image without Python 3 installed. When Ansible runs the setup (fact gathering) module, it fails with /usr/bin/python3: not found (rc: 127). This blocks all plays against that host.

The project currently has no ansible_python_interpreter configuration and no pre-play to bootstrap Python.

Goals / Non-Goals

Goals:

• Ensure Python 3 is present on all managed hosts before any Ansible modules run
• Configure Ansible to auto-discover the Python interpreter path
• Make the solution idempotent and safe for hosts that already have Python

Non-Goals:

• Installing a specific Python version (system package manager default is fine)
• Managing Python virtual environments or pip packages
• Changing the existing role structure beyond what's necessary

Decisions

1. Use a raw pre-task play to bootstrap Python

Choice: Add a new play at the top of site.yml that uses the raw module (which doesn't require Python) to install python3 via apt.

Rationale: The raw module executes commands directly over SSH without requiring Python on the remote. This is the standard Ansible pattern for bootstrapping Python on minimal images. Using a dedicated play with gather_facts: false avoids the setup module entirely.

Alternatives considered:

• Install Python manually before running Ansible: Defeats the purpose of automation and requires out-of-band steps.
• Use a custom SSH script: Adds complexity outside Ansible's management.

2. Set ansible_python_interpreter: auto in group_vars/all.yml

Choice: Configure interpreter auto-discovery globally.

Rationale: auto tells Ansible to probe common Python paths on the remote host rather than assuming /usr/bin/python3. This handles cases where Python is at /usr/bin/python3.x or other locations. Applied globally since all hosts benefit from resilient interpreter discovery.

Alternatives considered:

• Set per-host in inventory: More granular but unnecessary since all hosts are Debian/Ubuntu.
• Hardcode /usr/bin/python3: Fragile; breaks on systems where the path differs.

Risks / Trade-offs

• [First-run latency] The raw apt install adds a few seconds on first run. Subsequent runs are idempotent (apt skips already-installed packages). -> Acceptable trade-off for reliability.
• [Assumes apt-based OS] The raw task uses apt-get. If a non-Debian host is added later, this will fail. -> Mitigated by the project being explicitly Debian/Ubuntu-only (all roles use apt).