Survey on various Ansible Style questions (CfgMgmtCamp follow-up)

Project Discussions
, ,
1

Hi everyone

following CfgMgmtCamp let me ask the community on certain style questions for Ansible.

In case you already answered in LimeSurvey or in person on the questions - please do not answer on all questions except questions 7, 8,9 below :slight_smile: - these questions are the are new ones

Some additional info on questions below:

  1. It is possible to use “dot notation” for dictionaries in many cases. The bracket notation is mandatory the variables use reserved names; for variables that use special characters;

Let’s say that because it is widespread ansible_facts will still use bracket notation
ansible_facts['hostname'].

Reference:

  1. it is possible to avoid quotes for most of the strings in YAML, the exceptions are:

If the string contains (e.g. : , { , } , [ , ] , , , & , * , # , ? , | , - , < , > , = , ! , % , @ , \ ).
and
If the value starts with characters like !, &, or #.

Additional reading:

Survey

Q1. What is the preferred dictionary notation?

  • Dot notation is the preferred notation, if possible
    ({{ my_dictionary.mykey }})

  • Bracket notation everywhere
    {{ my_dictionary['mykey'] }}

  • Both options are equally fine

0 voters
Q2. Is it good practice to prefix internal variables with double underscores (__) and use r_ prefix for variables used in “register” task attribute?
  • No, it is not necessary
  • Yes, it is better
0 voters
Q3. What is the preferred inventory format?
  • INI
  • YAML
  • Both options are equally fine
0 voters
Q4. Are the quotes necessary for all strings?

  • No, not always necessary, below is just fine
    apache_package_name: httpd

  • Yes

(apache_package_name: "httpd"
or
apache_package_name: 'httpd'); see also question about the quotes

0 voters
Q5. What is the preferred option for “external” quotes?
  • Double quotes
  • Single quotes
0 voters
Q6. What are the verb(s) that should be used within a task name?
  • “Install”, “create”, “configure”, etc.
  • Prefer the verb “Ensure” over “Install”, “create”, “configure” etc.
0 voters
Q7. What is the preferred notation for lists and dictionaries?

  • Use flow style (aka inline?), for example:
    tags: [install,configure]
    user: {name: Alice, age: 30}

  • Use Block-style lists and dictionaries, for example

tags: 
  - install
  - configure

user: 
  name: Alice
  age: 30
  • Both options are equally fine
  • It depends/I have a different opinion not covered by above
0 voters
Q8. Do you use and maintain meta/main.yml?
  • Yes, both using and maintain it
  • Yes, I read meta/main.yml
  • Yes, I maintain meta/main.yml
  • No, the file is actually is not used. It is typically present in the role but nobody maintains it
0 voters
Q9. Do you use and maintain meta/argument_specs.yml?
  • Yes, mostly used and maintained
  • Mostly no but we have plans to use it going forward
  • No, the file is mostly not present/is not filled in
  • No and it is the first time I hear about this file
  • It depends/I have a different opinion not covered by above
0 voters
1 Like
2

Regarding meta/main.yml in roles in collections: I think there was a time when galaxy-importer rejected a collection that had a role without this file. That might have changed though… This is I think the only reason why I maintain this file for some of my collections that have roles.

2 Likes
3

I always use ansible (yaml) style notation especially for lists and dictionaries. If lists are changing, it looks nice in git diffs.

Wonder what do you consider internal variable of the role in this context?

I think that having anything coded in the name is an antipattern and should not be used. My understanding is that this practice is coming from the fact that there is no go to definition and go to references functionality in ansible language server for variables (and for roles). One cannot simply check definition of a variable.

4

There is a topic I’ve opened for the same question (+ pool) and some additional alternatives proposed for task naming:

5

Q2. Is it good practice to prefix internal variables with double underscores (__ ) and use r_ prefix for variables used in “register” task attribute?

When writing a role which requires an internal variable, I usually follow the PEP 8 Style guide for specifying variables with a single leading underscore. Taken from: PEP 8 – Style Guide for Python Code | peps.python.org

_single_leading_underscore : weak “internal use” indicator.

---
# defaults/main.yml
_my_internal_var:
  - example
6

Adding to this, just thought you might want to take a look at the Red Hat Community of Practice styling guide: Good Practices for Ansible - GPA

As I’m reading through this I can see that my preference above contradicts that of the guide! :face_with_hand_over_mouth:

3.1.4. Naming parameters

Moreover, internal variables (those that are not expected to be set by users) are to be prefixed by two underscores: __foo_variable .

7

Few replies/comments

  1. The formatting of “block-style” notation got a bit lost in the survey.
    Even though all of you might know it let me still provide examples of that, for lists (and also “block-style” might be not much known as a term)
tags:
  - install
  - configure

users:
  name: John
  location: ghent

  1. @kks , indeed there is an answer of Daniel. But also roughly that assuming that vars/main.yml typically would contain (some) variables with underscores.
    The reference for __ are roles of Jeff Geerling (I guess all of them) and indeed Good Practices for Ansible - GPA , one of the Style Guides that I used
    The convention on using r_ for register variables is used more seldomly…

  2. @bvitnik indeed, thank you I have seen it! For me the poll over there was a bit of “semi-final” and I created those 2 options that got into final. And actually right now “ensure” is losing in the final :face_with_monocle:

1 Like
8

To me it looks like this recommendation predates argument_specs file. Because with argument specs there is no question what can be set by user.
There are number of questionable recommendations in that document from my point of view.