====== Ansible - best practices ======

===== Naming things =====

  * Variable names must contain only lowercase alphanumeric characters and the underscore ''_'' character. Variable names must also start with either an alphabetic or underscore ''_'' character.
  * Problematic Code

<code>
---
- name: Example playbook
  hosts: localhost
  vars:
    CamelCase: true # <- Contains a mix of lowercase and uppercase characters.
    ALL_CAPS: bar # <- Contains only uppercase characters.
    v@r!able: baz # <- Contains special characters.
    hosts: [] # <- hosts is an Ansible reserved name
    role_name: boo # <-- invalid as being Ansible special magic variable
 </code>

  * Correct Code

<code>
---
- name: Example playbook
  hosts: localhost
  vars:
    lowercase: true # <- Contains only lowercase characters.
    no_caps: bar # <- Does not contains uppercase characters.
    variable: baz # <- Does not contain special characters.
    my_hosts: [] # <- Does not use a reserved names.
    my_role_name: boo
</code>

  * Role names must contain only lowercase alphanumeric characters and the underscore ''_'' character. Role names must also start with an alphabetic character.

==== YAML and Jinja2 Syntax ====

  * Indent at two spaces
  * Indent list contents beyond the list definition

<code>
example_list:
  - example_element_1
  - example_element_2
  - example_element_3
  - example_element_4
</code>

  * Split long expressions into multiple lines. Always use the sign ''>-'' instead of ''>'' unless you are absolutely sure the trailing newline is not significant. The sign ''>'' adds a newline character to the last line, effectively turning non nunc. at the end of the example string above into ''"non nunc.\n"'', and ''>-'' doesn’t add the newline character. It is really easy to introduce an error by using ''>'' and silently add a newline to a variable, like a filename, which leads to strange, hard to decipher errors.

<code>
- name: Call a very long command line
  ansible.builtin.command: >-
    echo Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Maecenas mollis, ante in cursus congue, mauris orci tincidunt nulla,
    non gravida tortor mi non nunc.
</code>

  * Use ''true'' and ''false'' for boolean values in playbooks. Do not use the Ansible-specific ''yes'' and ''no'' as boolean values and also avoid the use of the Python-style ''True'' and ''False''.
  * Use double quotes for YAML strings with the exception of Jinja2 strings which will use single quotes.