kolla-ansible prechecks fails with "Ansible version should be between ...": the wrong Ansible or collections on the deploy host¶
Symptom¶
kolla-ansible prechecks stops at Checking Ansible version, after the role's earlier checks (inventory, host OS,
time, ports, services), with:
TASK [prechecks : Checking Ansible version] ************************************
fatal: [localhost]: FAILED! => {
"assertion": "ansible_version_host is version(ansible_version_min, '>=')",
"changed": false,
"evaluated_to": false,
"msg": "Ansible version should be between 2.19 and 2.20. Current version is 2.18.10 which is not supported."
}
Captured on an all-in-one lab (Kolla-Ansible 22.2.0) with ansible-core 2.18.10 installed into the virtual
environment; the run stopped after 8 seconds with failed=1. The task and the message are those of
ansible/roles/prechecks/tasks/package_checks.yml in Kolla-Ansible 2026.1; the bounds come from
ansible_version_min: '2.19' and ansible_version_max: '2.20' in the prechecks role.
Related forms of the same problem, on any command (deploy, reconfigure, upgrade), when prechecks were skipped:
- Ansible stops on a module, filter or plugin it cannot find in a collection (
couldn't resolve module/action, or a filter that "is not available"); - a play fails on syntax or keywords that the installed
ansible-coredoes not know, or that a newer one removed.
The exact wording of those Ansible errors depends on the ansible-core version and is not quoted here.
Impact¶
Nothing has been changed on the hosts: the run stops on the deploy host's own tools. The platform keeps running. The risk is in the fix: installing a different Kolla-Ansible or Ansible into the wrong environment, and then running it against production.
Quick checks¶
On the deploy host, read-only:
# 1. Which kolla-ansible and which ansible-playbook will run?
command -v kolla-ansible ansible-playbook ansible-galaxy
ansible-playbook --version | head -1
# 2. What is installed in the virtual environment Kolla-Ansible runs from?
/path/to/venv/bin/pip show kolla-ansible ansible-core | grep -E '^(Name|Version)'
# 3. Which collections Ansible sees, and from where
ansible-galaxy collection list 2>/dev/null | grep -E '^#|openstack.kolla|community.docker|ansible.utils|community.general'
The problem is confirmed when ansible-playbook is not the one of the virtual environment, or its version is outside
what the Kolla-Ansible release requires, or the collections listed are not those Kolla-Ansible installed.
Diagnosis¶
Three facts from the 2026.1 code explain most cases:
- Kolla-Ansible runs
ansible-playbookfrom thePATH. The CLI builds the command with the bare nameansible-playbook(kolla_ansible/ansible.py). If the virtual environment is not activated andkolla-ansibleis called by its full path, theansible-playbookfound first in thePATHmay be a system package or another virtual environment's. - Each release pins an
ansible-corerange. 2026.1 requiresansible-core>=2.19,!=2.19.0,<2.21(requirements.txt), and its prechecks accept 2.19 and 2.20. Apip installof Kolla-Ansible installs a matchingansible-coreinto its own environment; installing Ansible separately, or upgrading Kolla-Ansible across a series without following the operating guide's step foransible-core, breaks that. kolla-ansible install-depsinstalls the Galaxy collections at user level. It runsansible-galaxy collection installwith Kolla-Ansible'srequirements.ymlandrequirements-core.ymland no collections path (kolla_ansible/utils.py), so they land in Ansible's default collections path, normally under the user's home directory, shared by every virtual environment of that user. Two Kolla-Ansible releases on one deploy host, for example during an upgrade, share them, and the lastinstall-depswins.
Possible causes¶
Cause 1: the virtual environment is not active¶
kolla-ansible runs, but ansible-playbook comes from elsewhere. Tell it apart: command -v ansible-playbook is not
in /path/to/venv/bin/. If there is no other ansible-playbook in the PATH, kolla-ansible called by its full
path stops at once, before any play (seen on the lab):
Pre-deployment checking
[Errno 2] No such file or directory: 'ansible-playbook'
Cause 2: the wrong ansible-core in the virtual environment¶
The environment has an ansible-core outside the release's range, after a manual install or a partial upgrade. Tell
it apart: pip show ansible-core in the environment gives a version outside 2.19–2.20 for 2026.1.
Cause 3: collections from another release, or none¶
install-deps was not run after installing or upgrading Kolla-Ansible, or another release's install-deps ran
later for the same user. Tell it apart: the versions in ansible-galaxy collection list do not satisfy the bounds in
/path/to/venv/share/kolla-ansible/requirements-core.yml, or the openstack.kolla collection is missing or comes
from another release. That collection is installed from Git (requirements.yml names ansible-collection-kolla at
stable/2026.1 for 2026.1): its branch, not a version range, must match the release. On the lab,
ansible-galaxy collection list showed it as openstack.kolla 1.0.0, which does not name the branch, and unlike the
Galaxy collections it has no .info directory next to it; rerunning install-deps from the right environment is
the way to be sure.
Resolution¶
For cause 1¶
Activate the environment before any kolla-ansible command, in every shell, script and scheduled job:
source /path/to/venv/bin/activate
For cause 2¶
Install the range the release requires into the environment. The range below is the one of the release's
requirements.txt; the operating guide writes a looser <2.20.99 bound in its step for skip-level (SLURP)
upgrades only:
⚠️ State-changing. Changes the Python packages of the deploy host's virtual environment only; nothing on the OpenStack hosts. Undo: install the previous version back with the same command. Do it outside a running
kolla-ansiblecommand.
source /path/to/venv/bin/activate
pip install 'ansible-core>=2.19,!=2.19.0,<2.21' # the 2026.1 range; read requirements.txt of your release
A deploy host without access to PyPI gets ERROR: No matching distribution found for
ansible-core!=2.19.0,<2.21,>=2.19. On the lab, the wheel of the version the release had installed (2.20.10) was
downloaded elsewhere, copied over and installed with pip install --no-deps <wheel file>; its dependencies were still
in the environment.
For cause 3¶
⚠️ State-changing. Reinstalls the Galaxy collections for this user, with
--force; another Kolla-Ansible release used by the same user then sees these versions too. Undo: runinstall-depsfrom the other release's environment.
source /path/to/venv/bin/activate
kolla-ansible install-deps
To keep two releases apart on one deploy host, run each from its own system user, or give each environment its own
collections path (Ansible's ANSIBLE_COLLECTIONS_PATH, or collections_path in an ansible.cfg) and install the
collections there with ansible-galaxy collection install -r <requirements file> -p <path>. This is Ansible's
mechanism, not a Kolla-Ansible option; test it on a lab first.
Verification¶
command -v ansible-playbook # /path/to/venv/bin/ansible-playbook
ansible-playbook --version | head -1 # within the release's range
kolla-ansible prechecks -i <inventory> # passes "Checking Ansible version"
Validity and limits¶
- Written from the Kolla-Ansible 2026.1 code (
ansible/roles/prechecks/tasks/package_checks.yml,ansible/roles/prechecks/vars/main.yml,requirements.txt,requirements.yml,requirements-core.yml,kolla_ansible/ansible.py,kolla_ansible/utils.py) and the quickstart and operating guides. - Lab run (Kolla-Ansible 22.2.0, all-in-one, deploy host = the node): the quick checks; cause 1 (full path without the
environment, no other Ansible on the host); cause 2 (
ansible-core2.18.10 in the environment: the symptom above), fixed by installing 2.20.10 back from a wheel (no PyPI access), thenprecheckspassed (failed=0). Not run:kolla-ansible install-deps(cause 3; no direct Internet access on the lab), the separate collections path, and the missing-module and syntax forms of the problem. - Ansible's own error messages for missing collections or unsupported syntax vary by version and are described, not quoted.
- Not covered: Kolla-Ansible installed from a distribution package or a container image, and Ansible configuration
files (
ansible.cfg) that change the collections path.
Related¶
- deploy, reconfigure, upgrade and the others: keep the deploy host's Kolla-Ansible pinned to the platform's release
- From 2025.1 to 2026.1: the upgrade sequence, including Ansible
- Kolla-Ansible 2026.1: quickstart, virtual environments, operating Kolla
Provenance: written by agent:ozarland-author, from the Kolla-Ansible 2026.1 code and documentation. Reviewed in its pull request (see the page history). Checked by a human operator: not yet.
Worked for you, or not? Tell us in one line: your release, your topology, and what happened.