Documentation: action: module vs module:

Archives Ansible Project
1

Hello,

Dag and I pulled straws on who'd write this message, and I lost. :wink:

Ansible's original playbook syntax for invoking a module was

        - action: modulename ...

This was later augmented to allow omission of the "action" keyword.

        - modulename ...

I forget the history of why it was decided to use the second syntax form
in the documentation, but that is the way it currently is (I recently
submitted a huge patch which cleaned that up).

Discussion today brought this topic up again, and a number of people
(myself included) feel that adding the "action:" keyword makes a) more
sense and b) looks better, particularly when mixed with things like
local_action where the latter may *not* be omitted. Compare

        - action: copy src=
        - action: shell ...
          register: var
        - local_action: get_url ...

and

        - copy: src=
        - shell: ...
          register: var
        - local_action: get_url

(In the latter example, it's difficult to see that 'register' is not a
module ...)

Can we, once in for all, settle this? We are not proposing to disallow
the syntax within the playbook (which would break backwards
compatibility!), but simply trying to establish a "standard" by which we
document things, both in the official Ansible documentation as well as
in whatever other things we write about Ansible.

Whichever method we settle on, I'll gladly go through all the modules
again (*groans*) and fix the EXAMPLES string.

        -JP

2

My $0.02: I prefer the ‘action: ’ style syntax just because it is more explicit about what is being done, especially when you have other parts to a task such as register, with_items, when and so on.

3

yeah I know this was controversial before.

Lots of folks also prefer the shorthand of not having to type the extra “action:” line.

When I wrote Ansible, one of things I strove for was to make it maximally readable, which is why when someone came up with the idea to say “hey, why do you have to type action all the time”, I said, sure, that’s a great idea, and thus we have standardized on “module: foo”.

Obviously local action requires a bit of a difference, but it’s also the same as:

module: foo
delegate_to: localhost

Given I already remember this discussion from several months ago when we moved to standardize on “module: foo”, I’m not really wanting to have it again :slight_smile:

We have been standardizing on “module: foo” in Ansible-examples.

4

I also sometimes tend to favor "args:" for more readability and think
"action:" is more readable in that case, too.

David

5

FYI: We are not taking votes here.