Ansible Lesson 6 – Ansible Configuration Files | Dataplexa

Ansible Course

I. Ansible Fundamentals
1. What is Ansible 2. Why Configuration Management Matters 3. Ansible Architecture 4. Control Node and Managed Nodes 5. Installation and Setup 6. Ansible Configuration Files 7. Inventory Files Explained 8. Ansible Ad-hoc Commands 9. Ansible Modules Overview 10. Beginner Best Practices
II. Playbooks & Core Concepts
11. YAML Basics for Ansible 12. Playbooks Introduction 13. Writing Your First Playbook 14. Tasks, Handlers and Variables 15. Facts and Gathering Facts 16. Conditionals and Loops 17. Templates with Jinja2 18. File and Package Management 19. Service Management 20. User and Permission Management 21. Error Handling 22. Tags and Selective Execution 23. Roles Introduction 24. Creating and Using Roles 25. Playbook Best Practices
III. Security, Roles & Automation
26. Ansible Galaxy 27. Role Directory Structure 28. Ansible Vault 29. Managing Secrets Securely 30. Application Deployment 31. Server Hardening 32. Ansible with Docker 33. Ansible with Kubernetes 34. Troubleshooting 35. Performance Optimization
IV. Advanced Ansible & Real-World
36. Ansible at Scale 37. Ansible in CI/CD Pipelines 38. Ansible with Jenkins 39. Ansible Anti-Patterns 40. Mini Project
Section I · Lesson 6

Ansible Configuration Files

In this lesson

ansible.cfg explained Configuration precedence Essential settings Sections & directives Environment variables

ansible.cfg is Ansible's configuration file — an INI-formatted text file that controls how Ansible behaves on every run without requiring command-line flags. It sets defaults for the inventory location, SSH connection settings, privilege escalation, output verbosity, and dozens of other behaviours. Understanding ansible.cfg matters because it is the difference between typing a long, flag-heavy command every time and running a clean, repeatable ansible-playbook site.yml with all the right defaults already baked in.

Configuration Precedence

Ansible does not have a single configuration file — it checks several locations in a defined order and uses the first one it finds. Understanding this precedence chain is critical: a setting in the wrong file may be silently overridden by one higher in the chain, causing hard-to-diagnose behaviour. The order from highest to lowest priority is:

Priority 1 — Highest

Environment variables

Any ANSIBLE_* environment variable set in your shell overrides everything else. For example, ANSIBLE_HOST_KEY_CHECKING=False disables host key checking for the duration of that shell session, regardless of what any config file says.

Priority 2

./ansible.cfg — project directory

An ansible.cfg in the current working directory where you run the ansible-playbook command. This is the recommended location for most projects — it lives alongside your playbooks in the Git repository and applies automatically whenever you work in that project.

Priority 3

~/.ansible.cfg — user home directory

A hidden config file in the current user's home directory. Useful for personal defaults that apply across all your projects — for example, your preferred output format or a shared SSH private key path.

Priority 4 — Lowest

/etc/ansible/ansible.cfg — system-wide

The global fallback created during installation. This applies to all users on the system unless overridden by a higher-priority file. Useful for shared control nodes in a team environment, but rarely the right place for project-specific settings.

You can always confirm which config file Ansible is actually using by running:

# Shows the active config file path alongside the version info
ansible --version
ansible [core 2.17.0]
  config file = /home/user/myproject/ansible.cfg   <-- active config file
  ...

What just happened?

The config file = line tells you exactly which ansible.cfg Ansible loaded. If it shows config file = None, no config file was found and Ansible is using compiled-in defaults for every setting. This is normal if you have not yet created a project-level config file.

Anatomy of ansible.cfg

The file is structured as INI — named sections in square brackets, each containing directives as key = value pairs. Here is a well-commented project-level ansible.cfg covering the settings you will use most often:

[defaults]
# Path to the inventory file — avoids typing -i on every command
inventory      = ./inventory.ini

# User to connect as on managed nodes
remote_user    = ansible

# SSH private key for authentication
private_key_file = ~/.ssh/id_ed25519

# Number of hosts to manage in parallel (increase for large fleets)
forks          = 10

# Suppress the SSH host key check prompt (convenient for lab environments)
# WARNING: set to True only in trusted, controlled networks — never in production
host_key_checking = False

# Suppress deprecation warnings in output (useful once you know what they mean)
deprecation_warnings = False

# Format of Ansible's output — 'yaml' is more readable than the default
stdout_callback = yaml


[privilege_escalation]
# Enable sudo escalation for all plays by default
become       = True
become_method = sudo
become_user  = root
# Set to True if your sudo requires a password (avoid if possible in automation)
become_ask_pass = False


[ssh_connection]
# Speed up SSH connections by reusing the same TCP connection for multiple tasks
pipelining   = True

# Path to the SSH executable (override if using a non-standard SSH binary)
# ssh_executable = /usr/bin/ssh

Full reference: Ansible has over 100 configurable settings across all sections. The official documentation lists every directive with its default value, environment variable equivalent, and description.

Config reference ↗

The Preferences File Analogy

ansible.cfg is like the preferences file in any desktop application — it stores your personal defaults so you do not have to set them every time you open the app. The difference is that Ansible's preferences are layered: your project-level config overrides your user-level config, which overrides the system default — exactly the same way environment variables in your shell override everything else.

Essential Directives Reference

The table below covers the directives you will encounter most frequently across this course. Each one has an equivalent environment variable — useful for overriding a setting in a CI/CD pipeline without modifying any file.

Directive — Section — Default — What it controls

inventory [defaults] Path to the default inventory file. Eliminates the need to pass -i on every command. Env: ANSIBLE_INVENTORY
remote_user [defaults] Default SSH user for all connections. Can be overridden per host or group in the inventory. Env: ANSIBLE_REMOTE_USER
forks [defaults] Number of managed nodes to connect to in parallel. Default is 5. Increase for large fleets. Env: ANSIBLE_FORKS
host_key_checking [defaults] Whether to verify the SSH host key on first connection. Set to False in lab environments only. Default: True. Env: ANSIBLE_HOST_KEY_CHECKING
become [privilege_escalation] Enable privilege escalation by default for all plays. Equivalent to adding become: true to every play. Env: ANSIBLE_BECOME
pipelining [ssh_connection] Reduces SSH operations by piping multiple commands through a single connection. Significantly speeds up playbook execution. Default: False. Env: ANSIBLE_PIPELINING
stdout_callback [defaults] Controls the output format of playbook runs. Options include yaml, json, and minimal. The default is default. Env: ANSIBLE_STDOUT_CALLBACK

Environment Variables vs Config File

Every ansible.cfg directive has a corresponding environment variable equivalent. Knowing when to use each approach makes your automation more flexible — especially in CI/CD pipelines where you cannot commit a config file.

ansible.cfg file
Committed to Git alongside your playbooks
Applies automatically every time you work in that project directory
Reviewed and visible to the whole team
Best for stable, project-wide defaults
Environment variables
Set in the shell or injected by a CI/CD pipeline at runtime
Override any config file without modifying any file on disk
Useful for secrets, temporary overrides, or environment-specific values
Best for per-run or per-environment overrides

Practical example — disabling host key checking in a CI pipeline:

# Set in a GitHub Actions workflow or Jenkins pipeline step
# Overrides any ansible.cfg setting for this run only
export ANSIBLE_HOST_KEY_CHECKING=False
export ANSIBLE_FORKS=20
export ANSIBLE_STDOUT_CALLBACK=yaml

ansible-playbook -i inventory.ini site.yml

Generating a Full Config Reference

Ansible ships with a built-in command that generates a fully commented ansible.cfg listing every available setting with its default value and description. This is the fastest way to discover settings you did not know existed.

# Generate a full ansible.cfg with every setting commented out and documented
# Pipe to a file to save it as your starting point
ansible-config init --disabled -t all > ansible.cfg
# (truncated — the full output is several hundred lines)
[defaults]
# Path to the ansible.cfg config file
;config_file=/etc/ansible/ansible.cfg

# Number of parallel processes to use
;forks=5

# SSH port to use for connections
;remote_port=22

# SSH user to connect as
;remote_user=root
...

What just happened?

Ansible wrote a complete, fully commented config file to disk — every available setting, with its default value, prefixed with ; so none of them are active. Uncomment and set only the values you want to change. This is a much better starting point than writing a config file from scratch.

Never Commit ansible.cfg With host_key_checking = False to a Production Repository

Disabling SSH host key checking prevents Ansible from verifying that it is connecting to the intended server. In a production environment this opens the door to man-in-the-middle attacks. Disable it only in local lab environments where you control every server, and use environment variables to set it at runtime in CI/CD rather than committing it to your ansible.cfg.

Key Takeaways

✓
Ansible checks four config file locations in order — environment variables beat everything, then the project-level ./ansible.cfg, then user-level ~/.ansible.cfg, then the system-wide /etc/ansible/ansible.cfg.
✓
The project directory is the right place for ansible.cfg — committing it alongside your playbooks means any engineer who clones the repo gets the correct defaults automatically.
✓
Every directive has an environment variable equivalent — use ANSIBLE_* variables in CI/CD pipelines or for temporary per-run overrides without touching any file on disk.
✓
Enable pipelining for faster playbook runs — setting pipelining = True in the [ssh_connection] section reduces the number of SSH operations per task and noticeably speeds up large playbooks.
✓
ansible-config init --disabled -t all generates a full reference — use it to discover every available setting and create a well-documented starting config for any new project.

Teacher's Note

Create a minimal ansible.cfg in your project directory right now with at least inventory, remote_user, and pipelining = True — you will feel the difference in every lesson from here on.

Practice Questions

1. Which ansible.cfg location takes priority over the user home directory config but is lower priority than environment variables?



2. Which [ssh_connection] directive, when set to True, speeds up playbook execution by reusing a single SSH connection for multiple tasks?



3. What command generates a fully commented ansible.cfg listing every available setting with its default value?



Quiz

1. A setting appears in both ~/.ansible.cfg and ./ansible.cfg. Which value does Ansible use?


2. Your CI/CD pipeline needs to run Ansible with host_key_checking = False but you do not want to commit this to the repository. What is the correct approach?


3. What does the forks directive in [defaults] control?


Up Next · Lesson 7

Inventory Files Explained

Master Ansible's inventory — static and dynamic formats, host variables, group variables, and how to organise a real-world fleet of servers.

← Previous Course Index Next →