Ansible Guides and Tutorials | Spacelift Blog

Author title

Title category

Get all the latest content on Infrastructure as Code, DevOps, Spacelift features & news directly to your inbox!

Level up your IaC knowledge. Stay up to date with educational devops guides & news in infrastructure as code, cloud & more!

Managing Infrastructure at Scale | Spacelift Blog

AWS: Spacelift Reduces Time Spent on Cloud Management by 90% 🚀

applepodcasts

spotify

missionctrl

Welcome to missionCTRL, a show dedicated to exploring the frontiers of modern DevOps. Listen (or watch) as we sit down with the practitioners who are pushing the boundaries of development

How to Keep Your Playbooks Secure With Ansible Vault

Ansible

This blog post will dive deep into Ansible Vault as a mechanism for keeping your sensitive values and secrets secure in your playbooks and other Ansible files. We will explore different options for working with encrypted content and password management options. 
If you are new to Ansible or interested in other Ansible concepts, <a href="https://spacelift.io/blog/ansible" target="_blank" rel="noopener">these Ansible tutorials</a> on Spacelift’s blog might be handy.

Ansible provides a native way to handle sensitive information with Ansible Vault. Ansible Vault allows users to encrypt secrets and other sensitive data such as API keys, passwords, and other credentials to protect them at rest. 
Instead of storing secrets in plaintext, Ansible Vault gives you a secure, native, and low-effort option to manage sensitive information by leveraging encryption. Using Ansible Vault, encrypted content can be stored in <a href="https://spacelift.io/blog/ansible-playbooks" target="_blank" rel="noopener">playbooks</a>, variable files, and roles, persisted under source control, and shared without exposure risks. 
Ansible Vault protects your sensitive content only at rest. Users are responsible for not exposing decrypted content in the console or any other way. Check out the <a href="https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#keep-secret-data" target="_blank" rel="nofollow noopener">no_log</a> option for tasks to hide their output if necessary.

We must use passwords to encrypt and decrypt sensitive data with Ansible Vault. The passwords are used to create encrypted variables or files, decrypt, and view or edit the encrypted content. 
To supply the password for these operations, you can either leverage the <code>ansible-vault</code> command and get prompted for it, set up a location of a password file in your main configuration definition, <code>ansible.cfg</code>, or integrate with an external secret store solution that holds your passwords. 
As you can imagine, since you have to keep track of your vault passwords, there is a process involved around password management in any of these cases. You might leverage the same password for all your encrypted content for simple cases, small teams, and a few encrypted values. This approach simplifies your password management process since you only have to deal with a single password. Store and handle this password and other sensitive data in your secret management system. 
You might have to create and manage more vault passwords for complex systems and different access levels for different teams and people. For example, you might use a different password per team, per environment, per ansible role, application, directory, or any other pattern that fits your needs. 
You can specify a dedicated vault id for every password in such cases. Whenever you generate newly encrypted content, you can pass the dedicated id with the flag <code>--vault-id</code>.  Store this id along with the password and pass it with the password during decryption. 
We will look into more examples of leveraging vault IDs in the next section on how to encrypt sensitive values. 
As discussed previously, a simple but not really secure option would be to store passwords in a local file. If you decide to go that way, make sure the file has the correct permissions, store the password as a string in a single line, and don’t persist it in any code repositories. 
A more secure and scalable way would be to use an external secret store for storing passwords and fetch them dynamically with the help of a vault password client script. A vault password client script is responsible for connecting to the remote secret store, fetching the secret, and printing the password to standard output. Look at the <a href="https://docs.ansible.com/ansible/latest/vault_guide/vault_managing_passwords.html#storing-passwords-in-third-party-tools-with-vault-password-client-scripts" target="_blank" rel="nofollow noopener">Storing passwords in third-party tools with vault password client scripts</a> section of the official documentation for details on how to create and use such scripts.

Ansible Vault can assist users with encrypting mainly two types of data, <a href="https://spacelift.io/blog/ansible-variables" target="_blank" rel="noopener">variables</a> and files. This means we can encrypt either whole files or only specific values stored in encrypted variables. 
By encrypting specific variables, our content will be decrypted on demand only when needed. This option allows us to mix encrypted and plaintext content according to our needs inside playbooks and roles. One drawback of this approach is that it works only with variables and that changing or rotating the password might be a bit cumbersome since there isn’t a command that supports this.  
On the other hand, encrypting whole files allows us to encrypt other content (for example, tasks) apart from variables, and then decryption happens when the file is referenced. We can easily use the <code>rekey</code> command to change or rotate the password used for encryption on files, and in general file-level encryption is easier to use and manage.
A disadvantage of this approach is that since we are encrypting the whole content of the files, we are trading away readability and accessibility since we can’t read the file without effort and get an understanding of its contents. One way to bypass this issue could be to keep the names or references of your encrypted content in a separate non-encrypted file. Look at <a href="https://docs.ansible.com/ansible/latest/tips_tricks/ansible_tips_tricks.html#tip-for-variables-and-vaults" target="_blank" rel="nofollow noopener">Keep vaulted variables safely visible</a> for more information on the topic. 
Let’s look at some examples next. We will start by encrypting a variable.
<h3>Encrypt Ansible Variables</h3>
To encrypt a string to use in a variable, you can leverage the <code>ansible-vault encrypt_string</code> command. 
To encrypt the string <code>encrypt_this_string_please</code> named <code>encrypted_string</code> and provide the password via the command line:

ansible-vault-encrypt_this_string_please

ansible vault encrypt_this_string_please

Notice that the produced encrypted content starts with the <code>!vault</code> tag, which indicates to Ansible that this value is encrypted and needs decryption to use. After this tag, Ansible adds a header before the encrypted content that includes the format ID, the vault format version, and the cipher algorithm used for encryption. 
If you create the encrypted variable with a vault ID, this is also included in the generated content. If you are interested in more information, check out the <a href="https://docs.ansible.com/ansible/latest/vault_guide/vault_using_encrypted_content.html#format-of-files-encrypted-with-ansible-vault" target="_blank" rel="nofollow noopener">format of files created with Ansible Vault</a> section of the official docs.

ansible-vault-vault-id

ansible vault vault ID

You can also select the password source. For example, let’s use a file named <code>password_file</code> as our password source.

ansible-vault-password_file

ansible vault password_file

To avoid persisting the secret value in your shell history, don’t pass directly with the command, but opt to be prompted for a string to encrypt like this:

You can find more command options by using the <code>--help</code> flag.

<ul>
<li><a href="https://spacelift.io/blog/infrastructure-problems-that-spacelift-solves" target="_blank" rel="noopener"><span data-sheets-value="{&quot;1&quot;:2,&quot;2&quot;:&quot;Common Infrastructure Challenges and How to Solve Them&quot;}" data-sheets-userformat="{&quot;2&quot;:513,&quot;3&quot;:{&quot;1&quot;:0},&quot;12&quot;:0}">Common Infrastructure Challenges and How to Solve Them</a></li>
<li><a href="https://spacelift.io/blog/ansible-best-practices" target="_blank" rel="noopener"><span data-sheets-value="{&quot;1&quot;:2,&quot;2&quot;:&quot;44 Ansible Best Practices to Follow [Tips &amp; Tricks]&quot;}" data-sheets-userformat="{&quot;2&quot;:513,&quot;3&quot;:{&quot;1&quot;:0},&quot;12&quot;:0}">44 Ansible Best Practices to Follow</a></li>
<li><a href="https://spacelift.io/blog/spacelift-ansible-integration-beta" target="_blank" rel="noopener">How to Manage Ansible More Securely </a></li>
</ul>

<h3>Encrypt Ansible Files</h3>
To encrypt whole files that include structured data, you can leverage the <code>ansible-vault create</code> or the <code>ansible-vault encrypt</code> commands. Different files that can be encrypted include group, host, defaults, roles, and other custom variable files, tasks files, handlers files, binary, or other arbitrary files.
To create a new encrypted file, <code>encrypted_file.yml</code>, with vault ID dev, and get prompted for the password, use this command:

This will open your configured editor to provide the content to be encrypted. The same considerations discussed earlier for storing and using Ansible Vault passwords also apply here. 
Next, let’s see an example of encrypting an existing file. This operation is as simple as running this command:

In the previous section, we explained the process and went over several options for encrypting different content with Ansible Vault. Now, let’s look at how we can utilize and work with encrypted content. 
One of the most common operations for a user is to be able to view the encrypted content if necessary. You can leverage the <code>debug</code> module to view the plaintext value of encrypted content. 
Let’s create a simple encrypted variable and pass the password via the prompt:

ansible-vault-pass-the-password-via-the-prompt

ansible vault pass the password via the prompt

Next, we store this variable in a file named <code>file_with_stored_encrypted_variable.yml</code>.

ansible-vault-store-variable-in-a-file

ansible vault store variable in a file

To view the encrypted value, use the <code>debug</code> module and pass the location of the password as we have seen earlier:

Viewing the contents of encrypted files is quite simple with the <code>ansible-vault view</code> command:

Another handy option when working with encrypted files is the ability to edit the encrypted content with the <code>ansible-vault edit</code> command:

This command prompts the user for the password, decrypts the content to a temporary file, allows the user to edit the encrypted content with the configured editor, and finally saves and re-encrypts the file. 
To permanently decrypt an encrypted file, use the <code>ansible-vault decrypt</code> command:

Another common operation is to rotate or change the password used for encryption. As briefly discussed in the previous section, this can be achieved with the <code>ansible-vault rekey</code> command. 
To change the password for an encrypted file, use the below command, and pass the current and the new password when prompted:

When you need to decrypt content from a playbook with encrypted variables that have been created with different passwords and vault IDs, pass multiple <code>--vault-id</code> flags when executing the playbook. For example:

In case you use a specific vault ID or a password source more frequently than others, you can define default options and avoid passing them every time. Leverage <a href="https://docs.ansible.com/ansible/latest/reference_appendices/config.html#default-vault-identity-list" target="_blank" rel="nofollow noopener">DEFAULT_VAULT_DENY_LIST</a> and <a href="https://docs.ansible.com/ansible/latest/reference_appendices/config.html#default-vault-password-file" target="_blank" rel="nofollow noopener">DEFAULT_VAULT_PASSWORD_FILE</a> to set this up.

In this blog post, we explored different options for encrypting sensitive information by leveraging Ansible Vault. We explained Ansible Vault’s main functionality and discussed various options for handling sensitive content, passwords, and files. Lastly, we went over examples and use cases of using encrypted content. 
You can also explore how <a href="https://spacelift.io/?utm_source=blog&amp;utm_medium=text&amp;utm_id=blogpost&amp;utm_content=%7Bansible_vault%7D" target="_blank" rel="noopener">Spacelift</a>’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 then easily <a href="https://docs.spacelift.io/concepts/policy/trigger-policy" target="_blank" rel="noopener">create custom workflows</a> based on pull requests and apply any necessary <a href="https://docs.spacelift.io/concepts/policy/terraform-plan-policy" target="_blank" rel="noopener">compliance checks</a> for your organization.
Thank you for reading and I hope you enjoyed this as much as I did!

<span data-sheets-value="{&quot;1&quot;:2,&quot;2&quot;:&quot;Spacelift is a flexible orchestration solution for IaC development. It delivers enhanced collaboration, automation and controls to simplify and accelerate the provisioning of cloud based infrastructures.&quot;}" data-sheets-userformat="{&quot;2&quot;:769,&quot;3&quot;:{&quot;1&quot;:0},&quot;11&quot;:4,&quot;12&quot;:0}">Spacelift is a flexible orchestration solution for IaC development. It delivers enhanced collaboration, automation and controls to simplify and accelerate the provisioning of cloud based infrastructures.

Terraform vs. Ansible : Key Differences and Comparison of Tools

Working with Ansible Inventory - Basics and Use Cases

Ansible Roles : Basics & How to Combine Them With Playbooks

Explore different options for encrypting sensitive information by leveraging Ansible Vault with examples and use cases of using encrypted content.

134-ansible_vault

How to Keep Your Playbooks Secure Using Ansible Vault

In this blog post, we will dive deep into different concepts around building an Ansible inventory, along with best practices. We will look into basic functionality, managing variables, and combining multiple inventory sources and options for working with dynamic inventories. 
If you are new to Ansible or interested in other Ansible concepts, <a href="https://spacelift.io/blog/ansible" target="_blank" rel="noopener">these Ansible tutorials</a> on Spacelift’s blog might be handy.

An Ansible inventory is a collection of managed hosts we want to manage with Ansible for various automation and configuration management tasks. Typically, when starting with Ansible, we define a static list of hosts known as the inventory. These hosts can be grouped into different categories, and then we can leverage various patterns to run our playbooks selectively against a subset of hosts. 
By default, the inventory is stored in <code>/etc/ansible/hosts</code>, but you can specify a different location with the <code>-i</code> flag or the <a href="https://docs.ansible.com/ansible/latest/installation_guide/intro_configuration.html#configuration-file" target="_blank" rel="nofollow noopener">ansible.cfg</a> configuration file. 
Let’s take a look at what a simple inventory looks like. The most common formats are either INI or <a href="https://spacelift.io/blog/yaml" target="_blank" rel="noopener">YAML</a>.

In this example, we use the INI format, define four managed hosts, and we group them into two host groups; webservers and databases. The group names can be specified between brackets, as shown above.
Inventory groups are one of the handiest ways to control Ansible execution. Hosts can also be part of multiple groups.

Note: By default, we can also reference two groups without defining them. The <code>all</code> group targets all our hosts in the inventory, and the <code>ungrouped</code> contains any host that isn’t part of any user-defined group.
We can also create nested groups of hosts if necessary.

To list a range of hosts with similar patterns, you can leverage the range functionality instead of defining them one by one. For example, to define ten hosts (host01, host02, …. host10):

Another useful functionality is the option to define aliases for hosts in the inventory. For example, we can run Ansible against the host alias <code>host01</code> if we define it in the inventory as:

A typical pattern for inventory setups is separating inventory files per environment. Find below an example of keeping separate staging and production inventories.
staging_inventory

production_inventory

When defining groups of hosts in the inventory, we categorize them based on application, function, location, department, and other shared characteristics between hosts, allowing us to target them in groups. Try understanding which groups make sense for your use case and automation needs.

An important aspect of Ansible’s project setup is variable’s assignment and management. Ansible offers many different ways of setting variables (check this blog post for <a href="https://spacelift.io/blog/ansible-variables" target="_blank" rel="noopener">detailed information about Ansible variables</a>), and defining them in the inventory is one of them. 
For example, let’s define one variable for a different application version for every host in our dummy inventory from before.

Ansible-specific connection variables such as <code>ansible_user</code> or <code>ansible_host</code> are examples of host variables defined in the inventory. Check the <a href="https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#connecting-to-hosts-behavioral-inventory-parameters" target="_blank" rel="nofollow noopener">Connecting to hosts: behavioral inventory parameters</a> section of the docs for more options.
Similarly, variables can also be set at the group level in the inventory and offer a convenient way to apply variables to hosts with common characteristics.

Although setting variables in the inventory is possible, it’s usually not the preferred way. Instead, store separate host and group variable files to enable better organization and clarity for your Ansible projects. Note that host and group variable files must use the YAML syntax. 
In the same directory where we keep our inventory file, we can create two folders named <code>group_vars</code> and <code>host_vars</code> containing our variable files. For example, we could have a file <code>group_vars/webservers</code> that contains all the variables for web servers:
group_vars/webservers

A possible use case for having separate variable files instead of storing them in the inventory is to keep sensitive values without persisting them in <a href="https://spacelift.io/blog/ansible-playbooks" target="_blank" rel="noopener">playbooks</a> or source control systems. 
As mentioned, there are multiple options to set variables in Ansible, so look at the official documentation <a href="https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#understanding-variable-precedence" target="_blank" rel="nofollow noopener">Understanding variable precedence</a> and <a href="https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#how-we-merge" target="_blank" rel="nofollow noopener">How variables are merged</a> if you plan on using different layers for your vars.

We have the option to combine different inventories and sources, such as directories, dynamic inventory scripts, or inventory plugins during runtime or in the configuration. 
This becomes especially useful in cases where we want to target multiple environments or otherwise isolated setups. For example, to target the <code>development</code>, <code>testing</code>, <code>staging</code>, and <code>production</code> hosts all at the same time:

We can combine multiple inventory sources in a directory and then manage them as one. This approach comes in handy when controlling static and dynamic hosts.

Then, we can run playbooks against all hosts in these inventories like this:

Many modern environments are dynamic, cloud-based, possibly spread across multiple providers, and constantly changing. In these cases, maintaining a static list of managed nodes is time-consuming, manual, and error-prone. 
Ansible has two methods to properly track and target a dynamic set of hosts: inventory plugins and inventory scripts. The official suggestion is to prefer inventory plugins that benefit from the recent updates to ansible core. 
To see a list of available inventory plugins you can leverage to build dynamic inventories, you can execute <code>ansible-doc -t inventory -l</code>. We will look at one of them, the <code>amazon.aws.aws_ec2</code>, to get hosts from Amazon Web Services EC2. 
For plugin-specific docs and examples, use the command <code>ansible-doc -t inventory amazon.aws.aws_ec2</code>. Install the Ansible Galaxy collection <code>amazon.aws</code> to work with the plugin by running <code>ansible-galaxy collection install amazon.aws</code>
For this example, we have created four ec2 instances on AWS, and we would like to build an inventory file dynamically using the plugin.

ansible-inventory-aws-instance

Ansible inventory AWS instance

We added two tags, <code>environment</code> and <code>role</code>, on these ec2 instances that we will later use to create inventory groups. 
Let’s create a YAML file named <code>dynamic_inventory_aws_ec2.yml</code> with the plugin configuration required for our use case.
dynamic_inventory_aws_ec2.yml

We declare the plugin we want to use and other options, including regions to consider fetching data from, setting hostnames from the tag <code>Name</code>, and creating inventory groups based on region, environment, and role. 
Let’s view the generated inventory with the command:

dynamic-inventory-aws-ec2

Dynamic Inventory AWS EC2

The plugin fetches information from our AWS account and creates several groups according to our configuration and options. 
To persist the inventory to a file, you can use this command:

In case you want to integrate a source that isn’t covered by the existing inventory plugins, you also have the option to <a href="https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html#developing-inventory-plugins" target="_blank" rel="nofollow noopener">develop your own custom inventory plugin</a>.

In this article, we explored Ansible inventory basics and various use cases for defining groups and variables in static inventories. We also learned how to combine multiple inventory sources and an example of fetching our inventory of hosts dynamically from AWS. 
You can also explore how <a href="https://spacelift.io/?utm_source=blog&amp;utm_medium=text&amp;utm_id=blogpost&amp;utm_content=%7Bansible_inventory%7D" target="_blank" rel="noopener">Spacelift</a>’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 then easily <a href="https://docs.spacelift.io/concepts/policy/trigger-policy" target="_blank" rel="noopener">create custom workflows</a> based on pull requests and apply any necessary <a href="https://docs.spacelift.io/concepts/policy/terraform-plan-policy" target="_blank" rel="noopener">compliance checks</a> for your organization.
Thank you for reading, and I hope you enjoyed this as much as I did.

Spacelift is a sophisticated SaaS product for Infrastructure as Code that helps DevOps develop and deploy new infrastructures or changes quickly and with confidence. It supports Terraform, Cloudformation, Pulumi, and Kubernetes, with initial support for Ansible.

44 Ansible Best Practices to Follow [Tips & Tricks]

Ansible Modules - How To Use Them Efficiently (Examples)

How Spacelift Can Improve Your Infrastructure as Code

Learn about Ansible inventory basic functionality, managing variables, and combining multiple inventory sources and options for dynamic inventories.

133-ansible-inventory

Working with Ansible Inventory

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. 
<ol>
<li><a href="https://spacelift.io/blog/ansible-best-practices#1-generic--project-structure-best-practices">Generic &amp; Project Structure Best Practices</a></li>
<li><a href="https://spacelift.io/blog/ansible-best-practices#2-plays--playbooks-best-practices">Plays &amp; Playbooks Best Practices</a></li>
<li><a href="https://spacelift.io/blog/ansible-best-practices#3-variables-best-practices">Variables Best Practices</a></li>
<li><a href="https://spacelift.io/blog/ansible-best-practices#4-modules-best-practices">Modules Best Practices</a></li>
<li><a href="https://spacelift.io/blog/ansible-best-practices#5-roles-best-practices">Roles Best Practices</a></li>
<li><a href="https://spacelift.io/blog/ansible-best-practices#6-execution-and-deployments-best-practices-and-tricks">Execution and Deployments Best Practices and Tricks</a></li>
</ol>
If you are new to Ansible, take a look at this <a href="https://spacelift.io/blog/ansible-tutorial">Ansible Tutorial for Beginners</a>.

In this part, we will examine and discuss general best practices and recommendations for organizing your projects and getting the most out of Ansible.
<h3>Generic Best Practices</h3>
Prefer YAML instead of JSON: Although Ansible allows JSON syntax, using YAML is preferred and improves the readability of files and projects. (See: <a href="https://spacelift.io/blog/yaml#yaml-vs-json">YAML vs. JSON</a>)
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: <a href="https://docs.ansible.com/ansible/latest/user_guide/playbooks_tags.html" target="_blank" rel="nofollow noopener">Tagging</a> 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 <a href="https://github.com/openshift/openshift-ansible/blob/master/docs/style_guide.adoc" target="_blank" rel="nofollow noopener">this style guide by OpenShift</a>.
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&#8217;t store sensitive values in plain text: For secrets and sensitive values, use <a href="https://spacelift.io/blog/ansible-vault" target="_blank" rel="noopener">Ansible Vault</a> to encrypt variables and files and protect any sensitive information. 
Test your ansible projects: Use linting tools like <a href="https://github.com/ansible/ansible-lint" target="_blank" rel="nofollow noopener">Ansible Lint</a> and add testing steps in your CI/CD pipelines for your Ansible repositories. For testing Ansible roles, have a look at <a href="https://molecule.readthedocs.io/en/latest/" target="_blank" rel="nofollow noopener">Molecule</a>. To test inputs or verify custom expressions, you can use the <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/assert_module.htmls" target="_blank" rel="nofollow noopener">assert module</a>.

<h3>Directory Organization</h3>
Take a look at this example of how a well-organized Ansible directory structure looks:

<h3>Inventory Best Practices</h3>
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 <a href="https://docs.ansible.com/ansible/2.8/user_guide/intro_dynamic_inventory.html" target="_blank" rel="nofollow noopener">synchronize the inventory dynamically with your cloud providers</a>. 
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: <a href="https://spacelift.io/blog/ansible-inventory" target="_blank" rel="noopener">Working with Ansible Inventory – Basics and Use Cases</a>.

In this part, we will list and discuss best practices regarding using plays &amp; 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 <a href="https://docs.ansible.com/ansible/2.8/user_guide/playbooks_best_practices.html#top-level-playbooks-are-separated-by-role" target="_blank" rel="nofollow noopener">this example</a> 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 allow a task to be executed after something has changed. This handler will be triggered when there are changes to <code>index.html</code> from the above example.

Check out the <a href="https://spacelift.io/blog/ansible-playbooks" target="_blank" rel="noopener">Working with Ansible Playbooks</a> 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 <code>group_vars/all</code>. For every role, set default role variables in <code>roles/&lt;role_name&gt;/defaults.main.yml</code>.
Use groups_vars and host_vars directories: To keep your inventory file clean, prefer setting group and hosts variables in the <code>groups_vars</code> and <code>host_vars</code> 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: <a href="https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable" target="_blank" rel="nofollow noopener">Many options are available for setting variables in Ansible</a>. 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 <a href="https://spacelift.io/blog/ansible-variables" target="_blank" rel="noopener">How to Use Different Types of Ansible Variables</a> 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&#8217;s <code>./library</code> directory to store relevant custom modules. Playbooks that have a <code>./library</code> 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 <code>command</code> and <code>shell</code> modules only when there isn&#8217;t another option. Instead, prefer specialized modules that provide idempotency and proper error handling. 
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 <code>state</code> 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 <a href="https://spacelift.io/blog/ansible-modules" target="_blank" rel="noopener">Ansible Modules &#8211; How to Use Them Efficiently</a> blog post.

<a href="https://spacelift.io/blog/ansible-roles" target="_blank" rel="noopener">Ansible roles</a> 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 <code>ansible-galaxy init &lt;role_name&gt;</code> command to generate a default role directory layout according to Ansible Galaxy’s standards.

ansible-galaxy

ansible galaxy

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 <code>import_role</code> or <code>include_role</code> over the classic <code>roles</code> 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 <code>--limit</code> 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 <code>--tags</code> flag.
Validate which tasks will run before executing: You can use the <code>--list-tasks</code> flag to confirm which tasks would be run without actually running them.
Validate against which hosts the playbook will run: You can use the <code>--list-hosts</code> flag to confirm which hosts will be affected by the playbook without running it.
Validate which changes will happen without making them: Leverage the <code>--check</code> flag to predict any changes that may occur. Combine it with <code>--diff</code> flag to show differences in changed files.
Start at a specific task: Use the <code>--start-at-task</code> 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 <a href="https://docs.ansible.com/ansible/latest/user_guide/playbooks_strategies.html#setting-the-batch-size-with-serial" target="_blank" rel="nofollow noopener">serial</a> 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 <a href="https://docs.ansible.com/ansible/latest/user_guide/playbooks_strategies.html#controlling-playbook-execution-strategies-and-more" target="_blank" rel="nofollow noopener">look at this guide</a>.

<a href="https://spacelift.io/?utm_source=blog&amp;utm_medium=text&amp;utm_id=blogpost&amp;utm_content=%7Bansible_best_practices%7D" target="_blank" rel="noopener">Spacelift</a>’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 then easily <a href="https://docs.spacelift.io/concepts/policy/trigger-policy" target="_blank" rel="noopener">create custom workflows</a> based on pull requests and apply any necessary <a href="https://docs.spacelift.io/concepts/policy/terraform-plan-policy" target="_blank" rel="noopener">compliance checks</a> for your organization. Another great advantage of using Spacelift is that you can manage different infrastructure tools like Ansible, Terraform, Pulumi, AWS CloudFormation, and even Kubernetes from the same place and combine their <a href="https://docs.spacelift.io/concepts/stack/" target="_blank" rel="noopener">Stacks</a> with building workflows across tools.

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.

Spacelift is a sophisticated SaaS product for Infrastructure as Code that helps DevOps develop and deploy new infrastructures or changes quickly and with confidence. It supports Terraform, Cloudformation, Pulumi, and Kubernetes, with initial support for Ansible.

8 Popular Terraform Alternatives You Should Know

This article will look into best practices for setting up Ansible projects and suggest approaches to deal with Ansible’s internals effectively. 

108-ansible-best-practices

Ansible best practices

Ansible Modules: Basics & How to Use Them Efficiently

This article delves into Ansible modules, one of the core building blocks of Ansible. In this blog post, we will examine the purpose and usage of modules, along with information on how to build them and best practices. 
If you are interested in other Ansible concepts, <a href="https://spacelift.io/blog/ansible" target="_blank" rel="noopener">these Ansible tutorials</a> posted on Spacelift’s blog might be helpful for you.

Modules represent distinct units of code, each one with specific functionality. Basically, they are standalone scripts written for a particular job and are used in tasks as their main functional layer.
We build Ansible modules to abstract complexity and provide end-users with an easier way to execute their automation tasks without needing all the details. This way, some of the cognitive load of more complex tasks is abstracted away from Ansible users by leveraging the appropriate modules. 
Here’s an example of a task using the apt package manager module to install a specific version of Nginx.

Modules can be executed as well directly from the command line. Here’s an example of running the ping module against all the database hosts from the command line.

A well-designed module provides a predictable and well-defined interface that accepts arguments that make sense and are consistent with other modules. Modules take some arguments as input and return values in JSON format after execution. 
Ansible modules should follow <a href="https://docs.ansible.com/ansible/latest/reference_appendices/glossary.html#term-Idempotency" target="_blank" rel="nofollow noopener">idempotency principles</a>, which means that consecutive runs of the same module should have the same effect if nothing else changes. Well-designed modules detect if the current and desired state match and avoid making changes if that’s the case. 
We can utilize handlers to control the flow execution of modules and tasks in a <a href="https://spacelift.io/blog/ansible-playbooks" target="_blank" rel="noopener">playbook</a>. Modules can trigger additional downstream modules and tasks by notifying specific handlers.
As mentioned, modules return data structures in JSON data. We can store these return values in variables and use them in other tasks or display them to the console. Look at the <a href="https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html" target="_blank" rel="nofollow noopener">common return values</a> for all modules to get an idea. 
For custom modules, the return values should be documented along with other useful information for the module. The command-line tool <code>ansible-doc</code> displays this information. 
Here’s an example output of running the ansible-doc command.

ansible-doc-ansible-modules

run ansible-doc

In the latest versions of Ansible, most modules are part of <a href="https://docs.ansible.com/ansible/latest/user_guide/collections_using.html" target="_blank" rel="nofollow noopener">collections</a>, a distribution format that includes roles, modules, plugins, and playbooks. Many of the core modules we use extensively are part of the <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/index.html#plugins-in-ansible-builtin" target="_blank" rel="nofollow noopener">Ansible.Builtin</a> collection. To find other available modules have a look at the <a href="https://docs.ansible.com/ansible/latest/collections/index.html#list-of-collections" target="_blank" rel="nofollow noopener">Collection docs</a>.

In this part, we explore some of the most used and helpful modules, and for each, we provide a working example. The modules in this list are picked based on their popularity within the Ansible community and functionality to perform everyday automation tasks.
<h3>Package Manager Modules yum &amp; apt</h3>
The <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/apt_module.html" target="_blank" rel="nofollow noopener">apt module</a> is part of ansible-core and manages apt packages for Debian/Ubuntu Linux distributions. Here’s an example that updates the repository cache and updates the Nginx package to the latest version:

The <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/yum_module.html" target="_blank" rel="nofollow noopener">yum module</a> is also part of ansible-core and manages packages with yum for RHEL/Centos/Fedora Linux distributions. Here’s the same example as above with the yum module:

<h3>Service Module</h3>
The <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/service_module.html" target="_blank" rel="nofollow noopener">service module</a> controls services on remote hosts and can leverage different init systems depending on their availability in a system. This module provides a nice abstraction layer for underlying service manager modules. Here’s an example of restarting the docker service:

<h3>File Module</h3>
The <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/file_module.html" target="_blank" rel="nofollow noopener">file module</a> handles operations to files, symlinks, and directories. Here’s an example of using this module to create a directory with specific permissions:

<h3>Copy Module</h3>
The <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/copy_module.html" target="_blank" rel="nofollow noopener">copy module</a> copies files to the remote machine and handles file transfers or moves within a remote system. Here’s an example of copying a file to the remote machine with permissions set:

<h3>Template Module</h3>
The <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/template_module.html" target="_blank" rel="nofollow noopener">template module</a> assists us to template files out to target hosts by leveraging the <a href="https://jinja.palletsprojects.com/en/3.1.x/" target="_blank" rel="nofollow noopener">Jinja2 templating language</a>. Here’s an example of using a template file and some set Ansible variables to generate an Nginx configuration file:

<h3>Lineinfile &amp; Blockinfile Modules</h3>
The <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/lineinfile_module.html" target="_blank" rel="nofollow noopener">lineinfile module</a> adds, replaces, or ensures that a particular line exists in a file. It’s pretty common to use this module when we need to update a single line in configuration files.

The <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/blockinfile_module.html" target="_blank" rel="nofollow noopener">blockinfile module</a> inserts, updates, or removes a block of lines from a file. It has the same functionality as the previous module but is used when you want to manipulate multi-line text blocks.

<h3>Cron Module</h3>
The <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/cron_module.html" target="_blank" rel="nofollow noopener">cron module</a> manages crontab entries and environment variables entries on remote hosts.

<h3>Wait_for Module</h3>
The <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/wait_for_module.html" target="_blank" rel="nofollow noopener">wait_for module</a> provides a way to stop the execution of plays and wait for conditions, amount of time to pass, ports to become open, processes to finish, files to be available, strings to exist in files, etc.

<h3>Command &amp; Shell Modules</h3>
The <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/command_module.html" target="_blank" rel="nofollow noopener">command</a> and <a href="https://docs.ansible.com/ansible/latest/collections/ansible/builtin/shell_module.html" target="_blank" rel="nofollow noopener">shell</a> modules execute commands on remote nodes. Their main difference is that the command module bypasses the local shell, and consequently, variables like $HOSTNAME or $HOME aren’t available, and operations like “&lt;”, “&amp;” don’t work. If you need these features, you have to use the shell module. 
On the other hand, the remote local environment won’t affect the command module, so its outcome is considered more predictable and secure. 
Usually, it’s always preferred to use specialized Ansible modules to perform tasks instead of command and shell. There are cases, though, where you won’t be able to get the functionality that you need from specialized modules, and you will have to use one of these two. Use command and shell with care, and always try to check if there is a specialized module that can serve you better before relying on them.

For advanced users, there is always the option to develop custom modules if they have needs that can’t be satisfied by existing modules. Since modules always should return JSON data, they can be written in any programming language. 
Before jumping into module development, ensure that a similar module doesn&#8217;t exist to avoid unnecessary work. Αdditionally, you might be able to combine different modules to achieve the functionality you need. In this case, you might be able to replicate the behavior you want by creating a role that leverages other modules. Another option is to use <a href="https://docs.ansible.com/ansible/latest/plugins/plugins.html" target="_blank" rel="nofollow noopener">plugins</a> to enhance Ansible’s basic functionality with logic and new features accessible to all modules.
Next, we will go through an example of creating a custom module that takes as input a string that represents an epoch timestamp and converts it to its human-readable equivalent of type <a href="https://docs.python.org/3/library/datetime.html" target="_blank" rel="nofollow noopener">datetime</a> in Python. You can find the code for this tutorial <a href="https://github.com/spacelift-io-blog-posts/Blog-Technical-Content/tree/master/ansible-modules" target="_blank" rel="nofollow noopener">on this repository</a>.
First, let’s create a <code>library</code> directory on the top of our repository to place our custom module. Playbooks with a <code>./library</code> directory relative to their YAML file can add custom ansible modules that can be recognized in the ansible module path. This way, we can group custom modules and their related playbooks. 
We create our custom Python module <code>epoch_converter.py</code> inside the library directory. This simple module takes as input the argument <code>epoch_timestamp</code> and converts it to datetime type. We use another argument, <code>state_changed</code>, to simulate a change in the target system by this module.
library/epoch_converter.py

To test our module, let’s create a <code>test_custom_module.yml</code> playbook in the same directory as our <code>library</code> directory.
test_custom_module.yml

Last stop, let’s execute the playbook to test our custom module. Since we opted to set the <code>state_changed</code> argument, we expect the task state to appear as <code>changed</code> and displayed in yellow.

ansible-modules-example

ansible modules example

If you wish to contribute to an existing Ansible collection or create and publish a new one with your custom modules, look at <a href="https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_distributing.html#publishing-your-collection" target="_blank" rel="nofollow noopener">Distributing collections</a> and <a href="https://docs.ansible.com/ansible/latest/community/index.html#ansible-community-guide" target="_blank" rel="nofollow noopener">Ansible Community Guide</a>, where you can find information on how to configure and distribute Ansible content.

Use specialized modules over shell or command: Although It might be tempting to use the <code>shell</code> or <code>command</code> module often, it’s considered a best practice to leverage more specific modules for each job. Specialized modules are typically recommended because they implement the concept of desired state and idempotency, have been tested, and fulfill basic standards, like error handling.
Specify arguments when it makes sense: Some module arguments have default values that can be omitted. To be more transparent and explicit, we can opt to specify some of these arguments like the <code>state</code> 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.

The above method should be preferred over the <code>loop</code> or defining multiple separate tasks using the same module.
Custom modules should be simple and tackle a specific job: If you decide to build your own module, focus on solving a particular problem. Each module should have a concise functionality, be as simple as possible, and perform one thing well. If what you try to achieve goes beyond the scope of a single module, consider <a href="https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_in_groups.html#developing-modules-in-groups" target="_blank" rel="nofollow noopener">developing a new collection</a>.
Custom modules should have predictable parameters: Try to enable others to use your module by defining a transparent and predictable user interface. The arguments should be well-scoped and understandable, and their structures should be as simple as possible. Follow the typical convention of parameter names in lowercase and use underscores as the word separator.
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 roles and playbooks to test your custom modules and different test cases.

We deep-dived into Ansible modules and examined their use and functionality in detail. We discussed best practices and showed practical examples of leveraging the most commonly-used modules. Lastly, we went through a complete example of developing a custom module. 
You can also explore how <a href="https://spacelift.io/?utm_source=blog&amp;utm_medium=text&amp;utm_id=blogpost&amp;utm_content=%7Bansible_modules%7D" target="_blank" rel="noopener">Spacelift</a>’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 then easily <a href="https://docs.spacelift.io/concepts/policy/trigger-policy" target="_blank" rel="noopener">create custom workflows</a> based on pull requests and apply any necessary <a href="https://docs.spacelift.io/concepts/policy/terraform-plan-policy" target="_blank" rel="noopener">compliance checks</a> for your organization. Get started on your journey by <a href="https://spacelift.io/free-trial?utm_source=blog&amp;utm_medium=text&amp;utm_id=blogpost&amp;utm_content=%7Bansible_modules%7D" target="_blank" rel="noopener">creating a free trial account</a>.
Thank you for reading, and I hope you enjoyed this article as much as I did.

Spacelift is a flexible orchestration solution for IaC development. It delivers enhanced collaboration, automation and controls to simplify and accelerate the provisioning of cloud based infrastructures.

16 DevOps Best Practices Every Developer Should Know

Ansible Tutorial for Beginners: Ultimate Playbook & Examples

Modules are one of the core building blocks of Ansible. Learn how to build them and see best practices. Explore some of the most used and helpful modules.

81-ansible-modules

This blog post explores the concept of Ansible roles, their structure, and how we can combine them with our playbooks. We will analyze their functionality and usage along with ways to create new roles and retrieve public shared roles from Ansible Galaxy, a public repository for Ansible resources.
If you are new to Ansible, you might also find these tutorials helpful <a href="https://spacelift.io/blog/ansible-tutorial" target="_blank" rel="noopener">Ansible Tutorial for Beginners</a>, <a href="https://spacelift.io/blog/ansible-playbooks" target="_blank" rel="noopener">Working with Ansible Playbooks</a>, and <a href="https://spacelift.io/blog/ansible-variables" target="_blank" rel="noopener">How to Use Different Types of Ansible Variables</a>.

When starting with Ansible, it’s pretty common to focus on writing playbooks to automate repeating tasks quickly. As new users automate more and more tasks with playbooks and their Ansible skills mature, they reach a point where using just Ansible playbooks is limiting. Ansible Roles to the rescue!
Roles enable us to reuse and share our Ansible code efficiently. They provide a well-defined framework and structure for setting your tasks, variables, handlers, metadata, templates, and other files. This way, we can reference and call them in our playbooks with just a few lines of code while we can reuse the same roles over many projects without the need to duplicate our code.
Since we have our code grouped and structured according to the Ansible standards, it is quite straightforward to share it with others. We will see an example of how we can accomplish that later with Ansible Galaxy. 
Organizing our Ansible content into roles provides us with a structure that is more manageable than just using playbooks. This might not be evident in minimal projects but as the number of playbooks grows, so does the complexity of our projects. 
Lastly, placing our Ansible code into roles lets us organize our automation projects into logical groupings and follow the separation of concerns design principle. Collaboration and velocity are also improved since different users can work on separate roles in parallel without modifying the same playbooks simultaneously.

Let’s have a look at the standard role directory structure. For each role, we define a directory with the same name. Inside, files are grouped into subdirectories according to their function. A role must include at least one of these standard directories and can omit any that isn’t actively used.
To assist us with quickly creating a well-defined role directory structure skeleton, we can leverage the command ansible-galaxy init &lt;your_role_name&gt;. The ansible-galaxy command comes bundled with Ansible, so there is no need to install extra packages.
Create a skeleton structure for a role named test_role:

image4-18

test_role

This command generates this directory structure:

image5-16

Directory structure

Ansible checks for main.yml files, possible variations, and relevant content in each subdirectory. It’s possible to include additional YAML files in some directories. For instance, you can group your tasks in separate YAML files according to some characteristic.
<ul>
<li aria-level="1">defaults &#8211;  Includes default values for variables of the role. Here we define some sane default variables, but they have the lowest priority and are usually overridden by other methods to customize the role.</li>
<li aria-level="1">files  &#8211; Contains static and custom files that the role uses to perform various tasks.</li>
<li aria-level="1">handlers &#8211; A set of <a href="https://docs.ansible.com/ansible/latest/user_guide/playbooks_handlers.html" target="_blank" rel="nofollow noopener">handlers</a> that are triggered by tasks of the role. </li>
<li aria-level="1">meta &#8211; Includes metadata information for the role, its dependencies, the author, license, available platform, etc.</li>
<li aria-level="1">tasks &#8211; A list of tasks to be executed by the role. This part could be considered similar to the task section of a playbook.</li>
<li aria-level="1">templates &#8211; Contains <a href="https://docs.ansible.com/ansible/latest/user_guide/playbooks_templating.html" target="_blank" rel="nofollow noopener">Jinja2</a> template files used by tasks of the role.</li>
<li aria-level="1">tests &#8211; Includes configuration files related to role testing.</li>
<li aria-level="1">vars &#8211; Contains variables defined for the role. These have quite a high <a href="https://docs.ansible.com/ansible/latest/user_guide/playbooks_templating.html" target="_blank" rel="nofollow noopener">precedence</a> in Ansible.</li>
</ul>
Another directory that wasn’t automatically generated by the ansible-galaxy init command but is mentioned in the official Ansible docs, and you might find helpful in some cases, is the library directory. Inside it, we define any custom modules and plugins that we have written and used by the role. Finally, we also have a preconfigured README.md file that we can fill with details and useful information about our role.

<ul>
<li><a href="https://spacelift.io/blog/infrastructure-problems-that-spacelift-solves" target="_blank" rel="noopener"><span data-sheets-value="{&quot;1&quot;:2,&quot;2&quot;:&quot;Common Infrastructure Challenges and How to Solve Them&quot;}" data-sheets-userformat="{&quot;2&quot;:513,&quot;3&quot;:{&quot;1&quot;:0},&quot;12&quot;:0}">Common Infrastructure Challenges and How to Solve Them</a></li>
<li><a href="https://spacelift.io/blog/how-specialized-solution-can-improve-your-iac" target="_blank" rel="noopener"><span data-sheets-value="{&quot;1&quot;:2,&quot;2&quot;:&quot;10 Ways to Improve Your Infrastructure as Code&quot;}" data-sheets-userformat="{&quot;2&quot;:513,&quot;3&quot;:{&quot;1&quot;:0},&quot;12&quot;:0}">10 Ways to Improve Your Infrastructure as Code</a></li>
<li><a href="https://spacelift.io/blog/ansible-best-practices" target="_blank" rel="noopener"><span data-sheets-value="{&quot;1&quot;:2,&quot;2&quot;:&quot;44 Ansible Best Practices to Follow [Tips &amp; Tricks]&quot;}" data-sheets-userformat="{&quot;2&quot;:513,&quot;3&quot;:{&quot;1&quot;:0},&quot;12&quot;:0}">44 Ansible Best Practices to Follow</a></li>
</ul>

A common tactic is to refactor an Ansible playbook into a role. To achieve that, we have to decompose the different parts of a playbook and stitch them together into an Ansible role using the directories we’ve just seen in the previous section. 
This section will go through an example of creating a new role for installing and configuring a minimal Nginx web server from scratch. If you wish to follow along, you will need <a href="https://www.virtualbox.org/" target="_blank" rel="nofollow noopener">VirtualBox</a>, <a href="https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html" target="_blank" rel="nofollow noopener">Ansible</a>, and <a href="https://www.vagrantup.com/" target="_blank" rel="nofollow noopener">Vagrant</a> installed locally.
Ansible searches for referenced roles in common paths like the orchestrating playbook’s directory, the roles/ directory, or the configured <a href="https://docs.ansible.com/ansible/latest/reference_appendices/config.html#default-roles-path" target="_blank" rel="nofollow noopener">roles_path</a> configuration value. It’s also possible to set a custom path when referencing a role:

Using the ansible-galaxy init command, we generate the initial directory structure for a role named webserver inside a parent directory named roles. Let’s go ahead and delete the tests directory since we won’t be using it. We will see how to utilize all the other directories during our demo. 
The final structure of our role looks like this:

image2-23

The final structure of our role

First, let’s define the most fundamental part of our role, its tasks. Head to the tasks directory and edit the main.yml file.
roles/webserver/tasks/main.yml

Here, we define a handful of tasks that update the operating system, install an Nginx web server, and set up a minimal custom configuration for demo purposes.
Next, we move to the defaults directory, where we will set default values for the variables used in the tasks. If there is no other definition for these variables, they will be picked up and used by the role, but usually, they are meant to be easily overwritten.
roles/webserver/defaults/main.yml

Moving on to our vars directory, we define values with higher precedence that aren’t meant to be overridden at the play level. Here, we override the default variable that defines the Nginx custom directory.
roles/webserver/vars/main.yml

In the handlers directory, we define any handler that is triggered by our tasks. One of our tasks includes a notify keyword since it needs to trigger our Restart the Nginx service handler.
roles/webserver/handlers/main.yml

In the templates directory, we leverage a Jinja2 template file for the Nginx configuration that gets the Nginx custom directory value from one of our previously defined variables.
roles/webserver/templates/nginx.conf.j2

In the files directory, we define a static file index.html that will serve as our static demo webpage.
roles/webserver/files/index.html

We use the meta directory to add metadata and information about the role. Any role dependencies by other roles go here as well.
roles/webservers/meta/main.yml

Lastly, we update the README.md file accordingly. The autogenerated file provided by the ansible-galaxy init command includes many pointers and guidance on filling this nicely. 
roles/webserver/README.md

Once we have defined all the necessary parts of our role, it’s time to use it in plays. The classic and most obvious way is to reference a role at the play level with the roles option:

With this option, each role defined in our playbook is executed before any other tasks defined in the play.
This is an example play to try out our new webserver role. Let’s go ahead and execute this play. To follow along, you should first run the <code>vagrant up</code> command from the top directory of <a href="https://github.com/spacelift-io-blog-posts/Blog-Technical-Content/tree/master/ansible-roles" target="_blank" rel="nofollow noopener">this repository</a> to create our target remote host.

image3-20

webserver role

Sweet! All the tasks have been completed successfully. Let’s also validate that we have configured our Ngnix web server correctly.
Use the command <code>vagrant ssh host1</code> to connect to our demo Vagrant host. Then execute <code>systemctl status nginx</code> to verify that Nginx service is up and running. Finally, run the command <code>curl localhost</code> to check if the web server responds with the custom page that we configured.

image1-24

vagrant ssh host1

When using the roles option at the play level, we can override any of the default role’s variables or pass other keywords, like tags. Tags are added to all tasks within the role.

Here, we override the default variable nginx_version with another version.
Apart from defining roles at the play level with the roles option, we can use them also at the tasks level with the options include_role dynamically and import_role statically. These are useful when we would like to run our role tasks in a specific order and not necessarily before any other playbook tasks. This way, roles run in the order they are defined in plays.

Check the <a href="https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html#using-roles" target="_blank" rel="nofollow noopener">official docs</a> for achieving more fine-grained control of your role’s task execution order. 
Even if we define a role multiple times, Ansible will execute it only once. Occasionally, we might want to run a role multiple times but with different parameters. Passing a different set of parameters to the same roles allows executing the role more than once. 
Example of executing the role test three times:

<a href="https://galaxy.ansible.com/" target="_blank" rel="nofollow noopener">Ansible Galaxy</a> is an online open-source, public repository of Ansible content. There, we can search, download and use any shared roles and leverage the power of its community. We have already used its client, ansible-galaxy, which comes bundled with Ansible and provides a framework for creating well-structured roles.
You can use Ansible Galaxy to browse for roles that fit your use case and save time by using them instead of writing everything from scratch. For each role, you can see its code repository, documentation, and even a rating from other users. Before running any role, check its code repository to ensure it’s safe and does what you expect. Here’s a blog post on <a href="https://www.jeffgeerling.com/blog/2019/how-evaluate-community-ansible-roles-your-playbooks" target="_blank" rel="noopener">How to evaluate community Ansible roles</a>. If you are curious about Galaxy, check out its <a href="https://galaxy.ansible.com/docs/" target="_blank" rel="nofollow noopener">official documentation</a> page for more details.
To download and install a role from Galaxy, use the ansible-galaxy install command. You can usually find the installation command necessary for the role on Galaxy. For example, look at <a href="https://galaxy.ansible.com/geerlingguy/postgresql" target="_blank" rel="nofollow noopener">this role that installs a PostgreSQL server</a>.
Install the role with:

Then use it in a playbook while overriding the default role variable postgresql_users to create an example user for us.

This section gathers some tips and tricks that might help you along your journey with Ansible roles.
<ul>
<li style="font-weight: 400;" aria-level="1">Always use descriptive names for your roles, tasks, and variables. Document the intent and the purpose of your roles thoroughly and point out any variables that the user has to set. Set sane defaults and simplify your roles as much as possible to allow users to get onboarded quickly.</li>
<li style="font-weight: 400;" aria-level="1">Never place secrets and sensitive data in your roles YAML files. Secret values should be passed to the role at execution time by the play as a variable and should never be stored in any code repository.</li>
<li style="font-weight: 400;" aria-level="1">At first, it might be tempting to define a role that handles many responsibilities. For instance, we could create a role that installs multiple components, a common anti-pattern. Try to follow the separation of concerns design principle as much as possible and separate your roles based on different functionalities or technical components.</li>
<li style="font-weight: 400;" aria-level="1">Try to keep your roles as loosely coupled as possible and avoid adding too many dependencies. </li>
<li style="font-weight: 400;" aria-level="1">To control the execution order of roles and tasks, use the import_role or Include_role tasks instead of the classic roles keyword.</li>
<li style="font-weight: 400;" aria-level="1">When it makes sense, group your tasks in separate task files for improved clarity and organization.</li>
</ul>
To learn more, check out the <a href="https://spacelift.io/blog/ansible-best-practices" target="_blank" rel="noopener">44 Ansible Best Practices to Follow</a>.

We deep-dived into Ansible Roles and their utility and saw how to refactor our playbooks into roles or generate them from scratch. We went through a complete example of creating and using a role and explored how we can benefit from the Ansible Galaxy community.
We encourage you to also explore how <a href="https://spacelift.io/?utm_source=blog&amp;utm_medium=text&amp;utm_id=blogpost&amp;utm_content=%7Bansible_roles%7D" target="_blank" rel="noopener">Spacelift</a>’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 then easily <a href="https://docs.spacelift.io/concepts/policy/trigger-policy" target="_blank" rel="noopener">create custom workflows</a> based on pull requests and apply any necessary <a href="https://docs.spacelift.io/concepts/policy/terraform-plan-policy" target="_blank" rel="noopener">compliance checks</a> for your organization. Get started on your journey by <a href="https://spacelift.io/free-trial?utm_source=blog&amp;utm_medium=text&amp;utm_id=blogpost&amp;utm_content=%7Bansible_roles%7D" target="_blank" rel="noopener">creating a free trial account</a>.
Thank you for reading, and I hope you enjoyed this “Ansible Roles” blog post as much as I did.

Spacelift allows you to automate, audit, secure, and continuously deliver your infrastructure.  It helps overcome common state management issues and adds several must-have features for infrastructure management.

Working with Ansible Playbooks - Tips & Tricks with Examples

Explore the concept of Ansible roles, their structure, and how we can refactor our playbooks into roles or generate them from scratch.

76-ansible-roles

Ansible Roles

This blog post deep dives into Ansible Variables, which allow us to parametrize different Ansible components. Variables store values for reuse inside an Ansible project. 
If you are still learning how to use Ansible, you might also find helpful the introductory <a href="https://spacelift.io/blog/ansible-tutorial" target="_blank" rel="noopener">Ansible Tutorial</a> or <a href="https://spacelift.io/blog/ansible-playbooks" target="_blank" rel="noopener">Working with Ansible Playbooks</a> blog posts. You can find this article&#8217;s code on this <a href="https://github.com/spacelift-io-blog-posts/Blog-Technical-Content/tree/master/ansible-variables" target="_blank" rel="nofollow noopener">repository</a> if you wish to follow along.

The use of variables simplifies the management of dynamic values throughout an Ansible project and can potentially reduce the number of human errors. We have a convenient way to handle variations and differences between different environments and systems with variables. 
Another advantage of variables in Ansible is that we have the flexibility to define them in multiple places with different precedence according to our use case. We can also register new variables in our playbooks by using the returned value of a task.
<a href="https://docs.ansible.com/ansible/latest/user_guide/playbooks_vars_facts.html#vars-and-facts" target="_blank" rel="nofollow noopener">Ansible facts</a> are a special type of variables that Ansible retrieves from any remote host for us to leverage them in Ansible projects. For example, we can get information regarding the operating system distribution with ansible_distribution, information about devices on the host, the python version that Ansible is using with ansible_python_version, and the system architecture, among others. To access this data, we have to reference the ansible_facts variable.

Ansible has a strict set of rules to create valid variable names. Variable names can contain only letters, numbers, and underscores and must start with a letter or underscore. Some strings are reserved for other purposes and aren’t valid variable names, such as <a href="https://docs.python.org/3/reference/lexical_analysis.html#keywords" target="_blank" rel="nofollow noopener">Python Keywords</a> or <a href="https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html#playbook-keywords" target="_blank" rel="nofollow noopener">Playbook Keywords</a>.

The simplest use case of variables is to define a variable name with a single value using standard <a href="https://spacelift.io/blog/yaml" target="_blank" rel="noopener">YAML syntax</a>. Although this pattern can be used in many places, we will show an example in a playbook for simplicity.

In the above example, after the vars block, we define the variable username, and assign the value bob. Later, to reference the value in the task, we use <a href="https://docs.ansible.com/ansible/latest/user_guide/playbooks_templating.html" target="_blank" rel="nofollow noopener">Jinja2 syntax</a> like this &#8220;{{ username }}&#8221; 
If a variable&#8217;s value starts with curly braces, <a href="https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#when-to-quote-variables-a-yaml-gotcha" target="_blank" rel="nofollow noopener">we must quote the whole expression</a> to allow YAML to interpret the syntax correctly.

There are many other options to define more complex variables like lists, dictionaries, and nested structures. To create a variable with multiple values, we can use YAML lists syntax:

To reference a specific value from the list we must select the correct field. For example, to access the third value v3:

Another useful option is to store key-value pairs in variables as dictionaries. For example:

Similarly, to reference the third field from the dictionary, use the bracket or dot notation:

Note that the bracket notation is preferred as you might encounter problems using the dot notation in special cases.
Sometimes, we have to create or use nested variable structures. For example, facts are nested data structures. We have to use a bracket or dot notation to reference nested variables.

There are certain types of variables that we consider special in the context of Ansible. These include magic variables, connection variables, and facts. The names of these variables are reserved. 
Ansible allows us to access information about itself, hosts, groups, <a href="https://spacelift.io/blog/ansible-inventory" target="_blank" rel="noopener">inventory</a>, roles, and other Ansible manifests with the so-called magic variables. For a complete list of different options, have a look <a href="https://docs.ansible.com/ansible/latest/reference_appendices/special_variables.html#magic-variables" target="_blank" rel="nofollow noopener">here</a>.
We already talked about facts. These variables contain all the information that Ansible can get from the current host. To use them, Ansible has to gather them first. To see all the facts that you can gather on a host, execute:

Lastly, we have connection variables. They are used to configure Ansible execution behavior and actions on hosts. The most common ones configure the user that Ansible logs in, set privilege escalation, set the IP of the target host, etc.

During our plays, we might find it handy to utilize the output of a task as a variable that we can use in the following tasks. We can use the keyword register to create our own custom variables from task output.

In the above example, we register the output of the command find /etc/hosts, and we showcase how we can use the variable in the next task by printing its value.

image3-12

Registering Variables

A powerful pattern is to combine registered variables with conditionals to create tasks that will only be executed when certain custom conditions are true.

Learn how to work with Ansible Variables, with special and registering variables. See where to set them and best practices.

How to Keep Your Playbooks Secure Using Ansible Vault

Get the newsletter

Recent posts

Working with Ansible Inventory – Basics and Use Cases

44 Ansible Best Practices to Follow [Tips & Tricks]

Ansible Modules – How To Use Them Efficiently (Examples)

Ansible Roles : Basics & How to Combine Them With Playbooks

How to Use Different Types of Ansible Variables (Examples)

Working with Ansible Playbooks – Tips & Tricks with Examples

Ansible Tutorial for Beginners: Ultimate Playbook & Examples

Terraform vs. Ansible : Key Differences and Comparison of Tools