Add notes for DNF module about caveats when ensuring presence of groups

[codyro]

SUMMARY

Add additional notes to the dnf module/documentation about the behavior of the dnf API's handling of groups.

ISSUE TYPE

• Docs Pull Request

ADDITIONAL INFORMATION

When using state: present in conjunction with a package group (EX: @Core), it is possible that a package in the group can be updated regardless of the state: present, causing breaking or unexpected results.

test-dnf-module.yml

---
- name: Test dnf module
  hosts: localhost
  tasks:
    - name: Test group present/update
      ansible.builtin.dnf:
        name: "@Core"
        state: present

[root@c ~]# rpm -q curl
curl-7.76.1-23.el9_2.1.x86_64

TASK [Test group present/update] ***********************************************************************
task path: /root/update-test.yml:6
<127.0.0.1> ESTABLISH LOCAL CONNECTION FOR USER: root
<127.0.0.1> EXEC /bin/sh -c 'echo ~root && sleep 0'
<127.0.0.1> EXEC /bin/sh -c '( umask 77 && mkdir -p "` echo /root/.ansible/tmp `"&& mkdir "` echo /root/.ansible/tmp/ansible-tmp-1691356716.832642-1563126-24396014678510 `" && echo ansible-tmp-1691356716.832642-1563126-24396014678510="` echo /root/.ansible/tmp/ansible-tmp-1691356716.832642-1563126-24396014678510 `" ) && sleep 0'
Using module file /usr/lib/python3.11/site-packages/ansible/modules/dnf.py
<127.0.0.1> PUT /root/.ansible/tmp/ansible-local-1563122tenqqjke/tmph7vr0kpm TO /root/.ansible/tmp/ansible-tmp-1691356716.832642-1563126-24396014678510/AnsiballZ_dnf.py
<127.0.0.1> EXEC /bin/sh -c 'chmod u+x /root/.ansible/tmp/ansible-tmp-1691356716.832642-1563126-24396014678510/ /root/.ansible/tmp/ansible-tmp-1691356716.832642-1563126-24396014678510/AnsiballZ_dnf.py && sleep 0'
<127.0.0.1> EXEC /bin/sh -c '/usr/bin/python3.11 /root/.ansible/tmp/ansible-tmp-1691356716.832642-1563126-24396014678510/AnsiballZ_dnf.py && sleep 0'
<127.0.0.1> EXEC /bin/sh -c 'rm -f -r /root/.ansible/tmp/ansible-tmp-1691356716.832642-1563126-24396014678510/ > /dev/null 2>&1 && sleep 0'
changed: [localhost] => {
    "changed": true,
    "invocation": {
        "module_args": {
            "allow_downgrade": false,
            "allowerasing": false,
            "autoremove": false,
            "bugfix": false,
            "cacheonly": false,
            "conf_file": null,
            "disable_excludes": null,
            "disable_gpg_check": false,
            "disable_plugin": [],
            "disablerepo": [],
            "download_dir": null,
            "download_only": false,
            "enable_plugin": [],
            "enablerepo": [],
            "exclude": [],
            "install_repoquery": true,
            "install_weak_deps": true,
            "installroot": "/",
            "list": null,
            "lock_timeout": 30,
            "name": [
                "@Core"
            ],
            "nobest": false,
            "releasever": null,
            "security": false,
            "skip_broken": false,
            "sslverify": true,
            "state": "present",
            "update_cache": false,
            "update_only": false,
            "validate_certs": true
        }
    },
    "msg": "",
    "rc": 0,
    "results": [
        "Group core installed.",
        "Installed: curl-7.76.1-23.el9_2.2.x86_64",
        "Removed: curl-7.76.1-23.el9_2.1.x86_64"
    ]
}

PLAY RECAP *********************************************************************************************
localhost                  : ok=1    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

[root@c ~]# rpm -q curl
curl-7.76.1-23.el9_2.2.x86_64

[ansibot]

The test ansible-test sanity --test validate-modules [explain] failed with 66 errors:

lib/ansible/modules/dnf.py:0:0: doc-choices-do-not-match-spec: Argument 'state' in argument_spec defines choices as (['absent', 'installed', 'latest', 'present', 'removed']) but documentation defines choices as ([])
lib/ansible/modules/dnf.py:0:0: doc-choices-do-not-match-spec: Argument 'use_backend' in argument_spec defines choices as (['auto', 'dnf4', 'dnf5']) but documentation defines choices as ([])
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'allow_downgrade' in argument_spec defines default as (False) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'allowerasing' in argument_spec defines default as (False) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'autoremove' in argument_spec defines default as (False) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'bugfix' in argument_spec defines default as (False) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'cacheonly' in argument_spec defines default as (False) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'disable_gpg_check' in argument_spec defines default as (False) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'disable_plugin' in argument_spec defines default as ([]) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'disablerepo' in argument_spec defines default as ([]) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'download_only' in argument_spec defines default as (False) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'enable_plugin' in argument_spec defines default as ([]) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'enablerepo' in argument_spec defines default as ([]) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'exclude' in argument_spec defines default as ([]) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'install_repoquery' in argument_spec defines default as (True) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'install_weak_deps' in argument_spec defines default as (True) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'installroot' in argument_spec defines default as ('/') but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'lock_timeout' in argument_spec defines default as (30) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'name' in argument_spec defines default as ([]) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'nobest' in argument_spec defines default as (False) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'security' in argument_spec defines default as (False) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'skip_broken' in argument_spec defines default as (False) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'sslverify' in argument_spec defines default as (True) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'update_cache' in argument_spec defines default as (False) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'update_only' in argument_spec defines default as (False) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'use_backend' in argument_spec defines default as ('auto') but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-default-does-not-match-spec: Argument 'validate_certs' in argument_spec defines default as (True) but documentation defines default as (None)
lib/ansible/modules/dnf.py:0:0: doc-elements-mismatch: Argument 'disable_plugin' in argument_spec specifies elements as str,but elements is not documented
lib/ansible/modules/dnf.py:0:0: doc-elements-mismatch: Argument 'disablerepo' in argument_spec specifies elements as str,but elements is not documented
lib/ansible/modules/dnf.py:0:0: doc-elements-mismatch: Argument 'enable_plugin' in argument_spec specifies elements as str,but elements is not documented
lib/ansible/modules/dnf.py:0:0: doc-elements-mismatch: Argument 'enablerepo' in argument_spec specifies elements as str,but elements is not documented
lib/ansible/modules/dnf.py:0:0: doc-elements-mismatch: Argument 'exclude' in argument_spec specifies elements as str,but elements is not documented
lib/ansible/modules/dnf.py:0:0: doc-elements-mismatch: Argument 'name' in argument_spec specifies elements as str,but elements is not documented
lib/ansible/modules/dnf.py:0:0: doc-missing-type: Argument 'releasever' in argument_spec uses default type ('str') but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: doc-missing-type: Argument 'use_backend' in argument_spec uses default type ('str') but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: missing-documentation: No DOCUMENTATION provided
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'allow_downgrade' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'allowerasing' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'autoremove' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'bugfix' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'cacheonly' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'conf_file' in argument_spec defines type as 'str' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'disable_excludes' in argument_spec defines type as 'str' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'disable_gpg_check' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'disable_plugin' in argument_spec defines type as 'list' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'disablerepo' in argument_spec defines type as 'list' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'download_dir' in argument_spec defines type as 'str' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'download_only' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'enable_plugin' in argument_spec defines type as 'list' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'enablerepo' in argument_spec defines type as 'list' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'exclude' in argument_spec defines type as 'list' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'install_repoquery' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'install_weak_deps' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'installroot' in argument_spec defines type as 'str' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'list' in argument_spec defines type as 'str' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'lock_timeout' in argument_spec defines type as 'int' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'name' in argument_spec defines type as 'list' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'nobest' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'security' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'skip_broken' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'sslverify' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'state' in argument_spec defines type as 'str' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'update_cache' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'update_only' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:0:0: parameter-type-not-in-doc: Argument 'validate_certs' in argument_spec defines type as 'bool' but documentation doesn't define type
lib/ansible/modules/dnf.py:285:5: documentation-syntax-error: DOCUMENTATION is not valid YAML

The test ansible-test sanity --test ansible-doc [explain] failed with the error:

Command "ansible-doc -t module dnf" returned exit status 1.
>>> Standard Error
ERROR! module dnf missing documentation (or could not parse documentation): dnf did not contain a DOCUMENTATION attribute (/root/ansible/lib/ansible/modules/dnf.py). Unable to parse documentation in python file '/root/ansible/lib/ansible/modules/dnf.py': while scanning a simple key
  in "<unicode string>", line 272, column 5
could not find expected ':'
  in "<unicode string>", line 273, column 5. while scanning a simple key
  in "<unicode string>", line 272, column 5
could not find expected ':'
  in "<unicode string>", line 273, column 5

The test ansible-test sanity --test yamllint [explain] failed with 2 errors:

lib/ansible/modules/dnf.py:285:5: error: DOCUMENTATION: syntax error: could not find expected ':' (syntax)
lib/ansible/modules/dnf.py:285:5: unparsable-with-libyaml: while scanning a simple key - could not find expected ':'

click here for bot help

[bcoca]

I would point at package_facts or check_mode for this use case, as 'present' and check_mode: no is expected to modify a system to match the stated group presence.

[Akasurde]

@codyro Are you still working on this? Thanks.

[codyro]

I thought this got picked up by someone else. Added to my agenda.