_{Support maintenance, testing, and documentation. Sponsorship is optional.}

Ansible Controller

Run Ansible playbooks in Docker, with your files on the host.

Detailed guide · Architecture · Mesh · GitLab integration · Support · Contact

An Ubuntu 26.04 container with Ansible, OpenSSH, and Windows/WinRM support. Keep playbooks, inventory, and credentials on your machine and mount them into the controller. No host Ansible installation is needed. All three images below are published for amd64 and arm64 on Docker Hub and as ghcr.io/allamiro/<image-name>.

Choose how to run

There are two ways to run it, using three published images. Start with a single deployment if the controller can reach all your targets, and add the mesh only for networks it cannot reach. GitLab integration is optional for either mode.

Image on Docker Hub	Purpose and where it runs
ansible-controller	Standalone control host. Runs playbooks directly against reachable SSH or WinRM targets.
ansible-orchestrator	Mesh control host. Includes the controller runtime and dispatches signed jobs through Receptor ingress sidecars to execution nodes.
ansible-execution-node	Inside each target network. Runs mesh jobs against local targets and connects outbound to the control host; no running SSH server.

Single deployment

Use this when the controller has a network route to every target: a lab, a small environment, or a management network. One ansible-controller container runs the playbooks itself.

• Run playbooks with make run, docker exec, or SSH on host port 2222.
• Keep your files on the host. Configuration, playbooks, SSH keys and logs are mounted into the container.
• Reach targets directly: Linux over SSH and Windows over WinRM.
• GitLab is optional. A CI job calls the controller over restricted SSH, and the controller fetches the reviewed commit.

To set it up, follow the quick start below.

Distributed deployment (mesh)

Use this when some targets sit in networks the control host cannot reach, such as a DMZ, an OT segment or a remote site. The ansible-orchestrator sends signed work to an ansible-execution-node placed inside each of those networks.

• Nodes connect out. Each execution node opens mTLS connections to two Receptor ingresses on the control host (ports 27199 and 27200). Nothing connects into the remote networks.
• Every job is signed. The ingresses sign each job before sending it over those connections, and nodes refuse unsigned work.
• Targets stay local. Each node runs playbooks against hosts in its own network and returns the results.
• GitLab stays on the control side. It never contacts execution nodes.

To set it up, follow the mesh guide.

Quick start

You need Docker Engine, Docker Compose 2.17 or newer, Git, and OpenSSH tools on the host. Run these commands from the repository root. Replace 192.0.2.10 and deploy with your server and SSH account.

1. Clone and prepare an SSH key. For existing keys or SSH agent forwarding, see the detailed guide.

git clone https://github.com/allamiro/ansible-controller.git
cd ansible-controller
mkdir -p ssh && chmod 700 ssh
ssh-keygen -t ed25519 -C "ansible-controller" -f ssh/id_ed25519 -N ""
ssh-copy-id -i ssh/id_ed25519.pub deploy@192.0.2.10

2. Set your inventory in configs/inventory/hosts.ini:

[all]
web01 ansible_host=192.0.2.10 ansible_user=deploy

[all:vars]
ansible_ssh_private_key_file=/home/ansible/.ssh/id_ed25519

3. Build, start, and test connectivity. The included Compose file builds the controller from this checkout.

docker compose up -d --build --wait
docker exec -it ansible-controller \
  ansible-playbook /configs/playbooks/ping.yml -e ansible_become=false

A successful run returns pong; this connectivity check does not require sudo. Add your own playbooks under playbooks/; they are available inside the container at /configs/playbooks/. The full quick start covers custom playbooks and the optional Make helpers.

SSH host-key checking

The shipped configuration disables managed-host key verification for lab use. Before production, follow the managed known-hosts procedure. Use make preflight (requires Make) to check readiness and make preflight STRICT=1 to also flag risky settings. Container startup and docker exec run as root; SSH logins use the ansible account.

GitLab: review, sync, then execute

GitLab CE can manage project review and deployment for either execution mode. For mesh and the project template, the controller syncs an exact commit without running Ansible, then a separate manual deployment executes the verified snapshot. You can require a manual release before sync as well. These are voluntary operator decisions about deployment, unrelated to sponsorship or fleet size.

Start with the project lifecycle guide to create a project, connect its runners and environment, choose both approval gates, read reports, and handle upgrades or recovery. The bootstrap seed's standalone deploy-direct job combines fetch and execution; the reusable project template uses separate sync and execution for either mode. GitLab remains optional.

Common use cases

Your situation	Start here
A workstation or one reachable server network	Standalone quick start; edit mounted playbooks without rebuilding.
Branch offices, private networks, or several reachability zones	Mesh setup; place nodes near targets and use separate environment inventories per zone.
A team needs reviewed Git changes and approval before sync and execution	Project setup and approvals.
A rollout affects 100+ inventory hosts	Canary and batch rollout; pool selection does not split an inventory automatically.
Windows, cloud inventory, or encrypted credentials	Controller reference; provision dependencies and trust in the runtime that executes Ansible.
A job disconnected or its outcome is unclear	Results and recovery; collect the original job before considering another execution.

Documentation

Guide	What you will find
Detailed controller README	Images and tags, commands, Galaxy roles, cloud inventory, Windows, Vault, SSH, logs, and troubleshooting checks.
Architecture and diagrams	Host mounts, direct execution, mesh connections, certificate enrollment, and the GitLab boundary.
Project lifecycle and use cases	Create projects, sync GitLab revisions, approve execution, roll out in batches, read reports, and upgrade.
Mesh deployment · Runbook	Execution nodes, redundant ingress, deployment, upgrades, and recovery.
External CA	Use your organization's certificate authority for mesh identities.
GitLab walkthrough	Project setup, permissions, reviewed commits, and manual deployments.
Releases and image signatures	Versioning, registry tags, and cosign verification.

License and support

This project's source is licensed under the Apache License 2.0. Bundled third-party software retains its own licenses.

Capability or term	Community controller	Community mesh	Enterprise support services
Software	Standalone Ansible controller	Orchestrator and execution nodes	Uses the same community software
Execution	Direct SSH / WinRM	Signed work over Receptor; nodes reach targets	Deployment planning and operational assistance by agreement
GitLab sync, approval and reports	Optional integration	Optional integration	Integration/setup assistance by agreement
Host limit / 100+ systems	Unlimited	Unlimited	Fleet size helps scope the work, not license enforcement
Software license	Apache-2.0 project source	Apache-2.0 project source	No replacement software license; service terms agreed separately
Payment / response commitments	Free; voluntary sponsorship	Free; voluntary sponsorship	Scope, fees and response commitments agreed before work starts

EE status: there is no separate Enterprise Edition or proprietary mesh license available today. Here, enterprise support means optional services. It does not unlock features or remove a host cap. “Execution environment” is a different Ansible term and does not indicate a paid license. See support and licensing details.

The community controller and mesh are free to use with no host limit or purchase requirement. Sponsorship is voluntary. For deployment assistance, contact the maintainer and see SUPPORT.md for scope and terms. Sponsorship alone does not include a support contract or guaranteed response.

Contributing

Bug reports, documentation improvements, and fixes are welcome. Open an issue before a PR, then follow the contribution and validation instructions.