requirements.yml and version pinning · Ansible

Version pinning gets filed under tidiness, alongside consistent indentation and sorted lists. It is not tidiness. It is the difference between an automation repository that describes a change and one that describes an intention to run whatever is current.

Here is the whole argument in one sentence. Your repository has not changed since Tuesday. Your run on Thursday does something different. That is what an unpinned dependency buys you, and no amount of review discipline on your own code prevents it, because the change was not in your code.

The file

Read-only / Saferequirements.yml

---
collections:
- name: community.docker
  version: '4.7.0'
- name: ansible.posix
  version: '3.0.0'
- name: community.general
  version: '12.4.0'

roles:
- name: geerlingguy.postgresql
  version: '3.5.2'

Two top-level keys, both optional. collections: and roles: are resolved by different machinery — roles predate collections and use a different index — so a file with both is normal and each half is installed independently.

Configuration changeinstall from the file— Installs the declared collections into a project-local path. This writes Python to disk that later runs as root on managed hosts; it is a configuration change to the controller, not a read-only operation.

$ ansible-galaxy collection install -r requirements.yml -p ./collections

Starting galaxy collection install process
Process install dependency map
Starting collection install process
Downloading https://galaxy.ansible.com/api/v3/plugin/ansible/content/published/collections/artifacts/community-docker-4.7.0.tar.gz to /home/opsuser/.ansible/tmp/ansible-local-1601101soz9l_f/tmpx0j7iwi0/community-docker-4.7.0-zbsncrpu
Installing 'community.docker:4.7.0' to '/home/opsuser/project/collections/ansible_collections/community/docker'
community.docker:4.7.0 was installed successfully
Downloading https://galaxy.ansible.com/api/v3/plugin/ansible/content/published/collections/artifacts/community-library_inventory_filtering_v1-1.1.5.tar.gz to /home/opsuser/.ansible/tmp/ansible-local-1601101soz9l_f/tmpx0j7iwi0/community-library_inventory_filtering_v1-1.1.5-rnua6vrl
Installing 'community.library_inventory_filtering_v1:1.1.5' to '/home/opsuser/project/collections/ansible_collections/community/library_inventory_filtering_v1'
community.library_inventory_filtering_v1:1.1.5 was installed successfully

Read that output again. You asked for one collection and two were installed. The second is a transitive dependency, and it is the subject of the second half of this lesson.

`ansible-galaxy install` runs somebody else's code as root on your fleet

This is worth stating plainly once, in these words, because the command is so ordinary that the fact disappears.

A collection is Python. The modules in it are copied to every managed host in the play and executed there — under become: true in almost every production play, which means as root. The lookup, filter and action plugins in it execute on the controller, which is the machine that holds your SSH keys and your vault password.

So ansible-galaxy collection install <name> is not “adding a library”. It is granting an unreviewed third party root on every host that collection’s modules will touch, plus code execution on the machine that can reach all of them.

That is not an argument against using collections. It is an argument for knowing which version you installed, being able to prove nobody changed it, and having read enough of it to know what it does. The rest of this part is those three things.

The specifier syntax, verified

The version key accepts exact versions and comma-separated range expressions. An exact pin:

Read-only / Safethe pin this course teaches

collections:
- name: community.docker
  version: '4.7.0'

A range resolves at install time to whatever is newest inside it:

Configuration changea range, resolved today— Installs community.crypto with a range specifier. The version that lands is the newest release inside the range on the day the command runs.

$ ansible-galaxy collection install -r req.yml -p ./gx --no-deps

Downloading https://galaxy.ansible.com/api/v3/plugin/ansible/content/published/collections/artifacts/community-crypto-2.26.9.tar.gz to /home/opsuser/.ansible/tmp/ansible-local-182176gyjuqyyk/tmpf9q18xw4/community-crypto-2.26.9-mk4xhvbf
Installing 'community.crypto:2.26.9' to '/home/opsuser/project/gx/ansible_collections/community/crypto'
community.crypto:2.26.9 was installed successfully

The file said '>=2.0.0,<3.0.0'. What landed was 2.26.9 — because that is the newest 2.x today. Run the same file next quarter and you get 2.27.something, from the same unchanged commit. The range is a policy; the pin is a fact.

Not every syntax you have met elsewhere is accepted. The npm-style caret is not:

Read-only / Safea specifier that is rejected— Attempts an install with a caret range. The resolver rejects it before contacting the server.

$ ansible-galaxy collection install -r req-caret.yml -p ./gx3

[ERROR]: Non integer values in LooseVersion ('^2.0.0')
Starting galaxy collection install process
Process install dependency map

Use >=, >, <=, <, !=, ==, *, and commas to combine them. '*' means “any”, which is also what you get when you omit version entirely — and it is the state this lesson exists to argue against.

The flags that matter

Flag	What it does	When you want it
`-r requirements.yml`	Install everything in the file	Always, in a repository
`-p ./collections`	Install to this path instead of the first configured one	Always, on a shared controller
`-U`, `--upgrade`	Upgrade installed collections, and their dependencies unless `--no-deps`	Deliberately, as its own reviewed change
`-n`, `--no-deps`	Do not install declared dependencies	Building an offline bundle, or when you pin the dependencies yourself
`--pre`	Consider pre-release versions, which are ignored by default	Testing an upcoming release, never in production
`-f`, `--force`	Overwrite an existing collection	Repairing a partial install
`--offline`	Install from local tarballs without contacting any server	Air-gapped install; lesson 7

The pin that does not hold

Back to the two collections from one request. Where did the second one come from? From inside the first one’s manifest:

Read-only / Safethe dependency declaration— Reads the collection_info block out of the installed collection's MANIFEST.json, which records what it declared about itself at build time.

$ python3 -c "import json; m=json.load(open('collections/ansible_collections/community/docker/MANIFEST.json')); print(m['collection_info']['dependencies'])"

{'community.library_inventory_filtering_v1': '>=1.0.0'}

>=1.0.0. Unbounded. You pinned community.docker to exactly 4.7.0, and the collection you pinned brings in a second collection with a range that will resolve to whatever is newest whenever the install runs.

Your requirements.yml is pinned. Your controller is not.

Finding what you actually installed

The fix is mechanical. Install once, list what landed, and pin all of it:

Read-only / Safethe real installed set— Lists everything on the project collections path as JSON, including collections that arrived as transitive dependencies.

$ ansible-galaxy collection list -p ./collections --format json

{"/home/opsuser/project/collections/ansible_collections": {"community.docker": {"version": "4.7.0"}, "community.library_inventory_filtering_v1": {"version": "1.1.5"}}}

Then write every line of that into requirements.yml with an exact version, and install with --no-deps so the resolver takes your list rather than re-deriving one:

Read-only / Saferequirements.yml, fully pinned

---
# Direct dependencies.
collections:
- name: community.docker
  version: '4.7.0'

# Transitive: pulled in by community.docker, which declares it as
# '>=1.0.0'. Pinned here so a rebuild reproduces this controller
# rather than today's newest.
- name: community.library_inventory_filtering_v1
  version: '1.1.5'

Configuration changeinstall exactly this list and nothing else

ansible-galaxy collection install -r requirements.yml -p ./collections --no-deps

The comment is not decoration. In eighteen months somebody will find a collection in that file that no playbook imports and delete it, and the comment is the only thing that stops them.

How the resolver decides, and why a conflict is a hard error

ansible-galaxy uses resolvelib, the same dependency resolution library pip uses. It builds a dependency map from every declared requirement — yours plus every collection’s own — and looks for an assignment of versions that satisfies all of them simultaneously.

Two behaviours follow that surprise people:

A conflict fails the whole install, not just the conflicting collection. If you pin community.library_inventory_filtering_v1 to 1.0.0 and community.docker 4.7.0 requires >=1.0.0, that is fine. If a future community.docker requires >=2.0.0 and your pin says 1.1.5, the install fails and nothing is written. That is the correct behaviour: a half-installed dependency tree is worse than none.

-i/--ignore-errors does not ignore this. Its documentation is explicit — it continues past install errors for individual collections but “will not ignore dependency conflict errors”. There is no flag that makes an unsatisfiable tree install anyway, which is a good thing to know before you go looking for one at 2am.

When you hit a genuine conflict, the resolution is to widen or move your pin deliberately, in a commit, with the conflicting requirement quoted in the message.

What happens if a pinned version is deleted from Galaxy?

It can happen: a release is yanked for a security defect, a namespace changes hands, a collection is deprecated and removed.

The symptom is an install that fails on a version that worked last week, from an unchanged file. The controller you have keeps working; the controller you rebuild does not, which means you discover it during recovery.

Three defences, in increasing order of seriousness:

Keep the tarballs. ansible-galaxy collection download produces an artefact directory you can install from offline. Store it with your backups, not only on the controller. Lesson 7 covers this.
Run a private mirror or a pull-through cache, so your controller’s supply is not a public service’s uptime and retention policy. Also lesson 7.
Build execution environments — a container image with the collections already installed — so the artefact you restore is the whole environment rather than a shopping list. Part L.

The general principle is the one every package ecosystem learns the same way: a requirements file is a description of an environment, not a copy of one. If losing the upstream would hurt, keep a copy.