The "module: parameters" option

Archives Ansible Project
1

Hi,

I noticed today on IRC that it's not just me how is not in favor of the new "module: parameters" syntax, and wanted to list the reasons why I think we should probably not promote it in the documentation:

  - Currently the documentation is quite confusing, we have examples
    showing one or the other method, and certain examples show both ways in
    a single example (fixable)

  - If there are no parameters to a command (like pause), it's weird to
    only have:

      - tasks:
        - pause:

    BTW Even though this is listed as an example, it fails in Ansible (both
        "pause:" and "action: pause") (fixable)

  - By promoting "command: parameters" we are making
    "local_action: commmand parameters" a confusing exception, should we
    promote "delegate_to: localhost" instead too ?

  - By explicitely stating "action:" you make people use the same
    terminology for an action, if not it might become confusing for support

  - By explicitely stating "action:" it is more obvious that only one such
    entry is allowed, which is not so clear from:

      - tasks:
        - command: ls
          register: foo
          pause:
          only_if: expression
          debug: msg="blah"

I know I already brought it up in the original pull-request at:

     https://github.com/ansible/ansible/pull/1426

and it was clear that this was not negotiable, but since I now see jp_mens, skvidal and daniel_hozac not liking it either and advising people on IRC to use "action:" instead, I wonder if we want to release it like this on v0.9.

Since it was not discussed on the list properly (afaict) I wanted to bring it up before we are commiting ourselves to it.

2

I noticed today on IRC that it's not just me how is not in favor of
the new "module: parameters" syntax

I'll admit to thinking it was pretty cool: it looked neat, shortened the
amount of typing I have to do, etc., but I find myself using action:
most of the time.

I find Dag has nailed most of the reasons why _I_ don't use command:
right on the head. It can stay, for all I care, but full ACK regarding
consistent documentation.

        -JP

3

I’m new to ansible but here’s my two cents. I agree that explicitly using action: makes more sense. When I see action: I know exactly what I’m looking at. I don’t think it’s as clear when I see a bunch of module names. I think that shows especially in Dag’s last example which has two actions in one task.

I don’t see the great value that makes it worth adding module: parameter as an option.

Having two different styles to accomplish the same thing sometimes makes sense but in this case I think, contrary to the docs suggestion, it actually reduces the simplicity, intuitiveness, uniformity and clarity. I think those things are important and helpful as people learn about, share and support ansible plays.

P.S. thanks for a great tool. It helps make work fun.

4

A better way to handle the no arguments question is not to say "this
is bad, I'm telling everyone to not do this" but to instead ask, how
can we make it better. So I think this was approached in totally the
wrong way. If you want a compatible way to do no arguments in that
form, maybe it's as simple as "module: None", and make that work, or
even just the string of the module name "- pause". Seems super easy
to do. Problem solved! I actually like that last one a lot!

I strongly believe this makes playbooks much more legible.
Local_action is a corner case used by advanced users, and that's ok if
it takes a slightly different form. Many people love this.

5

A better way to handle the no arguments question is not to say “this
is bad, I’m telling everyone to not do this” but to instead ask, how
can we make it better.

There was more discussed than just the no arguments example. I think some good questions are “Does the additional style really provide significant value? Does it complicate the ‘Dead Simple’ approach especially when considering sharing playbooks?”

The fact that, until now, I completely overlooked the debug: action in Dag’s last example is precisely the concern I have. Explicit use of action: easily identifies what module is being used. That’s legible to me and hopefully most users. I don’t have to wonder if the “word” refers to a module or something else (like register or only_if). So I can use action: in my playbooks and I’ll be satisfied. But what about when I want to use someone else’s playbook? I may have to contend with their preference. With all due respect I still don’t see having multiple styles as contributing to legibility or simplicity.

Jeremiah

6

It doesn't.

Also, not a democracy :slight_smile:

7

“It doesn’t” provide significant value? Or “It doesn’t” complicate? Or both.

Either way I understand the “Not a democracy”. :slight_smile: Just glad to be able to bring the points up.

In light of the other thread about sharing playbooks it looks like some of my concerns shouldn’t be much of a problem since sharing is not really the goal. I guess the issue of confusion can still arise if referencing other’s playbooks for learning purposes. Anyway, I understand your position on it.

Thanks for your time,
Jeremiah

8

Actually both.

It provides some nice polish, which isn't all that complicated :slight_smile:

9

The ‘not a democracy’ comment most likely point to the fact that this project is not a ‘design by committee’ or number of people that request/complain a for a feature once the owner has made his views clear, insisting isn’t going to change that.

Wait a bit, bring it up again later on, specially with new facts/reasoning to bolster your case, at this point I think you are just making this into an exhausting sore point that will be much harder to revisit later.

10

Yep, understood. To be honest I don’t think it’s a big enough issue to warrant that so I’m sorry for contributing to it becoming a sore point. I was originally trying to +1 the concerns and then clarify when I thought there was misunderstanding. It makes sense to me to bring issues up earlier rather than later. I think it’s far less likely to make a change after something has been in place for any length of time. But those are just my thoughts.

Thanks,
Jeremiah

11

Yeah, all of this was brought up when the feature was originally added
in 0.8 timeframe, so it's kind of a rehash... and received pretty good
fanfare at the time. First off, we do not remove features because
that breaks people's playbooks. A major goal for Ansible is making
sure playbooks are easily auditable, and to me, the best way to do
that is to strive for maximum whitespace, and text that reads the most
like English. When skimming to see what actions are used, I don't
want the visual block of "action:" keep interrupting my sight lines.
There are other syntaxes and things that I'm not *ultimately* pleased
with, but in all, Ansible is pretty close to that speed-reading level
I want it to be at.

FWIW, The multiple action case still happens because people try to do
this all of the time:

- action: foo
  action: bar

And yeah, that doesn't work like you think it does either :slight_smile:

That's a YAML issue, not a module syntax issue, really. We don't
have many issues like that, and in general, YAML is pretty good to us.

--Michael