Playbooks & Execution•7 min read•Advanced

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 botocore libraries 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

FeatureContainer Runner (OCI / Podman)Native Python Virtualenv
Isolation LevelComplete OS, filesystem, and process isolationController user space / Virtualenv
Best ForProduction deployments, multi-cloud fleets, strict securityFast local development, diagnostic runs, edge appliances
PrerequisitesPodman or Docker daemon installed on controllerPython 3.10+ (using uv or python3-venv)
PortabilityReproducible across any controller host via container imagesDependent on controller host OS packages and libraries
Volume MountsProject files/, roles/, and temporary SSH keys mounted into /runnerDirect host filesystem access
Interactive Architecture Diagram(Mermaid)
Rendering diagram...

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:

Terminal(bash)
sudo mkdir -p /opt/ciel-venvs
sudo chown -R $USER:$USER /opt/ciel-venvs

uv creates isolated environments in milliseconds and can download specific Python versions on demand without requiring system PPA repositories or manual compilation.

Terminal(bash)
# 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 --version

Option B: Standard Setup with python3 -m venv & pip

For environments where third-party package managers are restricted by policy, use the standard Python toolchain:

Terminal(bash)
# 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 --version

Both 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:

  1. Navigate to Project Settings (/projects) in the workspace navigation.
  2. In the Project Execution Engine & Environments section, click + Add Environment.
  3. Fill in the profile parameters:
    • Profile Name: A descriptive label (e.g. Ansible 2.17 Hardened Runner or Kubernetes & 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:latest or an internal registry tag).
    • Virtual Environment Path (for Native): Specify the absolute directory path (e.g. /opt/ciel-venvs/ansible-2.17).
  4. Click Create Profile.

Automatic Environment Probing:

Upon creation, CIEL automatically runs an immediate health probe:

  • Native Virtualenv: Executes <venv_path>/bin/ansible-playbook --version in the isolated venv to discover and record the exact ansible_version and python_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:

  1. Project Default: Set the default execution mode and environment profile in Project Settings. All new playbooks and studio sessions inherit this default.
  2. Saved Runs: Lock specific execution environments into a template in Saved Runs (/saved-runs), ensuring recurring jobs always run with their certified dependency stack.
  3. 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:

text
Error: statfs /root/.ciel/workspaces/...: permission denied

SSH 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:

text
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:

Terminal(bash)
# 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-ee

Or maintain a versioned production runner image using a Containerfile:

Containerfile(dockerfile)
FROM quay.io/ansible/creator-ee:latest
RUN microdnf install -y sshpass \
    && microdnf clean all

6. External References

For upstream Ansible and runtime documentation on execution environment architecture and tooling: