Learn ansible.cfg Best Practices: Avoid Common Mistakes

Ansible Tutorial

Introduction to Ansible Configuration File

Ansible is a powerful automation tool used for configuration management, application deployment, and task automation. The Ansible configuration file plays a pivotal role in the operation of Ansible, acting as the cornerstone where various settings and parameters governing its behavior are defined.

Welcome to this comprehensive tutorial on the Ansible configuration file (ansible.cfg) — an essential element in mastering Ansible’s powerful automation capabilities. In this tutorial, we will embark on a detailed exploration, starting with the purpose and significance of the Ansible configuration file and diving into its anatomy and various configuration settings. We’ll uncover how to customize and optimize the configuration file for improved performance and security. You’ll gain insights into managing inventory, roles, error handling, and logging within the configuration file. Additionally, essential best practices and troubleshooting tips will be highlighted to ensure smooth and effective management of your Ansible projects. Advanced topics, real-world scenarios, and a repository of useful tools and resources will also be shared to enhance your learning experience and practical application of knowledge acquired. Let's dive in, and unlock the full potential of Ansible through a deeper understanding of its configuration file.


Different ansible.cfg File Locations and Their Significance

Ansible uses configuration settings to govern its operation, which are stored in the ansible.cfg file. Ansible looks for this configuration file in various locations in a specific order, and the first file found is used. Different locations of the ansible.cfg file and their significance are as follows:


1. Current Directory (./ansible.cfg):

  • Significance: This configuration file is the first one that Ansible tries to load. Having an ansible.cfg in the current directory allows for project-specific configurations.
  • Use Case: Ideal for managing configurations at a project level, ensuring that the settings are localized and not affecting other projects.


2. Home Directory (~/.ansible.cfg):

  • Significance: If the configuration file is not found in the current directory, Ansible will look for it in the home directory of the user running the command. This allows for user-specific configurations.
  • Use Case: Useful when different users on the same system need different Ansible configurations. It provides user-level customization without affecting global settings.


3. Environment Variable ($ANSIBLE_CONFIG):

  • Significance: Users can specify a custom path to an ansible.cfg file by setting the ANSIBLE_CONFIG environment variable. This gives users precise control over the configuration file used by Ansible commands.
  • Use Case: Essential for scenarios where configurations need to be dynamically switched or when using multiple configuration files for different environments or workflows.


4. System-wide Configuration (/etc/ansible/ansible.cfg):

  • Significance: This is the system-wide configuration file used when no other files are found. It acts as a fallback and contains the default settings used by all Ansible commands system-wide.
  • Use Case: Suitable for defining global configurations that apply system-wide, ensuring consistency across all projects and users on the system.


Ansible Configuration File Precedence Order

Ansible uses a specific precedence order to determine which configuration file (ansible.cfg) to use for its operations. Here is the order in which Ansible searches for the configuration file:

  1. Current Directory: Ansible first looks for the configuration file in the current directory where the command is executed (./ansible.cfg).
  2. Home Directory: If not found in the current directory, Ansible then searches for the configuration file in the home directory of the user executing the command (~/.ansible.cfg).
  3. Environment Variable: Ansible will use the configuration file specified by the ANSIBLE_CONFIG environment variable if it is defined.
  4. System-wide Configuration: Lastly, if none of the above are found, Ansible will fall back to the system-wide configuration file located at /etc/ansible/ansible.cfg.


Anatomy of the Configuration File

The ansible.cfg file is structured in INI format, consisting of various sections, each containing different parameters that influence Ansible's behavior. Let’s dissect the key sections and parameters:

[defaults] Section

  • General configurations: Hosts file location, roles path, and fork number.
  • Library and module configurations: Directories for libraries and modules.
  • Output configurations: Controls the verbosity of the output.

[privilege_escalation] Section

  • Become configurations: Settings related to privilege escalation like become_method, become_user, and passwords.

[paramiko_connection] Section

  • Paramiko settings: Configurations for when the Paramiko connection plugin is used (SSH).

[ssh_connection] Section

  • SSH-specific settings: Control over SSH configurations like pipelining, transfer method, and more.

[persistent_connection] Section

  • Timeouts and retries: For persistent connections, settings control connection retries and timeouts.


Configuration Settings

1. Inventory

2. Privilege Escalation

  • Become Method: Specified under the [privilege_escalation] section. It could be sudo, su, pbrun, etc.
  • Become User: Specifies which user you become after connecting.

3. SSH Connection Parameters

  • Remote Port: Defined under the [ssh_connection], specifying the port for SSH connections.
  • SSH Arguments: Additional SSH arguments can be provided.

4. Timeout Settings

  • Connection Timeout: Time before connection attempts are dropped.
  • Persistent Connection Timeout: Under [persistent_connection], defines how long the connection should persist.

5. Remote User

  • Specifying Remote User: Under [defaults], remote_user parameter to define the default user to connect as.


Inventory in Ansible Configuration

Inventory is a cornerstone in Ansible configurations, determining which hosts are managed and how they are categorized. You can use either a Static or Dynamic inventory, and customization is facilitated through specifying different inventory files. Let’s discuss these aspects with examples.


Static vs Dynamic Inventory

Static Inventory: Involves explicitly listing and organizing hosts in an inventory file.

web_server_1 ansible_host=

db_server_1 ansible_host=

Dynamic Inventory: Utilizes scripts or plugins to dynamically generate an inventory from sources like cloud providers.

  "web_servers": {
    "hosts": ["web_server_1"],
    "vars": {
      "ansible_host": ""
  "db_servers": {
    "hosts": ["db_server_1"],
    "vars": {
      "ansible_host": ""


Specifying a Custom Inventory File

You can specify a different inventory file in the ansible.cfg or directly in command-line executions.

In the ansible.cfg:

inventory = /path_to_your_directory/custom_inventory

Command Line Example:

ansible-playbook -i /path_to_your_directory/custom_inventory your_playbook.yml


Roles and Inclusion in Configuration File

Roles are reusable parts of Ansible playbooks, facilitating the organization and sharing of automation content. The configuration file plays a pivotal role in managing these roles effectively, specifying paths and handling access and permissions.

1. Specifying Custom Roles Path

You can define custom paths to your roles within the configuration file, allowing Ansible to locate and utilize the roles as needed.

Example in ansible.cfg:

roles_path = /path_to_your_directory/custom_roles

This tells Ansible to look for roles in the specified directory.

2. Role-Based Access and Permissions

Managing permissions effectively can help in safeguarding sensitive information within roles and ensuring that they are accessed by authorized entities.

Example: Setting File PermissionsYou can ensure that role files are not overly permissive by setting appropriate file permissions.

chmod 0755 /path_to_your_directory/custom_roles/your_role

This command ensures that the role files have appropriate read and execute permissions.

3. Role Inclusions in Playbooks

Roles can be included within playbooks, enabling the reuse of common configurations and tasks.

Example: Including a Role in a Playbook

- hosts: your_host_group
    - role: /path_to_your_directory/custom_roles/your_role

This includes a specified role within a playbook, allowing the playbook to utilize the tasks and handlers defined in the role.


Logging and Output

1. Configuring Logging Paths

Defining where Ansible should log its activities can be configured in the ansible.cfg, thus centralizing the logging information.

Example: Setting up Logging in ansible.cfg

log_path = /path_to_your_directory/ansible.log

This will direct Ansible to store logs in the specified file.

2. Managing Output Formats

Ansible provides various output formats that can be customized to make the output more readable or suited for further processing.

Example: Customizing Output in ansible.cfg

stdout_callback = yaml

Setting the stdout_callback to yaml makes the output display in YAML format, which is more readable.


Frequently Asked Questions

What is ansible.cfg, and why is it important?

The ansible.cfg file is a configuration file used by Ansible to manage the settings and preferences used during execution of playbooks and roles. It centralizes configuration settings, making Ansible workflows more manageable and consistent. Its significance lies in allowing users to customize various aspects of Ansible’s behavior, such as the default inventory, privilege escalation, and output formats.

Where is the default location of ansible.cfg?

By default, Ansible searches for the ansible.cfg file in several locations in a specified order:
Ansible looks for the configuration file in the current directory where the command is being run.
Next, it checks for a .ansible.cfg file in the home directory of the user executing the command.
Lastly, it looks for the global configuration file located at /etc/ansible/ansible.cfg.

How can I customize the ansible.cfg file?

You can customize ansible.cfg by editing different parameters within the file. For instance, you can modify the inventory parameter under the [defaults] section to point to your inventory file. Various other settings such as the number of parallel tasks, privilege escalation, and connection types can also be customized in this file.

What is the role of inventory in ansible.cfg?

The inventory in ansible.cfg specifies the hosts you are managing with Ansible. By customizing the inventory path in the configuration file, you direct Ansible to use a specific inventory, either static or dynamic, when executing playbooks or roles, unless another inventory is explicitly specified.

How does ansible.cfg handle error and retry configurations?

Within ansible.cfg, you can configure how Ansible should handle errors and retries. By customizing parameters like retries and managing the output of error messages, you have better control and visibility over playbook execution, improving error diagnostics and troubleshooting.

Can ansible.cfg improve the security of Ansible operations?

Yes, ansible.cfg allows the configuration of various security parameters, such as managing passwords and secrets, ensuring secure connections, and protecting sensitive data. Customizing these settings enhances the security posture of your Ansible operations.

How do plugins relate to ansible.cfg?

Plugins enhance Ansible's functionality, and ansible.cfg can be used to configure and manage them. In the configuration file, you can specify the location and type of plugins, enabling various integrations and extended functionalities.

Can I optimize performance using ansible.cfg?

Absolutely! ansible.cfg allows you to tweak several performance-related settings, such as the number of forked processes, polling intervals, and timeout settings, enabling you to optimize the execution of your playbooks and tasks.

What happens if there is no ansible.cfg file found?

If Ansible doesn’t find an ansible.cfg file, it uses default settings predefined within the Ansible codebase. Ansible operates with built-in defaults that facilitate its basic functionality, ensuring it works even without a specific configuration file.



In this comprehensive guide, we delved deep into the essentials of the Ansible configuration file, offering insights into its structure, customization, and advanced usage techniques. Key takeaways include the significance of the ansible.cfg file, where various operational parameters of Ansible are defined and customized. We explored the anatomy of this file, understanding various sections like [defaults] and [privilege_escalation].

Techniques for customizing Ansible configurations, such as defining role paths and managing error messages, were also elucidated, empowering users to tailor Ansible’s behavior to specific needs. Inventory management, a pivotal concept, was demystified, highlighting the distinctions and applications of static and dynamic inventories. Additionally, practical insights into logging, output management, error handling, and advanced topics like plugin configurations were furnished, enabling enhanced visibility, robustness, and flexibility in Ansible automation workflows. The tutorial concludes by pointing readers towards valuable tools and resources for continued learning and mastery of Ansible configurations.

You can further read more about Ansible Configuration file at:


Views: 890
Deepak Prasad

Deepak Prasad

He is the founder of GoLinuxCloud and brings over a decade of expertise in Linux, Python, Go, Laravel, DevOps, Kubernetes, Git, Shell scripting, OpenShift, AWS, Networking, and Security. With extensive experience, he excels in various domains, from development to DevOps, Networking, and Security, ensuring robust and efficient solutions for diverse projects. You can connect with him on his LinkedIn profile.

Can't find what you're searching for? Let us assist you.

Enter your query below, and we'll provide instant results tailored to your needs.

If my articles on GoLinuxCloud has helped you, kindly consider buying me a coffee as a token of appreciation.

Buy GoLinuxCloud a Coffee

For any other feedbacks or questions you can send mail to admin@golinuxcloud.com

Thank You for your support!!

Leave a Comment