Ansible Style Guide¶
We implement all the default rules of Ansible Lint. A listing of all these rules can be found in the Ansible Lint documentation: https://ansible-lint.readthedocs.io/en/latest/default_rules/
Task naming¶
Tasks must always have names. The only exception allowed is for forked playbooks.
A name never starts with a small letter
Names are written in present tense
No punctuation is used in names
Positioning and use of the become directive¶
The become directive is only set when needed and is always set explicitly for each task that needs it.
Blocks, roles, or playbooks are never executed in a privileged mode.
We always insert the become directive between the name of a task and the task itself. This also applies to related directives like become_user or become_flags. This is for better visibility if a task is privileged or not.
- name: Copy hddtemp configuration file
become: true
ansible.builtin.copy:
src: "{{ ansible_os_family }}/hddtemp"
dest: "{{ hddtemp_conf_file }}"
owner: root
group: root
mode: 0644
notify: Restart hddtemp service
Position of the when condition¶
If you need to use the when condition please add this at the end-section from the task where it is needed. This makes the code easier to understand for others. For example:
- name: "Archive existing {{ resolvconf_file }} file"
become: true
ansible.posix.synchronize:
src: "/etc/resolv.conf"
dest: "/etc/resolv.conf.{{ ansible_date_time.date }}"
archive: true
delegate_to: "{{ inventory_hostname }}"
when: stat_resolvconf_file.stat.islnk is defined and not stat_resolvconf_file.stat.islnk
Usage of collections¶
Collections are always defined as in the following example.
netbox.netbox
is here the collection that is used.
- name: Configure netbox manufacturers
netbox.netbox.netbox_manufacturer:
netbox_url: "{{ netbox_url }}"
netbox_token: "{{ netbox_token }}"
data:
name: "{{ item.value.name }}"
slug: "{{ item.value.slug }}"
description: "{{ item.value.description | default('') }}"
state: present
with_dict: "{{ netbox_data_manufacturers }}"
Please don´t declare it in this way!:
collections:
- netbox.netbox
tasks:
- name: Manage Discworld site
netbox_site:
netbox_url: "{{ netbox_url }}"
netbox_token: "{{ netbox_token }}"
validate_certs: false
data:
name: Discworld
slug: discworld
state: present
The reason for that is, that the code is than more readable and easier to understand.
Parameters that offer lists¶
Parameters that provide a list are always defined as in the following example.
docker_hosts_defaults
sets the defaults in the role. Overriding is only possible
with the ansible-defaults
repository.
In the configuration repository, docker_hosts_extra is then used to add additional items to the list.
docker_hosts
itself is never modified from the outside.
docker_hosts_defaults:
- "unix:///var/run/docker.sock"
docker_hosts_extra: []
docker_hosts: "{{ docker_hosts_defaults + docker_hosts_extra }}"