A controller you can rebuild identically · Ansible

Here is the test this part of the course is built around, and it is a short one.

Take the repository to a second machine. Build a controller from what is in it. ansible --version and ansible-galaxy collection list must produce the same answers as the first machine.

If they do, you have a controller environment. If they do not, you have a machine that happens to work, and the difference will surface at the least convenient moment — usually as a CI job that fails on code a human just tested successfully.

Two files, because there are two mechanisms

Pinning Ansible needs two files, and forgetting one is the commonest reproducibility gap in an otherwise disciplined repository.

estate/
├── requirements.txt      # ansible-core, via pip
├── requirements.yml      # collections, via ansible-galaxy
├── ansible.cfg
├── inventory/
└── playbooks/

requirements.txt pins the runtime and ansible.builtin — because ansible.builtin is not a separately installed collection, its version is the ansible-core version:

# requirements.txt
ansible-core==2.21.3

requirements.yml pins everything else:

# requirements.yml
---
collections:
  - name: ansible.posix
    version: '2.1.0'
  - name: community.general
    version: '11.4.0'

Reading `requirements.yml` properly

The collection entry has more in it than a name and a version, and the options change what “pinned” means.

requirements.ymlA collection requirements file with the options that decide how strong the pin actually is.

collections[].name: name: community.general
collections[].version: version: '11.4.0'
collections[].source: source: https://galaxy.ansible.com
roles: roles:
  - name: geerlingguy.postgresql
    version: 3.5.4

01collections[].name= name: community.general
The fully qualified collection name, namespace and collection. This is what a playbook writes as `community.general.<module>`.
Production: Every module your playbooks call belongs to some collection. Run `ansible-doc <module>` to find which one before assuming it is ansible.builtin.
⚠ Listing a role name here. Roles go under a separate `roles:` key in the same file; collections and roles are different install mechanisms.
02collections[].version= version: '11.4.0'
An exact version. ansible-galaxy installs precisely this and nothing else.
Production: Quote it. Unquoted, a version like 2.10 is parsed by YAML as the float 2.1, and you will install a version you did not ask for.
⚠ Writing `version: '>=11.0.0'`. That is a valid range and a legitimate choice, but it is not a pin - two machines built a month apart will get different code.
03collections[].source= source: https://galaxy.ansible.com
Which Galaxy server to fetch from. Defaults to the public Galaxy unless GALAXY_SERVERS is configured.
Production: An estate with an internal Automation Hub or a proxy sets this, or configures servers in ansible.cfg so the file stays environment-neutral.
⚠ Hardcoding an internal URL in a repository that also builds on a laptop with no VPN. The build then fails in a way that looks like a network fault.
04roles= roles: - name: geerlingguy.postgresql version: 3.5.4
Standalone roles from Galaxy, a separate install mechanism that predates collections and still works.
Production: Pin these exactly as you pin collections. A standalone role is code that runs against your fleet with no version guard unless you write one.
⚠ Adding `-p ./roles` to `ansible-galaxy install -r requirements.yml`. That flag is `--roles-path`, and supplying it narrows the command to roles only, silently skipping the collections section of the same file.

The flag that quietly halves the install

ansible-galaxy install -r requirements.yml installs both sections of the file — roles into ROLES_PATH, collections into COLLECTIONS_PATH. Its own help text says so, and it is the convenient form.

The trap is -p. On ansible-galaxy install, -p is --roles-path, not a general destination, and the help text is explicit about the consequence: supplying it “will result in only roles being installed”. A build script that says ansible-galaxy install -r requirements.yml -p ./roles looks like it is placing everything neatly in the repository and is in fact skipping every collection in the file.

The failure arrives later as a module-not-found error that reads like a typo in a playbook. If you want both in repository-local paths, use the two explicit commands — ansible-galaxy role install and ansible-galaxy collection install — each with its own path.

Building the environment

Five commands, and they belong in a script in the repository rather than in anyone’s shell history.

Configuration changebin/build-controller - the whole thing— Creates the venv, installs the pinned runtime, installs the pinned collections into a repository-local path, and prints the manifest for comparison. Touches nothing outside the venv and the collections directory, and nothing at all on the managed fleet.

#!/usr/bin/env bash
set -euo pipefail

VENV=${VENV:-/opt/estate/venv}
REPO=$(cd "$(dirname "$0")/.." && pwd)

python3.12 -m venv "$VENV"
"$VENV/bin/pip" install --upgrade pip
"$VENV/bin/pip" install -r "$REPO/requirements.txt"
"$VENV/bin/ansible-galaxy" collection install \
  -r "$REPO/requirements.yml" -p "$REPO/collections"

"$VENV/bin/ansible" --version
"$VENV/bin/ansible-galaxy" collection list

The install of collections is genuinely a CONFIGURATION action, not a read-only one. It does not touch a managed host, but it changes what the next playbook run will execute on every managed host — which is a change with a fleet-wide blast radius, made on the controller.

Point Ansible at the repository-local collections directory so the result is a property of the repository rather than of the user’s home directory:

# ansible.cfg
[defaults]
collections_path = ./collections

Installed to a path Ansible does not read

ansible-galaxy collection install -p ./collections will warn you when that path is not in the configured collections path — and then install there anyway:

[WARNING]: The specified collections path '/home/ops/estate/collections' is not part of the configured Ansible collections paths '/home/ops/.ansible/collections:/usr/share/ansible/collections'. The installed collection will not be picked up in an Ansible run, unless within a playbook-adjacent collections directory.

Everything reports success. The collections are on disk. Ansible will not load them, and your next run fails with a module-not-found error pointing at a collection you can see in the filesystem.

Set collections_path in ansible.cfg and the warning disappears because the situation it describes no longer exists.

Verifying the build

The manifest is two commands, and comparing them between machines is the test.

Read-only / Safemanifest, part one: the runtime— Compare the core version, the python version and the collection location between two controllers. All three must match; the executable and module paths may legitimately differ if the venv lives elsewhere.

$ ansible --version

ansible [core 2.21.3]
config file = /home/ops/estate/ansible.cfg
configured module search path = ['/home/ops/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
ansible python module location = /opt/estate/venv/lib/python3.14/site-packages/ansible
ansible collection location = /home/ops/estate/collections
executable location = /opt/estate/venv/bin/ansible
python version = 3.14.4 (main, Jun 18 2026, 14:25:02) [GCC 15.2.0] (/opt/estate/venv/bin/python3)
jinja version = 3.1.6
pyyaml version = 6.0.3 (with libyaml v0.2.5)

Read-only / Safemanifest, part two: the collections— With collections_path pointing at the repository directory, this lists exactly what requirements.yml asked for. Two machines built from the same commit must produce byte-identical output here.

$ ansible-galaxy collection list

# /home/ops/estate/collections/ansible_collections
Collection        Version
----------------- -------
ansible.posix     2.1.0
community.general 11.4.0

Two collections, both at the versions in the file. On a machine built from the distribution’s community package, the same command lists ninety-one collections at versions nobody chose. That is the difference the pin buys, and it is visible in one command.

Make the comparison mechanical rather than visual:

Read-only / Safethe two-machine test as a diff— Captures both halves of the manifest on each controller and diffs them. Runs nothing against the fleet. The grep drops the paths, which are allowed to differ between machines.

ansible --version | grep -E 'core|python version|jinja' > /tmp/manifest-a.txt
ansible-galaxy collection list >> /tmp/manifest-a.txt

# on the second controller, produce /tmp/manifest-b.txt the same way, then:
diff /tmp/manifest-a.txt /tmp/manifest-b.txt && echo "controllers agree"

What is still not pinned

Two files is a large improvement and it is not complete. Four things remain loose, in rough order of how often they cause trouble.

The controller’s Python. requirements.txt pins ansible-core; it does not pin the interpreter the venv was built from. python3.12 -m venv on one machine and python3.14 -m venv on another produce two different controllers from the same file. Name the interpreter in the build script, and record it — a comment in requirements.txt is enough for a small estate, a base-image tag for a larger one.

Transitive Python dependencies. ansible-core==2.21.3 pins Ansible and lets pip resolve jinja2, cryptography, pyyaml, packaging and resolvelib to whatever is newest at build time. Two builds a month apart get different Jinja. For a controller that must be byte-reproducible, generate a fully pinned file:

Read-only / Safecapture the whole resolved tree— Prints every installed package and its exact version from the current environment. Redirect it into a locked requirements file that a later build installs verbatim.

/opt/estate/venv/bin/pip freeze

Read-only / Safewhat a pinned controller's dependency tree actually is— Nine packages. This is the entire runtime surface of an ansible-core controller - small enough that pinning all of it is not the burden people expect.

$ pip freeze

ansible-core==2.21.3
cffi==2.1.1
cryptography==50.0.0
Jinja2==3.1.6
MarkupSafe==3.0.3
packaging==26.3
pycparser==3.0
PyYAML==6.0.3
resolvelib==1.2.1

Collection dependencies. A collection may depend on another collection, and ansible-galaxy will install that dependency at whatever version satisfies the constraint. ansible-galaxy collection list shows you what actually landed — which is why the manifest is the list, not the requirements file.

Roles installed outside the file. Anything a person installed by hand on the controller is invisible to the repository and will not exist on machine two. The two-machine test catches this, which is most of why it is worth running.

Under the hood

ansible-galaxy collection install resolves the requirement graph with resolvelib — the same resolver family pip uses — then downloads a tarball per collection from the Galaxy API and unpacks it into <path>/ansible_collections/<namespace>/<name>/.

Two details follow from that layout and both matter operationally:

The installed tree contains a MANIFEST.json recording the version. That file is what ansible-galaxy collection list reads. It is not derived from requirements.yml, which is exactly why the list is the manifest and the requirements file is only a request.
Collections are plain directories of YAML and Python. They can be committed to your repository, vendored, and reviewed in a pull request. For an estate that must build without reaching Galaxy — an air-gapped controller, or a CI runner with no egress — vendoring is the mechanism, and the trade is that you now own the upgrade.

ansible-galaxy writes its download temporaries under ~/.ansible/tmp/ regardless of -p, so a controller with a locked-down home directory needs that path writable even though the result lands elsewhere.

What happens if you skip the second machine?

Nothing, for a while. That is the problem.

A controller assembled by hand works perfectly for the person who assembled it, because every implicit dependency they added is present. The environment degrades into documentation nobody wrote: it is correct, it is unrecorded, and it exists in one place.

The bill arrives in one of three forms, and all three are avoidable by running the test once a month:

The CI runner. A pipeline is added, builds the controller from the repository, and fails on a collection nobody realised was installed manually two years ago.
The new colleague. Their first run behaves differently, and the team spends a day deciding whose machine is right.
The lost controller. The machine is rebuilt, replaced, or has its disk fail. Whatever was not in the repository is gone, and you find out which parts those were under time pressure. Recovering a lost controller is a subject of its own later in the course; the cheapest version of that recovery is having practised the build.