Ansible / Intermediate: reuse, secrets, and scoped validation / Lesson 10

Pin collections and execution dependencies

Separate FQCN selection, collection versions, controller dependencies, target requirements, and reproducible execution environments.

About 4 min readContent reviewed 2026-10-25

On this page

Lesson goals

Explain collection namespaces and installation boundaries.
Record compatible engine, Python, and plugin dependencies.
Treat automation content as reviewed executable supply-chain input.

A collection is independently versioned content

A collection uses a namespace and name and can contain modules, plugins, roles, and metadata. FQCNs identify content unambiguously, but they do not pin which installed version provides it. The engine’s builtin content and separately installed collections have different distribution and maintenance boundaries. A project that works on one controller can fail on another because collection search paths or versions differ. Record the resolved content and its source instead of assuming a short module name always selects the same code. Do not install a collection merely to test a teaching example.

A requirements file expresses dependency intent

A collection requirements file can specify exact versions or supported ranges according to the documented installer syntax. Choose a project policy that balances reproducibility and reviewed updates, then preserve the actual resolved artifact set. An open range can resolve differently later. The example pins the ansible.posix version shown in its reviewed official collection documentation; it is not a command to download or a claim about compatibility with every target. Transitive collection dependencies, signatures where supported, provenance, and offline artifact handling belong in the same dependency review.

yaml Illustrative exact collection requirement

collections:
  - name: ansible.posix
    version: '2.2.2'

Official ansible.posix documentation reviewed on the course date identifies version 2.2.2. The manifest was parsed as YAML only; no installer, Galaxy request, or package operation was executed.

Controller and target Python are different dependency questions

The controller requires a Python version supported by the selected ansible-core release and any controller-side plugins. Managed nodes can require another supported interpreter or a platform-specific transport, while some modules operate through APIs without executing Python on the target device. Module documentation can add dependencies beyond the engine’s broad support matrix. An execution environment can package controller-side runtime and collection content, but it does not automatically satisfy every remote dependency or secure every credential. Verify the complete matrix and avoid presenting one container image as universal portability.

Compare declared and observed versions explicitly

A simple offline equality check can illustrate drift from an exact project lock. It is not a package resolver and must not pretend to evaluate arbitrary semantic-version constraints. In a real authorized workflow, record engine version, Python interpreter, resolved collection path/version, and plugin requirements without exposing secrets. A successful YAML parse does not show that the collection is installed or that its modules are importable. Keep dependency validation before target effects and report unavailable prerequisites as a clear failure, not a later unexplained module-not-found error.

python Check an exact dependency fixture without installation

declared = {'ansible.posix': '2.2.2'}
observed_fixture = {'ansible.posix': '2.2.2'}
print('synthetic_lock_matches=' + str(declared == observed_fixture))
print('collection_installed=not-tested')

Expected output

synthetic_lock_matches=True
collection_installed=not-tested

The result compares declared dictionaries only. It does not inspect local collection paths, resolve dependencies, import a module, or contact a content server.

Upgrade content through a tested change boundary

An engine or collection update can change argument validation, templating, result fields, platform support, and deprecation behavior. Read porting guides and collection changelogs for the actual transition, not just the newest release announcement. Preserve a reproducible previous dependency set and test the project’s public contracts on disposable targets when authorized. Avoid changing engine, collections, inventory sources, and application configuration simultaneously without a plan that can distinguish causes. The course performs no installation or runtime upgrade; it teaches how a dependency decision becomes concrete, reviewable, and reversible.

Common errors and fixes

FQCN is assumed to pin a version

Why it happens: Identity and artifact version were conflated.
How to fix it: Record explicit dependency versions and resolution.
Prevent it next time: Keep a reviewed project dependency manifest.

Controller packaging is called complete target support

Why it happens: Remote interpreter and module requirements were omitted.
How to fix it: Validate both runtime sides and module dependencies.
Prevent it next time: Maintain a platform-specific support matrix.

An open version range is called reproducible

Why it happens: Future resolution can select different artifacts.
How to fix it: Preserve the resolved set or use reviewed exact constraints.
Prevent it next time: Test dependency updates as explicit changes.

Check your understanding

1. What remains unproved after a requirements YAML file parses?

Show worked solution

Installation, source authenticity, dependency resolution, compatibility, plugin import, target requirements, and execution behavior remain unproved. A parser check is valuable syntax evidence but must be labeled at that boundary.

2. Why should an engine upgrade and a collection upgrade be recorded separately?