Enabling the Ansible Runner Capability on the Site Controller

The Site Controller can execute Ansible tasks, typically provided via the Extension mechanism (application, workflow and action extensions all use it for their Ansible tasks). It is disabled by default for security reasons and must be enabled.

The ms-agent service runs each Ansible task in an ephemeral execution environment container, launched via the Docker socket. Enabling the capability is done on the ms-agent service.

On the Site Controller VM execute:

Create the job and archive directories:

mkdir -p /opt/metalsoft/ansible-jobs /opt/metalsoft/ansible-archives

Enable the capability on the ms-agent service: Edit the docker-compose.yaml file and add the following to the ms-agent service definition — the Ansible Runner entries go in the environment section (alongside the other capability flags such as COMMAND_EXECUTION, HTTP_REQUEST, etc.), plus the extra volumes:

services:
  ms-agent:
    ...
    group_add:
      - "${DOCKER_GID:-110}"
    environment:
      ...
      ## Capabilities:
      - ANSIBLE_RUNNER=enabled
      - ANSIBLE_RUNNER_HOME=/opt/metalsoft/ansible-jobs
      - ANSIBLE_RUNNER_ARCHIVES_FOLDER=/opt/metalsoft/ansible-archives
      - ANSIBLE_RUNNER_RUN_UID=1000
      - ANSIBLE_RUNNER_RUN_GID=1000
      - ANSIBLE_RUNNER_EXECUTION_ENV=${ANSIBLE_RUNNER_EXECUTION_ENV:-ee-default:latest}
      - ANSIBLE_RUNNER_SOCKET_PATH=${ANSIBLE_RUNNER_SOCKET_PATH:-/var/run/docker.sock}
      - ANSIBLE_RUNNER_HOME_HOST=${ANSIBLE_RUNNER_HOME_HOST:-/opt/metalsoft/ansible-jobs}
      - ANSIBLE_RUNNER_DEBUG_KEEP_CONTAINER=0
    volumes:
      ...
      - /opt/metalsoft/ansible-jobs:/opt/metalsoft/ansible-jobs
      - /opt/metalsoft/ansible-archives:/opt/metalsoft/ansible-archives
      - ${ANSIBLE_RUNNER_SOCKET_PATH:-/var/run/docker.sock}:${ANSIBLE_RUNNER_SOCKET_PATH:-/var/run/docker.sock}

The group_add entry gives the agent access to the Docker socket (set DOCKER_GID to the host’s docker group id) — required to launch the execution environment containers. To find the group id, run the following on the Site Controller host:

getent group docker | cut -d: -f3

or check the socket’s group directly:

stat -c '%g' /var/run/docker.sock

The environment variables:

Variable	Purpose
`ANSIBLE_RUNNER`	`enabled` turns the capability on.
`ANSIBLE_RUNNER_HOME`	Transient job directory (bundle, inventory, variables and logs per task).
`ANSIBLE_RUNNER_HOME_HOST`	The same directory as seen on the host — mounted into the ephemeral execution environment containers.
`ANSIBLE_RUNNER_ARCHIVES_FOLDER`	Where downloaded Ansible bundle archives are stored.
`ANSIBLE_RUNNER_RUN_UID` / `ANSIBLE_RUNNER_RUN_GID`	The uid/gid the tasks run as inside the execution environment container.
`ANSIBLE_RUNNER_EXECUTION_ENV`	The default execution environment image used for tasks that do not select their own via the task `ee` option.
`ANSIBLE_RUNNER_SOCKET_PATH`	The Docker socket used to launch the execution environment containers.
`ANSIBLE_RUNNER_DEBUG_KEEP_CONTAINER`	Set to `1` to keep the execution environment container after a run, for debugging. Default `0`.

Restart the site controller:

docker compose up -d

Verify that the capability is active: In the Admin go to Sites > site > Site Controllers and look for the ANSIBLE_RUNNER=true entry.

Changing the default execution environment

Each Ansible task runs in the image set by ANSIBLE_RUNNER_EXECUTION_ENV unless the task selects its own image via the ee option (an OciImage asset in the extension definition). To add dependencies for all extensions at the site, build a custom execution environment image and point ANSIBLE_RUNNER_EXECUTION_ENV at it; for extension-specific dependencies prefer a per-task image instead.

See Execution environments for how to build an image (Dockerfile or ansible-builder) and how to distribute it — including air-gapped sites, where the image tarball is transferred and loaded with docker load into a registry reachable by the Site Controller.