Ansible Best Practices
Ansible is a tool that automates configuration management through code written in YAML. It is extremely popular, partly thanks to the fact that it works without clients and daemons: all it needs is Python and an SSH connection!
More efficient, faster, automated: Taking your IT infrastructure to the next level
Discover everything to do with infrastructure automation in our free live and on-demand webinars - from best practices to specific tool insights.
👉 Find out more now and secure valuable know-how!
Since the YAML syntax is quite user-friendly, it is fairly easy to get started with Ansible. However, without a thorough introduction to the formats and structures of Ansible, the initial result is usually “bad” code: it might work, but it is prone to yield errors in the future, be inefficient or simply unreadable.
In this article, we want to present a few of the Ansible best practices that we deem especially important. This is a taste of what we discuss during our Ansible trainings at ATIX. If you are interested in learning Ansible from the ground up with a hands-on approach, do not hesitate to contact us for more information about our trainings.
YAML
-
Use
trueinstead ofyesandfalseinstead ofno -
Insert two blank spaces per indentation level (not four and NEVER tabs!)
-
Avoid inline lists and dictionaries
-
Break lines that are longer than 80 characters:
1 a_string: > # transforms linebreaks to spaces2 R0lGO2313DdhDQAIAIAAAAAAANn3 Z2SwAAAAAsdasfDQAIAAACF4SDGQ4 ar3xxbJ9p0qa7R3fasdAS0YxwzaFME5 1IAADs=6 7 # this string doesn't have spaces8 a_folded_string_without: "R0lGO2313DdhDQAIAIAAAAAAANn9 Z2SwAAAAAsdasfDQAIAAACF4SDGQ10 ar3xxbJ9p0qa7R3fasdAS0YxwzaFME11 1IAADs="
Playbook
-
Task names:
-
Always give a name to each task
-
Start the name with a capital letter
-
Ensure the name describes the task appropriately; for example “Install Apache” instead of “Install stuff”
-
-
Use dictionary style in playbooks, for example:
1 # avoid this2 - name: Install Apache packages3 yum: name="{{ packages }}" state=present4 vars:5 packages:6 - httpd7 - httpd-devel8 9 # use this instead10 - name: Install Apache packages11 yum:12 name: "{{ packages }}"13 state: present14 vars:15 packages:16 - httpd17 - httpd-devel
-
Use the fully qualified collection name (FQCN), e.g.,
ansible.builtin.debuginstead ofdebug -
Apply privilege escalation at task level, not at play level
-
Try to avoid the modules
ansible.builtin.command,ansible.builtin.shellandansible.windows.win_shell: these modules are not idempotent! If you have no other option, try to work withchanged_when,failed_whenand (if applicable)createsandremovesto make your tasl as idempotent as possible
Vaults
-
Encrypt all sensitive variables/files using ansible-vault
-
Store the vault password securely, for example as a Jenkins secret or by using an external secret manager, such as HashiCorp’s vault
-
If you encrypt a whole file, you may forget the names of your variables => add layer of indirection for readability, for example
1 ---2 # vault.yaml3 vaulted_password: this_will_be_encrypted1 ---2 # vars.yaml3 password: "{{ vaulted_password }}"
Reusing Ansible Code
-
Separate your tasks into files and then import/include them in your playbook
-
As there are some important differences between
import_tasksandinclude_tasks(see this table), try to useimport_taskswhen possible -
In general, go for
import_*, especially because-
--list-tasksalso shows the imported tasks (and--start-at-taskworks as intended) -
--list-tagsalso shows the tags of the imported tasks -
notifyof imported tasks works (careful: you should notify one of the imported tasks, not the import_tasks task itself!) -
the options of the
import_*are passed to ALL child tasks
-
-
You should use
include_*when-
you want to loop over tasks
-
the name of the file to be included depends on a variable, for example
{{ ansible_os_family }}.yaml -
you want to apply an option ONLY to the
include_*task
-
Roles
-
Collect Ansible content meant for reuse in future projects into roles
-
Use one of the two options to define variables within a role—
defaultsandvars:-
varsrefers to variables that are not supposed to be changed by the user -
defaultsrefers to variables that can be easily overridden by the user
-
-
Add a prefix to the variables in a role to indicate to which role they belong, for example postgresql_version for a variable defined in a postgresql role (this is especially useful when you are working with multiple roles at once)
-
If you use
ansible-galaxy init my-roleto initialize a role, don’t forget to remove all unused directories in the end
Templates
Include a line at the beginning of your templates to show which role generated these files. For this purpose, the variable ansible_roleis very useful; for example, your template could start like this:
| 1 | # this file was created from the role: {{ansible_role}} |
| 2 | ***here comes your actual template*** |
-
Use the
ansible_managedfeature if you want to make it clear to other users that a specific file is generated by Ansible: you can define a variable namedansible_managedin the Ansible configuration (ansible.cfg)—see this minimal example of such anansible.cfg:1 [defaults]2 ansible_managed: Ansible managed: {file} modified3 on %Y-%m-%d %H:%M:%S by {uid} on {host}
-
o make sure your template includes information about who generated it at what time, write this variable at the beginning of your templates:
1 # {{ansible_managed}}2 # this file was created from the role: {{ansible_role}}3 ***your actual template***
Conclusion
As you can see, Ansible covers a wide range of topics. There are many places where you have to be careful in order to write elegant code and save yourself more work down the road.
We hope that this serves as a good reference and can help you in your future Ansible endeavours.
If you have any questions or would like more guidance on any of these specific topics, do not hesitate to contact us.
