Ansible should show collections' supported versions

[jalanb]

Proposal: Show collections' supported versions

Author: Alan @jalanb

Date: 2021-07-22

• Status: New
• Proposal type: Upgrade warning
• Targeted release: 2.12
• Associated PR: None (yet)
• Estimated time to implement: 1 day

Motivation

Error messages should not tell the user merely what is wrong, but (if possible) also suggest how to fix the problem

Problems

What problems exist that this proposal will solve?

Running an ansible playbook which uses the "Posix collection" and with the latest Ansible installed showed me the error message:

[WARNING]: Collection ansible.posix does not support Ansible version 2.11.0

This is not helpful, as it only tells me what I already know: I have 2.11.0 installed.

But it does not tell me what version that ansible.posix does support, what I should upgrade to.

Solution proposal

• Describe your suggested solution here.

Include the collections' range of supported versions in the message. (Preferably in a format that can be used in a pip install command, e.g. like >=2.9,<2.11)

• Insert code in snippets if you would like as shown. This code change was applied at the v2.11.3 tag in file lib/ansible/plugins/loader.py at line 1097, which is here

Old code:

        if not _does_collection_support_ansible_version(collection_meta.get('requires_ansible', ''), ansible_version):
            mismatch_behavior = C.config.get_config_value('COLLECTIONS_ON_ANSIBLE_VERSION_MISMATCH')
            message = 'Collection {0} does not support Ansible version {1}'.format(collection_name, ansible_version)

New code

        supported_versions = collection_meta.get('requires_ansible', '')
        if not _does_collection_support_ansible_version(supported_versions, ansible_version):
            mismatch_behavior = C.config.get_config_value('COLLECTIONS_ON_ANSIBLE_VERSION_MISMATCH')
            message = 'Collection {0} does not support Ansible version {1}. It does support versions {2}'.format(
                collection_name, ansible_version, supported_versions)

• Be sure to explain how this solves problems. This fixes the problem by retaining the versions supported by the collection, then adding those to message

After this change I saw the new message as

[WARNING]: Collection ansible.posix does not support Ansible version 2.11.0. It does support versions >=2.9,<2.11

Dependencies (optional)

Explain any dependencies. This section is optional but could be helpful.

• Possibly depends on the format of the versions returned by collection_meta.get()

I did not debug into that method once I saw that it gave a "proper" pip version specifier in my example

Testing (optional)

Does / should this require testing, and if so, how? Describe here. This section is optional but could be helpful.

Run the latest ansible (>= 2.11.0) on a playbook that uses ansible posix, for example

  - name: Allow HTTP through firewall
    become: yes
    ansible.posix.firewalld:
      service: http
      permanent: yes
      state: enabled
      zone: public

See the Warning message, and decide whether it merely says "does not support ..." or also include "It does support ..."

Documentation (optional)

I suggest no extra documentation is needed

Anything else?

Thanks for the wonderful tools which make my life easier every day.