Custom Execution Environments & Runner Profiles
Run playbooks in isolated OCI containers (Podman/Docker) or dedicated Python virtualenvs to prevent dependency conflicts.
As your automation footprint expands, different playbooks inevitably demand conflicting Python packages and Ansible collection versions:
- Legacy playbooks might require Ansible 2.15 with older
botocorelibraries for legacy AWS infrastructure. - Modern cloud playbooks might require Ansible 2.17,
kubernetes>=29.0, and specialized NetBox or Terraform integration SDKs.
Installing every collection and dependency into a single shared Python environment inevitably leads to dependency collisions.
CIEL resolves this with Execution Environments (EE): you can execute playbooks inside Isolated OCI Containers (Podman / Docker) or across Dedicated Python Virtualenvs, selectable per project, per saved run, or directly at task launch.
1. Container vs Native Virtualenv Execution
| Feature | Container Runner (OCI / Podman) | Native Python Virtualenv |
|---|---|---|
| Isolation Level | Complete OS, filesystem, and process isolation | Controller user space / Virtualenv |
| Best For | Production deployments, multi-cloud fleets, strict security | Fast local development, diagnostic runs, edge appliances |
| Prerequisites | Podman or Docker daemon installed on controller | Python 3.10+ (using uv or python3-venv) |
| Portability | Reproducible across any controller host via container images | Dependent on controller host OS packages and libraries |
| Volume Mounts | Project files/, roles/, and temporary SSH keys mounted into /runner | Direct host filesystem access |
2. Setting Up Native Python Virtualenvs
If you prefer executing directly on the controller host without container overhead, you can maintain dedicated Python virtual environments for different Ansible versions. CIEL supports any standard virtual environment structure containing bin/ansible-playbook and bin/python.
First, prepare a shared base directory on the controller host:
sudo mkdir -p /opt/ciel-venvs
sudo chown -R $USER:$USER /opt/ciel-venvsOption A: Fast Setup with uv (Recommended)
uv creates isolated environments in milliseconds and can download specific Python versions on demand without requiring system PPA repositories or manual compilation.
# 1. Create a dedicated virtual environment with a pinned Python version
uv venv /opt/ciel-venvs/ansible-2.17 --python 3.11
# 2. Install ansible-core and runner dependencies directly without activating
uv pip install --python /opt/ciel-venvs/ansible-2.17 \
ansible-core==2.17.4 \
ansible-runner \
boto3 \
kubernetes
# 3. Verify the installed CLI binary
/opt/ciel-venvs/ansible-2.17/bin/ansible-playbook --versionOption B: Standard Setup with python3 -m venv & pip
For environments where third-party package managers are restricted by policy, use the standard Python toolchain:
# 1. Create the virtual environment using Python's built-in module
python3 -m venv /opt/ciel-venvs/ansible-2.17
# 2. Activate the environment and install dependencies
source /opt/ciel-venvs/ansible-2.17/bin/activate
pip install --upgrade pip
pip install ansible-core==2.17.4 ansible-runner boto3 kubernetes
deactivate
# 3. Verify the installed CLI binary
/opt/ciel-venvs/ansible-2.17/bin/ansible-playbook --versionBoth methods yield an identical virtual environment layout. CIEL auto-probes /opt/ciel-venvs/ansible-2.17/bin/ansible-playbook upon registration to detect the exact Ansible and Python runtime versions.
3. Registering Execution Environments in CIEL
Execution Environments are managed in Project Settings (/projects) under the Project Execution Engine & Environments card:
- Navigate to Project Settings (
/projects) in the workspace navigation. - In the Project Execution Engine & Environments section, click + Add Environment.
- Fill in the profile parameters:
- Profile Name: A descriptive label (e.g.
Ansible 2.17 Hardened RunnerorKubernetes & Cloud EE). - Execution Mode: Choose Podman Container or Native Host System.
- OCI Container Image Tag (for Podman): Specify the image tag (e.g.
quay.io/ansible/creator-ee:latestor an internal registry tag). - Virtual Environment Path (for Native): Specify the absolute directory path (e.g.
/opt/ciel-venvs/ansible-2.17).
- Profile Name: A descriptive label (e.g.
- Click Create Profile.
Automatic Environment Probing:
Upon creation, CIEL automatically runs an immediate health probe:
- Native Virtualenv: Executes
<venv_path>/bin/ansible-playbook --versionin the isolated venv to discover and record the exactansible_versionandpython_version. - Podman Container: Executes
podman image exists <image>to verify that the container image is cached locally and ready for execution. Missing images are flagged with an actionable warning.
You can trigger a re-probe at any time by clicking Probe next to any configured environment.
4. Selecting Execution Environments at Runtime
CIEL allows setting defaults while retaining granular runtime overrides:
- Project Default: Set the default execution mode and environment profile in Project Settings. All new playbooks and studio sessions inherit this default.
- Saved Runs: Lock specific execution environments into a template in Saved Runs (
/saved-runs), ensuring recurring jobs always run with their certified dependency stack. - Studio & Ad-Hoc Runs: Click Run Options... before launching any playbook to switch between Native Mode and Podman Container, or select a specific runner profile on the fly.
5. Sibling Container Architecture & SSH Prerequisites
When CIEL Controller itself runs inside a container and spawns OCI runner containers via the host container socket (/run/user/1000/podman/podman.sock or /var/run/docker.sock), two operational requirements apply:
Symmetric Path Binding
The Controller writes workspace files (inventory, extravars, playbooks) and instructs the host container daemon to mount that workspace directory into the runner container (-v <workspace>:/runner:Z).
Because the host container engine resolves volume mounts against the host filesystem, the data directory path inside the controller container must match the path on the host:
- Host mount:
-v /opt/ciel-data:/opt/ciel-data:Z - Controller environment:
-e CIEL_HOME=/opt/ciel-data
If the controller writes files to an internal path like /root/.ciel without symmetric host binding, the host daemon attempts to resolve /root/.ciel on the host OS. On Linux systems where /root permissions are restricted (0700), the runner container fails with:
Error: statfs /root/.ciel/workspaces/...: permission deniedSSH Password Authentication (sshpass)
If any target host connects using password authentication (ciel_password) instead of SSH keypairs, Ansible requires the sshpass utility.
While CIEL's native controller packages include sshpass, upstream Execution Environment base images (such as quay.io/ansible/creator-ee, built on Fedora Linux) do not bundle it by default. Running password authenticated playbooks in these environments produces:
fatal: [host]: FAILED! => {"msg": "to use the 'ssh' connection type with passwords or pkcs11_provider, you must install the sshpass program"}To resolve this, install sshpass into your cached local image:
# Install sshpass into the local creator-ee image
podman run --name temp-ee quay.io/ansible/creator-ee:latest microdnf install -y sshpass
podman commit temp-ee quay.io/ansible/creator-ee:latest
podman rm temp-eeOr maintain a versioned production runner image using a Containerfile:
FROM quay.io/ansible/creator-ee:latest
RUN microdnf install -y sshpass \
&& microdnf clean all6. External References
For upstream Ansible and runtime documentation on execution environment architecture and tooling:
- Astral uv Documentation: High-performance Python package installer and virtual environment manager.
- Ansible Execution Environments Overview: Understanding execution environments, tooling, and philosophy.
- Ansible Builder Documentation: Tool for automating the creation of containerized execution environments with
execution-environment.yml. - Ansible Runner Architecture: How Ansible Runner manages runtime execution and container volume mounting.