Clarify the plugin 'configuration entries' hint in the docs

[samccann]

Currently we have the following note at https://github.com/ansible-community/antsibull-docs/blob/main/src/antsibull_docs/data/docsite/plugin.rst.j2#L461 which says:

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.

Some users are confused by that line so would be good to clarify and point to an area on docs.ansible.com that provides more detail.

[samccann]

As a newbie - it took me some time to realize 'configuration entries' referred to the Configuration: section below

That still leaves me with "for each entry type". I'm not sure what that means. does than mean for each parameter in the table?

And lastly, seems this would be a good link to point to https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable

[felixfontein]

"entry types" are Ansible variables, environment variables, INI entries, etc.

[samccann]

Ok thanks. Could we change the hint to:

Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. See R(Variable precedence,ansible_variable_precedence) for details.

[felixfontein]

Hmm, are you sure that https://docs.ansible.com/ansible/devel/playbook_guide/playbooks_variables.html#understanding-variable-precedence is the correct reference? I don't see any mention in there on how the config manager (for plugins) works.

[samccann]

@felixfontein honestly, I'm not sure what the config manager (for plugins) is ;-) got a pointer or a better reference to link to, keeping in mind this would be a note added in a lot of places...

[felixfontein]

I don't know any place that could be linked to (except source code), unfortunately...

[felixfontein]

(The config manager is https://github.com/ansible/ansible/blob/devel/lib/ansible/config/manager.py#L280, which is the piece of code that does the plugin option handling - assuming the plugin actually uses self.set_options() / self.get_option(), which not all of them do right now.)

[samccann]

Okay I pulled out the comments starting from https://github.com/ansible/ansible/blob/devel/lib/ansible/config/manager.py#L453 and here's what I get:

Order of precendence for plugin values, from highest to lowest:

• plugin argument set (does this include setting via interactive prompts?)
• variable overrides (not sure what this means?)
• playbook keywords (does this mean ``module_defaults` as well?)
• CLI settings
• environment variables
• config file entries
• default values

Once we get this order correct, we can add to https://docs.ansible.com/ansible/devel/module_plugin_guide/modules_intro.html and then link to that from here?

[samccann]

@felixfontein what do you think about the prior comment?

[felixfontein]

@samccann sorry, I wanted to reply to that but apparently forgot...

The order looks correct (according to the code), and seems to not have been changed since ansible-core 2.13 (I haven't checked before that). (One peculiarity is that None is treated as "not set", so if you use a high-priority way to set a value to None, it is ignored and a more lower-priority way is used if available.)

Which keywords exactly are meant I'm not sure; I guess the core team needs to clarify that. I'm also not sure for which plugin types these are actually available; I could only find indications for connection plugins in the code (when doing a very quick search), and in ansible-core they are used for connection, shell, and become plugins.

Variable overrides are all kind of variables I think, as in https://docs.ansible.com/ansible/devel/playbook_guide/playbooks_variables.html#using-variables.

Plugin arguments are "direct arguments to the plugin". These are relevant for lookups (direct parameters to these), inventory plugins (values from the config file); I'm not sure whether they are relevant for any other plugin type.

https://docs.ansible.com/ansible/devel/plugins/plugins.html or some new subpage is probably a better place than https://docs.ansible.com/ansible/devel/module_plugin_guide/modules_intro.html, since for modules you only have module parameters and nothing else.

[felixfontein]

So, should we change it to:

Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.

? We could provide a link to the code in ansible-core, but I don't think that's really helpful to most users.