Ansible Formatting Best Practices
Readable and consistent Ansible code makes reviews easier, reduces errors, and helps linters such as yamllint and ansible-lint work reliably. The following conventions have proven useful in larger playbooks and roles.
1. Use folded scalars for long Jinja expressions
Multiline Jinja expressions inside a quoted YAML scalar can confuse YAML parsers and linters.
Avoid this:
- name: Get list of items to install
ansible.builtin.set_fact:
mw_nginx_files: "{{(target_structure[mw_target_item].nginx_multi.version
|default(nginx_latest)).modules
|selectattr('rhel','equalto',ansible_distribution_major_version)
|list}}"The expression is hard to read and may break YAML formatting checks.
Use folded scalars instead:
- name: Get list of items to install
ansible.builtin.set_fact:
mw_nginx_files: >-
{{
(
target_structure[mw_target_item].nginx_multi.version
| default(nginx_latest)
).modules
| selectattr('rhel', 'equalto', ansible_distribution_major_version)
| list
}}Advantages:
- shorter line lengths
- easier readability
- cleaner
yamllintresults
2. General YAML formatting
Maintain a consistent layout across all playbooks.
Recommended conventions:
- Start YAML files with
--- - Follow the start marker with an empty line
- Add two empty lines between tasks
- End YAML files with an empty line followed by …
Example:
---
- name: Reset_tomcat_restart_list
ansible.builtin.set_fact:
tomcat_restart_list: []
- name: Reset_tomcat_stop_list
ansible.builtin.set_fact:
tomcat_stop_list: []
...This improves readability and keeps file structure consistent.
3. Always use Fully Qualified Collection Names (FQCN)
Using FQCN avoids ambiguity and improves compatibility with newer Ansible versions.
Avoid:
- name: Reset_tomcat_restart_list
set_fact:
tomcat_restart_list: []Prefer:
- name: Reset_tomcat_restart_list
ansible.builtin.set_fact:
tomcat_restart_list: []Benefits:
- explicit module origin
- better compatibility with collections
- clearer code reviews
4. Always define task names
Every task should have a descriptive name.
Avoid:
- debug: msg="supervar is set to {{ supervar }}"Prefer:
- name: Show supervar
ansible.builtin.debug:
msg: "supervar is set to {{ supervar }}"Task names improve:
- readability
- troubleshooting
- execution logs
5. Start task names with a capital letter
Use consistent capitalization for task names.
Avoid:
- name: reset_tomcat_restart_listPrefer:
- name: Reset_tomcat_restart_listConsistency improves readability in large playbooks.
6. Prefer debug: var= for variable inspection
When debugging variables, avoid iterating over them only to print their content.
Avoid:
- debug: msg="{{ item }}"
with_items: "{{ super_dict }}"This approach unnecessarily iterates over the list just to display its contents.
Prefer:
- name: Show super_dict
ansible.builtin.debug:
var: super_dict The var parameter automatically renders the full structure of a variable, including:
- lists
- dictionaries
- nested data structures
Advantages:
- no manual iteration required
- cleaner and shorter code
- better formatted output
- easier debugging of complex variables
In most debugging scenarios, var: is the simplest and most readable way to inspect variables.
7. Do not add parameters directly after the module name
Avoid placing parameters inline after the module name.
Avoid:
- name: Empty cache folders
ansible.builtin.include_tasks: "delete-cache.yaml"Prefer:
- name: Empty cache folders
ansible.builtin.include_tasks:
file: "delete-cache.yaml"This keeps parameter structures explicit and consistent.
Summary
Consistent formatting in Ansible provides several benefits:
- easier code reviews
- better linting results
- improved maintainability
- clearer execution logs
Small stylistic conventions can significantly improve the quality of large automation codebases.