44 Ansible Best Practices to Follow [Tips & Tricks]

Ansible is one of the most used open-source software tools for configuration management, software provisioning, and application deployment of cloud or on-premises environments. This article will look into best practices for setting up Ansible projects and suggest approaches to deal with Ansible’s internals effectively. 

1. Generic & Project Structure Best Practices
2. Plays & Playbooks Best Practices
3. Variables Best Practices
4. Modules Best Practices
5. Roles Best Practices
6. Execution and Deployments Best Practices and Tricks

If you are new to Ansible, take a look at this Ansible Tutorial for Beginners.

In this part, we will examine and discuss general best practices and recommendations for organizing your projects and getting the most out of Ansible.

Generic Best Practices

Prefer YAML instead of JSON: Although Ansible allows JSON syntax, using YAML is preferred and improves the readability of files and projects. (See: YAML vs. JSON)

Use consistent whitespaces: To separate things nicely and improve readability, consider leaving a blank line between blocks, tasks, or other components. 

Use a consistent tagging strategy: Tagging is a powerful concept in Ansible since it allows us to group and manage tasks more granularly.  Tags provide us with the option to add fine-grained controls to the execution of tasks. 

Add comments: When you think a further explanation is needed, feel free to add a comment explaining the purpose and the reason behind plays, tasks, variables, etc. 

Use a consistent naming strategy: Before starting to set up your Ansible projects, consider applying a consistent naming convention for your tasks (always name them), plays, variables, roles, and modules. 

Define a style guide: Following a style guide might be helpful to be consistent with the above suggestions. After all, how can we be consistent if we don’t have a style guide to follow and enforce? If you are searching for inspiration, look at this style guide by OpenShift.

Keep it simple: Ansible provides many options and advanced features, but that doesn’t mean we have to use all of them. Find the Ansible parts and mechanics that fit your use case and keep your Ansible projects as simple as possible. For example, begin with a simple playbook and static inventory and add more complex structures or refactor later according to your needs.

Store your projects in a Version Control System (VCS): Keep your Ansible files in a code repository and commit any new changes regularly. 

Don’t store sensitive values in plain text: For secrets and sensitive values, use Ansible Vault to encrypt variables and files and protect any sensitive information. 

Test your ansible projects: Use linting tools like Ansible Lint and add testing steps in your CI/CD pipelines for your Ansible repositories. For testing Ansible roles, have a look at Molecule. To test inputs or verify custom expressions, you can use the assert module.

Directory Organization

Take a look at this example of how a well-organized Ansible directory structure looks:

Inventory Best Practices

Use inventory groups: Group hosts based on common attributes they might share (geography, purpose, roles, environment).

Separate Inventory per Environment: Define a separate inventory file per environment (production, staging, testing, etc.) to isolate them from each other and avoid mistakes by targeting the wrong environments. 

Dynamic Inventory: When working with cloud providers and ephemeral or fast-changing environments, maintaining static inventories might quickly become complex. Instead, set up a mechanism to synchronize the inventory dynamically with your cloud providers. 

Leverage Dynamic Grouping at runtime: We can create dynamic groups using the `group_by` module based on a specific attribute. For example, group hosts dynamically based on their operating system and run different tasks on each without defining such groups in the inventory.

Learn more about Ansible inventory: Working with Ansible Inventory – Basics and Use Cases.

In this part, we will list and discuss best practices regarding using plays & playbooks, two of the most basic components of Ansible projects.

Always mention the state of tasks: To make your tasks more understandable, explicitly set the state parameter even though it might not be necessary due to the default value.

Place every task argument in its own separate line:  This point is in line with the general approach of striving for readability in our Ansible files. Check the examples below. 

This works but isn’t readable enough:

Use this syntax instead, which improves a lot the readability and understandability of the tasks and their arguments:

Use top-level playbooks to orchestrate other lower-level playbooks: You can logically group tasks, plays, and roles into low-level playbooks and use other top-level playbooks to import them and set up an orchestration layer according to your needs. Have a look at this example for inspiration.

Use block syntax to group tasks: Tasks that relate to each other and share common attributes or tags can be grouped using the block option. Another advantage of this option is easier rollbacks for tasks under the same block.

Use handlers for tasks that should be triggered: Handlers in Ansible allow a task to be executed after something has changed. This handler will be triggered when there are changes to index.html from the above example. 

Check out the Working with Ansible Playbooks blog post for more details about playbooks.

Variables allow users to parametrize different Ansible components and store values we can reuse throughout projects. Let’s look at some best practices and tips on using Ansible variables.

Always provide sane defaults for your variables: Set default values for all groups under group_vars/all. For every role, set default role variables in roles/<role_name>/defaults/main.yml.

Use groups_vars and host_vars directories: To keep your inventory file clean, prefer setting group and hosts variables in the groups_vars and host_vars directories.

Add the role’s name as a prefix to variables: Try to be explicit when defining variable names for your roles by adding a prefix with the role name. 

Keep your variable’s setup simple: Many options are available for setting variables in Ansible. Using all of them isn’t probably the way to go unless you have specific needs. Pick the ones more appropriate for your use case and keep it as simple as possible.

Check out the How to Use Different Types of Ansible Variables blog post for more pointers and tips.

This part will display some tips and best practices for using Ansible modules efficiently in tasks. 

Keep local modules close to playbooks: Use each Ansible project’s ./library directory to store relevant custom modules. Playbooks that have a ./library directory relative to their path can directly reference any modules inside it.

Avoid command and shell modules: It’s considered a best practice to limit the usage of command and shell modules only when there isn’t another option. Instead, prefer specialized modules that provide idempotency and proper error handling. Read more about the Ansible shell module.

Specify module arguments when it makes sense: Default values can be omitted in many module arguments. To be more transparent and explicit, we can opt to specify some of these arguments, like the state in our playbook definitions.

Prefer multi-tasks in a module over loops: The most efficient way of defining a list of similar tasks, like installing packages, is to use multiple tasks in a single module. 

Document and test your custom modules: Every custom module should include examples, explicitly document dependencies, and describe return responses. New modules should be tested thoroughly before releasing. You can create testing roles and playbooks to test your custom modules and validate different test cases. 

For more details about using modules and writing your own custom modules, check the Ansible Modules – How to Use Them Efficiently blog post.

Ansible roles enable reusability and sharing of code efficiently while they provide a well-structured framework for configuring and setting our projects. This part will examine some best practices and tips for creating well-defined roles.

Follow the Ansible Galaxy Role Directory structure: Leverage the ansible-galaxy init <role_name> command to generate a default role directory layout according to Ansible Galaxy’s standards.

Keep your roles single-purposed: Each role should have a separate responsibility and distinct functionality to conform with the separation of concerns design principle. Separate your roles based on different functionalities or technical domains. 

Try to limit role dependencies: By avoiding many dependencies in your roles, you can keep them loosely coupled, develop them independently, and use them without managing complex dependencies between them.

Prefer import_role or include_role: To better control the execution order of roles and tasks, prefer using import_role or include_role over the classic roles option.

Do your due diligence for Ansible Galaxy Roles: When downloading and using content and roles from Galaxy, do your due diligence, validate their content, and pick roles from trustworthy contributors.

Store Galaxy roles used locally: To avoid depending on the upstream of Ansible Galaxy, you can store any roles from Galaxy to your code repositories and manage them as part of your project.

Ansible provides many controls and options to orchestrate execution against hosts. In this part, we will explore tips and tricks on optimally controlling Ansible execution based on our needs.

Test changes in staging first: Having a staging or testing environment to test your tasks before production is a great way to validate that your changes have the expected outcome.

Limit task execution to specific hosts: If you want to run a playbook against specific hosts, you can use the --limit flag.

Limit tasks execution to specific tasks based on tags: In case you need to run only specific tasks from a playbook based on tags, you can define which tags to be executed with the --tags flag.

Validate which tasks will run before executing: You can use the --list-tasks flag to confirm which tasks would be run without actually running them.

Validate against which hosts the playbook will run: You can use the --list-hosts flag to confirm which hosts will be affected by the playbook without running it.

Validate which changes will happen without making them: Leverage the --check flag to predict any changes that may occur. Combine it with --diff flag to show differences in changed files.

Start at a specific task: Use the --start-at-task flag to start executing your playbook at a particular task.

Use Rolling Updates to control the number of target machines: By default, Ansible attempts to run the play against all hosts in parallel. To achieve a rolling update setup, you can leverage the serial keyword. Using this keyword, you can define how many to hosts the changes can be performed in parallel.   

Control playbook execution strategy: By default, Ansible finishes the execution of each task on all hosts before moving to the next task. if you wish to select another execution strategy, have a look at this guide.

Spacelift’s vibrant ecosystem and excellent GitOps flow can greatly assist you in managing and orchestrating Ansible. By introducing Spacelift on top of Ansible, you can easily create custom workflows based on pull requests and apply any necessary compliance checks for your organization.

With Spacelift, you get:

• Better playbook automation – Manage the execution of Ansible playbooks from one central location.
• Inventory observability – View all Ansible-managed hosts and related playbooks, with clear visual indicators showing the success or failure of recent runs.
• Playbook run insights – Audit Ansible playbook run results with detailed insights to pinpoint problems and simplify troubleshooting.
• Policies – Control what kind of resources engineers can create, what parameters they can have, how many approvals you need for a run, what kind of task you execute, what happens when a pull request is open, and where to send your notifications
• Stack dependencies – Build multi-infrastructure automation workflows with dependencies, having the ability to build a workflow that, for example, generates your EC2 instances using Terraform and combines it with Ansible to configure them
• Self-service infrastructure via Blueprints, or Spacelift’s Kubernetes operator – Enable your developers to do what matters – developing application code while not sacrificing control
• Creature comforts such as contexts (reusable containers for your environment variables, files, and hooks), and the ability to run arbitrary code
• Drift detection and optional remediation

If you want to learn more about using Spacelift with Ansible, check our documentation, read our Ansible guide, or book a demo with one of our engineers.

Would you like to see this in action – or just want a tl;dr? Check out this video I put together showing you Spacelift’s new Ansible functionality:

In this blog post, we delved into best practices, tips, and tricks for operating and configuring Ansible projects. We explored approaches for structuring our Ansible projects and roles and set different configuration options regarding the inventory and variables. Lastly, we examined various tips for controlling our playbook’s execution and deployments. 

Thank you for reading, and I hope you enjoyed this article as much as I did.