Good Practices for Ansible - GPA

define for which use case to use roles, playbooks, potentially workflows (in Ansible Controller/Tower/AWX), and how to split the code you write.

especially when writing automation in a team, it is important to have a certain level of consistency and make sure everybody has the same understanding. By lack of doing so, your automation becomes unreadable and difficult to grasp for new members or even for existing members.

The following is only one example of how to structure your content but has proven robust enough on multiple occasions.

Figure 1. Structure of Automation

Collections should be comprised of roles collected either at the type or landscape level. See The Structures Definition

Gathering and publishing collections, rather than individual roles, allows for easier distribution and particularly becomes more important when we discuss Execution Environments.

Often, variables will want to be defined on a collection level, but this can cause issues with roles being able to be reused. By defining collection wide variables and referencing them in roles' defaults variables, this can be made clear and roles can remain reusable. Collection variables are nowhere defined explicitly and are to be documented in the collection’s documentation.

Variables that are shared across collections can cause collisions when roles are reused outside of the original collection. Role variables should continue to be named according to our recommendations for naming variables It still remains possible to overwrite collection variable values for a specific role. Each role has it’s own set of defaults for the variable.

For a collection "mycollection", two roles exist. "alpha" and "beta". For this example, there is no default for the controller_username and would have to be defined in one’s inventory. The no_log variable does have defaults defined, and thus only needs to be defined if the default is being overwritten.

# specific role variables
alpha_job_name: 'some text'
# collection wide variables
alpha_controller_username: "{{ mycollection_controller_username }}"
alpha_no_log: "{{ mycollection_no_log | default('true') }}"

# specific role variables
beta_job_name: 'some other text'
# collection wide variables
beta_controller_username: "{{ mycollection_controller_username }}"
beta_no_log: "{{ mycollection_no_log | default('false') }}"

Include a README file that is in the root of the collection and which contains:

Use https://github.com/ansible-network/collection_prep to generate the documentation for the collection

Include a license file in the root directory Name the license file either LICENSE or COPYING. The contents may be either the text of the applicable license, or a link to the canonical reference for the license on the Internet (such as https://opensource.org/licenses/BSD-2-Clause ) If any file in the collection is licensed differently from the larger collection it is a part of (such as module utilities), note the applicable license in the header of the file.

Don’t put too much logic in your playbook, put it in your roles (or even in custom modules), and try to limit your playbooks to a list of a roles.

Roles are meant to be re-used and the structure helps you to make your code re-usable. The more code you put in roles, the higher the chances you, or others, can reuse it. Also, if you follow the type-function pattern, you can very easily create new (type) playbooks by just re-shuffling the roles. This way you can create a playbook for each purpose without having to duplicate a lot of code. This, in turn, also helps with the maintainability as there is only a single place where necessary changes need to be implemented, and that is in the role

A playbook can contain pre_tasks, roles, tasks and post_tasks sections. Avoid using both roles and tasks sections, the latter possibly containing import_role or include_role tasks.

The order of execution between roles and tasks isn’t obvious, and hence mixing them should be avoided.

Either you need only static importing of roles and you can use the roles section, or you need dynamic inclusion and you should use only the tasks section. Of course, for very simple cases, you can just use tasks without roles.

limit your usage of tags to two aspects:

there is nothing worse than tags which can’t be used alone, they bear the risk to destroy something by being called standalone. An acceptable exception is the pattern to use the role name as tag name, which can be useful while developing the playbook to test, or exclude, individual roles.

Debug messages should have a verbosity defined as appropriate for the message.

Debug messages are useful during testing and development, and can be useful to retain as playbooks go into production for future troubleshooting. However, log messages will clutter your output, which can confuse users with non-relevant information.

A Single Source of Truth (SSOT) is the place where the "ultimate" truth about a certain data is generated, stored and maintained. There can be more than one SSOT, each for a different piece of information, but they shouldn’t overlap and even less conflict. As you create your inventory, you identify these SSOTs and combine them into one inventory using dynamic inventory sources (we’ll see how later on). Only the aspects which are not already provided by other sources are kept statically in your inventory. Doing this, your inventory becomes another source of truth, but only for the data it holds statically, because there is no other place to keep it.

You limit your effort to maintain your inventory to its absolute minimum and you avoid generating potentially conflicting information with the rest of your IT.

You can typically identify three kinds of candidates as SSOTs:

As you combine multiple sources, some will represent:

Mixing up these two kind of information can lead to your automation taking the wrong course of action by thinking that the current situation is aligned with the desired state. That can make your automation go awry and your automation engineers confused. There is a reason why Ansible makes the difference between "facts" (As-Is) and "variables" (To-Be), and so should you. In the end, automation is making sure that the As-Is situation complies to the To-Be description.

The technical tools typically contain a lot of discovered information, like an IP address or the RAM size of a VM. In a typical cloud environment, the IP address isn’t part of the desired state, it is assigned on the fly by the cloud management layer, so you can only get it dynamically from the cloud API and you won’t manage it. In a more traditional environment nevertheless, the IP address will be static, managed more or less manually, so it will become part of your desired state. In this case, you shouldn’t use the discovered information or you might not realize that there is a discrepancy between As-Is and To-Be.

Everybody has started with a single file inventory in ini-format (the courageous ones among us in YAML format), combining list of hosts, groups and variables. An inventory can nevertheless be also a directory containing:

It is the only way to combine simply multiple sources into one inventory, without the trouble to call ansible with multiple -i {inventory_file} parameters, and keep the door open for extending it with dynamic elements.

The following is a complete inventory as described before. You don’t absolutely need to start at this level of complexity, but the experience shows that once you get used to it, it is actually a lot easier to understand and maintain than a single file.

inventory_example/  (1)
├── dynamic_inventory_plugin.yml  (2)
├── dynamic_inventory_script.py  (3)
├── groups_and_hosts  (4)
├── group_vars/  (5)
│   ├── alephs/
│   │   └── capital_letter.yml
│   ├── all/
│   │   └── ansible.yml
│   ├── alphas/
│   │   ├── capital_letter.yml
│   │   └── small_caps_letter.yml
│   ├── betas/
│   │   └── capital_letter.yml
│   ├── greek_letters/
│   │   └── small_caps_letter.yml
│   └── hebrew_letters/
│       └── small_caps_letter.yml
└── host_vars/  (6)
    ├── host1.example.com/
    │   └── ansible.yml
    ├── host2.example.com/
    │   └── ansible.yml
    └── host3.example.com/
        ├── ansible.yml
        └── capital_letter.yml

[all]
host1.example.com
host2.example.com
host3.example.com

[alphas]
host1.example.com

[betas]
host2.example.com

[greek_letters:children]
alphas
betas

[alephs]
host3.example.com

[hebrew_letters:children]
alephs

inventory_satellite/
├── groups_and_hosts
└── host_vars/
    └── sat6.example.com/
        ├── ansible.yml
        └── satellite/
            ├── content_views.yml
            ├── hostgroups.yml
            └── locations.yml

To perform the same task on multiple hosts, don’t create a variable with a list of hosts and loop over it. Instead use as much as possible the capabilities of your inventory, which is already a kind of list of hosts.

There are 4 main reasons for following this advice:

Our first idea could be to define managers and hosts first in an inventory:

[managers]
manager_a
manager_b

[managed_hosts]
host1
host2
host3

provision_list_of_hosts:
  - name: host1
    provision_value: uno
  - name: host2
    provision_value: due

- name: provision hosts in a bad way
  hosts: managers
  gather_facts: false
  become: false

  tasks:
    - name: create some file to simulate an API call to provision a host
      copy:
        content: "{{ item.provision_value }}\n"
        dest: "/tmp/bad_{{ inventory_hostname }}_{{ item.name }}.txt"
        force: true
      loop: "{{ provision_list_of_hosts }}"

[managers]
manager_a
manager_b

[managed_hosts_a]
host1
host2

[managed_hosts_b]
host3

[managed_hosts:children]
managed_hosts_a
managed_hosts_b

$ cat inventory_good/host_vars/host1/provision.yml
provision_value: uno
$ cat inventory_good/group_vars/managed_hosts_a/provision.yml
manager_hostname: manager_a

- name: provision hosts in a good way
  hosts: managed_hosts
  gather_facts: false
  become: false

  tasks:
    - name: create some file to simulate an API call to provision a host
      copy:
        content: "{{ provision_value }}\n"
        dest: "/tmp/good_{{ manager_hostname }}_{{ inventory_hostname }}.txt"
        force: true

$ ANSIBLE_STDOUT_CALLBACK=profile_tasks \
	ansible-playbook -i inventory_bad playbook_bad.yml
Saturday 23 October 2021  13:11:45 +0200 (0:00:00.040)       0:00:00.040 ******
Saturday 23 October 2021  13:11:45 +0200 (0:00:00.858)       0:00:00.899 ******
===============================================================================
create some file to simulate an API call to provision a host ------------ 0.86s
$ ANSIBLE_STDOUT_CALLBACK=profile_tasks \
	ansible-playbook -i inventory_good playbook_good.yml
Saturday 23 October 2021  13:11:55 +0200 (0:00:00.040)       0:00:00.040 ******
Saturday 23 October 2021  13:11:56 +0200 (0:00:00.569)       0:00:00.610 ******
===============================================================================
create some file to simulate an API call to provision a host ------------ 0.57s

There are 22 levels of variable precedence. This is almost impossible to keep in mind for a "normal" human and can lead to all kind of weird behaviors if not under control. In addition, the use of play(book) variables is not recommended as it blurs the separation between code and data. The same applies to all constructs including specific variable files as part of the play (i.e. include_vars). By reducing the number of variable types, you end up with a more simple and overseeable list of variables. Together with some explanations why they have their specific precedence, so that they become easier to remember and use wisely:

Don’t use extra vars to define your desired state. Make sure your inventory completely describes how your environment is supposed to look like. Use extra vars only for troubleshooting, debugging or validation purposes.

Inventory variables are typically in some kind of persistent tracked storage (be it a database or Git), and should be your sole source representing your desired state so that you can refer to it non-ambiguously. On the other hand, extra vars are bound to a specific job or ansible-call and disappear together with history.

Don’t use extra vars for the RAM size of VM to create, because this is part of the desired state of your environment, and nobody would know one year down the line if the VM was really created with the proper RAM size according to the state of the inventory. You may use an extra variable to protect a critical part of a destructive playbook, something like are_you_really_really_sure: true/false, which is validated before e.g. a VM is destroyed and recreated to change parameters which can’t be changed on the fly. You can also use extra vars to enforce fact values which can’t be reproduced easily, like overwriting ansible_memtotal_mb to simulate a RAM size fact of terabytes to validate that your code can cope with it.

All plugins, regardless of type, need documentation that describes the input parameters, outputs, and practical examples of how to use it.

See the Ansible Developer Guide sections on Plugin Configuration and Documentation Standards and Module Documenting for more details.

Sphinx (reST) formatted docstring are preferred for Ansible development. This includes all parameters, yields, raises, or returns for all classes, private and public functions written in Python.

PEP-257 states that: "All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings. Public methods (including the init constructor) should also have docstrings. A package may be documented in the module docstring of the init.py file in the package directory."

Use Python type hints to document variable types. Type hints are supported in Python 3.5 and greater.

Type hints communicate what type a variable can be expected to be in the code. They can be consumed by static analysis tools to ensure that variable usage is consistent within the code base.

Use pytest for writing unit tests for plugins

Pytest is the testing framework used by Ansible Engineering and will provide the best experience for plugin developers The Ansible Developer Guide section on unit testing has detailed information on when and how to use unit tests.

Ensure a consistent approach to the way complex argument_specs are formatted within a collection.

When hand-writing a complex argspec, the author may choose to build up to data structure from multiple dictionaries or vars. Other authors may choose to implement a complex, nested argspec as a single dictionary. Within a single collection, select one style and use it consistently.

Use of a sngle dictionary

Keep the entry file to a plugin to a minimal and easily maintainable size.

Long and complex code files can be difficult to maintain. Move reusable functions and classes, such as those for data validation or manipulation, to a module_utils/ (for Ansible modules) or plugin_utils/ (for all other plugin types) file and import them into plugins. This keeps the Python code easier to read and maintain.

The ansible.plugin_builder is a tool which helps developers scaffold new plugins.

This will make it easier to troubleshoot failures if they occur

Error messages that communicate specific details of the failure will aid in resolving the problem. Unclear error messages such as "Failed!" are unnecessarily obscure.