Adopt a policy to not allow custom argument parameters to modules

[dagwieers]

Proposal: stop-custom-arguments

Author: Dag Wieers (@dagwieers)

Date: 2019-03-01

• Status: New
• Proposal type: process
• Targeted release: 2.8
• Associated PR: <link to GH PR in ansible/proposals if PR was submitted>
• Estimated time to implement: Decide and document

Motivation

I would like the project to adopt a policy (for reviewers) that we do not accept (new) module parameters that allow to provide custom arguments to commands.

We have been bitten by this in the past and we must use our experience to fall into the same trap elsewhere. (e.g. ansible/ansible#51916)

Problems

There are many problems when you allow users to add customer arguments (or options) to a module

• It makes supporting the module hard to impossible as users tend to use it in ways not foreseen
• It makes it impossible to guarantee idempotency
• It becomes a liability for future improvements and makes refactoring impossible (as you may break existing setups)
• And command line tools change over time, and something that works may stop working tomorrow, a module can make such transitions smooth, a parameter accepting custom args is a liability

Solution proposal

• The contributor should think about the use-case and what parameter(s) could be added to enable the functionality he needs

• The use of specific parameters to enable functionality makes it easier to add dependencies between parameters (mutual exclusive, etc.), migrate or refactor things and guarantee backward compatibility

• I would like the project to adopt a policy that we do not accept such parameters to modules

• Document it as part of the guidelines and make it widely known to all contributors/reviewers

[dagwieers]

cc @gundalow @jborean93 @nitzmahone

[jborean93]

I agree with this personally, having to support a custom list of arguments in a module is a bad UI as well. It operates under the assumption the user knows the tool being used when Ansible should be simpler than that. Efforts should be make towards adding a new module option to add the specific feature the user requires. This adds documentation and makes it a lot easier to maintain going forward.

If the option is not present, there is always the command module as a workaround. This is a bit uglier for at least the user isn't without any choice.

There are still some use cases where accepting an arbitrary list of arguments/params can be required. For example the win_chocolatey module accepts install_args and package_params which control the behaviour of the package being installed and the args it passes to the installer respectively. These are not arguments that control the Chocolatey invocation itself like setting the source or --force.

[caphrim007]

In the contributions I have made, I agree with the first bullet point dag makes in his solution proposal. In my case, we deliberately did not add some functionality to our modules until we had that functionality asked for by users.

On one hand, it made some users unhappy because they thought that we would just implement every feature before we even released the product. Once we explained to them our reasoning behind it though, they tended to get on board. In our case, we re-enforced our message by actually implementing new params when they requested them.

If module contributors offer this sort of unstructured input, then one could ask what's the point of having any structured input in the first place.

[bcoca]

It was the policy, sadly exceptions were made and now are being used as an example to follow.