DEV Community

Oleksandr Kuryzhev
Oleksandr Kuryzhev

Posted on Originally published at kuryzhev.cloud

Migrate Playbooks to ansible-core 2.22 Without Breaking Collections

Originally published on kuryzhev.cloud


The scenario

A repository has forty playbooks, a dozen roles, and a CI job that runs pip install ansible or pip install ansible-core with no version pin. ansible-core 2.22 was released on 2026-11-02. An unpinned ansible-core install picks it up on the next build. An unpinned community ansible install picks it up as soon as a community release that depends on it is published, along with whatever bundled collection versions come with it. That is how a routine pipeline run turns into a surprise upgrade of the engine and the modules at once.

Short answer: do not upgrade in place. Record what you run today, pin collections in requirements.yml, install ansible-core 2.22 into a separate virtualenv, and run the same playbooks through both versions in check mode against a canary group. Switch CI and the control node only when the two outputs match. This applies to any team that runs ansible-playbook from a controller or CI runner it manages itself.

The core engine and the collections are versioned separately. The engine upgrade is often the smaller risk, though that depends on what a given release removes. A collection's requires_ansible bound, a removed deprecated option, or a module that used to ship in a bundle are common causes of breakage.

Prerequisites

You need the following before you start:

  • A Git repository with the playbooks and an ansible.cfg you control, so the collections path is explicit.
  • A Python version supported by ansible-core 2.22 on the controller. Check the support matrix in the official Ansible documentation instead of assuming that the newest Python works. Controller and managed-node Python requirements are separate, and both are version-dependent.
  • A canary inventory group, such as two or three hosts that are representative and safe to touch.
  • Read access to the porting guide for the 2.22 release in the same documentation, plus the changelog linked above.

Watch out for the packaging split. If your current setup installs the community ansible package, many collections arrive bundled with it. The ansible-core package ships only ansible.builtin. Moving to ansible-core alone makes every community.*, amazon.aws, or ansible.posix module vanish unless you install those collections explicitly. The steps below handle that.

Skip this migration plan if you run AWX or Ansible Automation Platform. There the engine version is a property of the execution environment image, so rebuild and test that image instead of using pip on a host. The check-mode comparison in step 3 still applies.

Step 1: Record the current state and pin collections

Capture the baseline from the environment that works today. This gives you a diff target and a rollback reference.

# run inside the CURRENT, working environment
ansible --version | tee baseline-version.txt
ansible-galaxy collection list --format yaml > baseline-collections.yml
ansible-config dump --only-changed > baseline-config.txt   # settings that differ from defaults
pip freeze > baseline-pip.txt                              # Jinja2, PyYAML, cloud SDKs

๐Ÿงช Lab โ€” try this in your browser

Now turn the collection list into a pinned requirements.yml. Copy the versions you actually observed in baseline-collections.yml. The names below are examples, and X.Y.Z is a placeholder for your recorded version.

---
collections:
  - name: ansible.posix
    version: "X.Y.Z"      # exact version from baseline-collections.yml
  - name: community.general
    version: "X.Y.Z"
  - name: amazon.aws
    version: "X.Y.Z"

Commit this file and tag the commit, for example pre-core-2.22. Collections are only reproducible when the version is explicit. A range like >=1.0.0 reintroduces the surprise you are trying to remove.

Step 2: Build an ansible-core 2.22 virtualenv next to the old one

Keep the old environment untouched. A parallel virtualenv makes rollback a matter of changing which binary CI calls.

First, in ansible.cfg, point at a project-local collections path. This stops the controller from falling back to user-level or system-level collections by accident:

[defaults]
collections_path = ./collections
interpreter_python = auto_silent

Then create the environment and install the same pinned collections into that path:

python3 -m venv ~/venvs/ansible-2.22
. ~/venvs/ansible-2.22/bin/activate
pip install --upgrade pip
pip install "ansible-core==2.22.0"          # exact pin; widen to a patch range later
ansible --version                            # confirm "ansible [core 2.22.0]"

# install the SAME pinned collections into the project-local path
ansible-galaxy collection install -r requirements.yml -p ./collections

Watch out for shadowed collections. If a different copy of a collection exists in ~/.ansible/collections or a system path, the version that runs may not be the one you pinned. Run ansible-galaxy collection list and read the paths it prints before trusting any test result.

Also install any Python libraries your modules need on the controller from baseline-pip.txt, for example boto3 for amazon.aws. A fresh virtualenv starts empty.

Step 3: Find breakage before a host does

First check what each collection declares about supported core versions. The requires_ansible field in meta/runtime.yml is the documented place for it:

grep -H requires_ansible \
  collections/ansible_collections/*/*/meta/runtime.yml
# a collection that excludes 2.22 needs a newer release; bump its pin deliberately

Then run static checks, which do not touch any host:

ansible-playbook site.yml --syntax-check
pip install ansible-lint "ansible-core==2.22.0"   # if you use it; keep the core pin so pip cannot move it
ansible --version | head -1                       # still "ansible [core 2.22.0]"
ansible-lint
ansible-galaxy collection list                    # every collection path should be under ./collections

Read the porting guide for the release alongside these results. Removed or changed behavior for each version is documented there, and this article does not substitute for it. Any [DEPRECATION WARNING] or [ERROR] output from the syntax check maps to a section of that guide or to a collection changelog.

Next, compare old and new engines in check mode against the canary group:

for v in old new; do
  [ "$v" = old ] && . ~/venvs/ansible-old/bin/activate || . ~/venvs/ansible-2.22/bin/activate
  ansible-playbook site.yml --check --diff --limit canary 2>&1 | tee "run-$v.log"
  deactivate
done
diff <(grep -E 'changed=|failed=' run-old.log) <(grep -E 'changed=|failed=' run-new.log)

This assumes the old environment lives at ~/venvs/ansible-old, so adjust the path to match yours. Check mode is not perfect. In check mode, command and shell tasks are skipped unless they use creates/removes or set check_mode: false. A clean result therefore proves less than it seems.

Step 4: Roll out in stages and keep the way back

Switch CI to the new virtualenv for one non-production pipeline first. Then run a real, non-check pass on the canary group, and only afterwards extend to the rest. Use --limit and serial to bound the blast radius, as in a normal rolling change.

Keep the old virtualenv and the baseline files for at least one full release cycle. Rollback then means pointing the pipeline back at the old interpreter path.

If you bumped any collection pins in step 3, the old engine may not support those newer releases. In that case, also restore requirements.yml from the pre-core-2.22 tag and reinstall it into ./collections with --force.

Once stable, loosen the engine pin to a patch range such as "ansible-core>=2.22,<2.23" in a requirements.txt. Security and bug-fix releases then arrive without a minor-version jump. Collections stay exactly pinned and move only through reviewed pull requests.

Cost to be aware of: two parallel environments, a pinned-collection update routine, and a few extra CI minutes. For a single-playbook hobby setup this is overkill, and a plain upgrade plus a syntax check is reasonable.

Verify and test

Confirm each of these before calling the migration done:

  • ansible --version prints a first line shaped like ansible [core 2.22.0], with config file pointing at your project's ansible.cfg and the python version you intended.
  • ansible-galaxy collection list shows every collection from requirements.yml at its pinned version, under ./collections only. Compare it with baseline-collections.yml.
  • ansible-playbook site.yml --syntax-check exits with code 0 and prints no deprecation warnings you have not triaged.
  • The check-mode recap lines (ok=โ€ฆ changed=โ€ฆ failed=0 unreachable=0) are the same on both engines for the canary hosts. A host that reports changed only on the new engine deserves a look at the diff output.
  • A real run on the canary group is idempotent: a second run reports changed=0 for tasks that were already converged.

If a collection fails to load, the usual causes are a missing Python dependency in the new virtualenv or a collection release that declares an incompatible requires_ansible. The fix is to install the dependency or bump that one collection, not to downgrade the engine immediately.

Where to go from here

Treat ansible-core 2.22 as a change to one pinned component, not a leap of faith. Take a baseline first, pin collections, build a parallel virtualenv, and compare old and new engines in check mode on a canary group. Once the canary is clean, the rest is a controlled switch of one interpreter path. For more runbooks in this style, browse the rest of kuryzhev.cloud. Keep the official porting guide and collection changelogs open while you work, because they are the authority on what changed.

Related

Top comments (0)