Provide standardized way to influence module return values

[dagwieers]

Proposal: Standard way to influence return values

Author: Dag Wieers (@dagwieers)

Date: 2018-01-10

• Status: New
• Proposal type: standard practice
• Targeted Release: 2.5
• Estimated time to implement: decision

Motivation

For the ACI modules (but I had a similar need with other modules as well) there is a lot of information that is useful to return, but it is not always desirable to return everything conceivable because only a limited subset is directly useful to 90% of the users. or the added return values have a possible performance impact and/or may confuse most of the users.

So in some cases the additional return values are related to debugging or testing the module itself, but in other cases it attains to troubleshooting your playbook or module behavior, or even adds more advanced information for a limited set of use-cases. (Maybe with a performance penalty attached)

In the case of ACI, the module creates a proposed configuration, we fetch the current configuration and after applying we end up with the new or existing configuration.

In most cases only the existing/current configuration is useful, and especially since this can be a complex/big dictionary providing wanted, existing and new can be very confusing (especially if you are looking for output and values appear more than once). But when you have a problem, it would be nice to see all the values.

Problems

See Motivation.

Solution proposal

Various solutions are possible:

• Let the return values depend on the verbosity level (-vvv)
  • This may add possible confusion to playbook-writers as well
  • Makes it impossible to use advanced return values
• Take ANSIBLE_DEBUG into account
  • Makes it impossible to use advanced return values when needed
• Have a standardized parameter (e.g. output: [minimal|normal|advanced]) to influence return values
  • Leaves it up to the user to influence and gives maximum control

[abadger]

At the meeting today we decided that at the present time we don't have enough use cases to propose an Ansible-wide standard. Gave some feedback about an ACi-standard for now. Decided that this should be a parameter that all the ACI modules take. Thought that perhaps something like "include_outputs: [list]" might be appropriate. list could have things like "original,proposed,final" to limit which of those is calculated and returned.

I'll close this for now but someone can re-submit the proposal if there's enough different use-cases to propose an Ansible-wide standard.

[dagwieers]

So we implemented 2 things:

• output_level: (normal|info|debug)
• ANSIBLE_DEBUG=1 or --debug will enable output_level: debug

More information in ansible/ansible#35304