Style guide
In general the Ansible best practices are used. These are the explicit conventions for the roles. The same text is available to coding assistants in AGENTS.md in every role.
- Prefer readability over complexity.
- Split logic into roles to allow composing a combination of roles.
- Roles do not solve business logic, they offer system logic. Playbooks combine roles into business logic.
- Roles need to be compatible with the distributions listed in
meta/main.yml. ansible-lintshould succeed without errors.
Development focus ordering
- Focus on the intent of the role in
meta/main.yml. - Focus on user variables, defined in
defaults/main.yml. - Focus on role variables, defined in
vars/main.yml. - Focus on tasks, templates and files.
Meta
galaxy_info.descriptioninmeta/main.ymlcaptures the intent of the role.meta/main.ymlis used to generate many other files with ansible-generator.- Only use
dependenciesif it is really required, for example for a shared handler or variable. It may surprise a user with extra roles being downloaded and executed. Soft dependencies belong inrequirements.ymlandmolecule/default/prepare.yml. - The distributions mentioned are tested using Molecule, see testing.
User variables
Defined in defaults/main.yml.
- The user will need to adjust these settings, so making life easier in this file is helpful.
- Variables start with the name of the role. The role
ansible-role-xyzhas variables that start withxyz_. This limits variable bleeding and helps a user understand where a variable is applicable. - Consider carefully if a variable is a string, integer, boolean, list or map. Changing a variable type later is difficult for users.
- Above the variable, in a comment, describe the behaviour of the variable.
- Test all variables with
ansible.builtin.assertintasks/assert.yml, and describe them inmeta/argument_specs.yml. Fail as fast as possible.
Role variables
Defined in vars/main.yml.
- These are “internal variables”. The user should not be interested in them, they are difficult to overwrite.
-
Determine a value with a lookup map:
_xyz_packages: default: - foo - bar Suse: - foobar xyz_packages: ""This pattern can be used for packages, service names, users and groups, and logic in
tasks/main.yml. - Use
ansible_facts['os_family']and notansible_os_family. - Resolve values in
vars/main.ymlto prevent unnecessarywhenconditions.
Tasks
-
Use
name:on every task and describe the intent of the task, which may differ slightly from what the task does:# Describes the intent of a task (strong) - name: Configure xyz # Describes what the task does (weak) - name: Place xyz.conf -
Spread lines vertically as much as possible, it is more readable:
# Easy to read (vertical) - name: Do something ansible.builtin.file: src: foo dest: /foo when: - xyz failed_when: - xyz == "xyz" notify: - XYZ Handler # Difficult to read (horizontal) - name: Do something ansible.builtin.file: src: foo dest: /foo when: xyz failed_when: xyz == "xyz" notify: XYZ HandlerAn added benefit: it is obvious that
when,failed_when,changed_whenand handlers are (AND) lists. - Never use an equal sign (
=) where a colon (:) is possible. - Never use Jinja in tasks or handlers. Use a mapping in
vars/main.ymlto determine a value instead. - Use FQCNs for modules, and mention the used collections in the role’s
requirements.txtandrequirements.yml. - Prefer modules over
ansible.builtin.shellandansible.builtin.command. - Always mention
state:where a module has it. ansible.builtin.filementionsowner,groupandmode.- Packages do not use
latest, unless the role is intended to update the package. - Avoid
ansible.builtin.set_fact. - For error handling, prefer
blockandrescue.failed_when: trueis never preferred, just asignore_errors: true. - Only use
gather_facts: truewhen the facts are required.
Handlers
- Don’t use the
listendirective.
Templates
- Put `` (with the correct comment style) at the top of a template.
- Although difficult, try to prevent Jinja in templates. There are exceptions.
Files
- It is nearly always beneficial to use a template. The exception is a binary file (keep in mind that Ansible is not a packaging solution).
Molecule
molecule/default/verify.ymltests the intent of the role. That can be: test that a port is open, or that an installed product can show a version number.
Linting
All roles pass ansible-lint, configured in .ansible-lint (it excludes the molecule and meta preferences files and enables name[prefix]). Lint has to pass before the Molecule job runs in CI, see testing.
No role skips lint rules for the whole role. Where a single task can’t meet a rule, an inline # noqa comment is used on that task only, with the rule name.