Proving a setting's value and its source

Reading ansible.cfg tells you what somebody wrote. It does not tell you what is in effect, for three reasons: the file may not be the one being loaded, an environment variable may override any line in it, and a misspelled key is accepted by the file and ignored by Ansible.

ansible-config answers the question the file cannot. It has five subcommands and you will use two of them constantly.

The five subcommands

dump --only-changed is the one you will type most. validate is the one that belongs in CI and usually is not there.

dump --only-changed: the operational view

On ansible-core 2.21.3, plain ansible-config dump prints 220 lines for the base configuration and 607 with -t all to include plugin settings. That is a reference, not a report — nobody reviews it.

--only-changed reduces it to what this estate actually altered:

$ ansible-config dump --only-changed

CONFIG_FILE() = /srv/estate/ansible.cfg
DEFAULT_FORKS(env: ANSIBLE_FORKS) = 12
DEFAULT_HOST_LIST(/srv/estate/ansible.cfg) = ['/srv/estate/inventory']

GALAXY_SERVERS:

Read the parentheses. They are the whole value of the command:

• CONFIG_FILE() — the file in effect, matching ansible --version.
• (/srv/estate/ansible.cfg) — this value came from that file.
• (env: ANSIBLE_FORKS) — this value came from the environment, and overrode whatever the file said.
• (default) — appears in the full dump for anything untouched.

That third annotation is why reading the file is not enough. In the capture above the file sets forks = 30; the effective value is 12, because an environment variable was set. Nothing in ansible.cfg records that, and nobody reviewing the repository would see it.

validate: the check nobody has in CI

Misspell a configuration key and nothing objects. The file parses, the run proceeds, and the setting is at its default.

[defaults]
forkz = 30
host_key_checking = False

$ ansible -i inventory all --list-hosts

  hosts (1):
  h1.example.com

$ ansible-config dump | grep '^DEFAULT_FORKS'

DEFAULT_FORKS(default) = 5

validate is the only tool that names the problem, and it exits non-zero:

$ ansible-config validate

[ERROR]: Found unknown key 'forkz' in section 'defaults' in '/srv/estate/ansible.cfg.

It also validates the environment, which is the source no file records:

$ ansible-config validate --format env

[ERROR]: Found unknown environment variable 'ANSIBLE_FORKZ'.

Both were confirmed on 2.21.3, along with the clean case: All configurations seem valid!, exit status 0.

list and init: the reference views

ansible-config list prints every setting Ansible knows about as YAML — 219 base settings on 2.21.3 — with the default, the description, the ini section and key, and the environment variable name. It is what you consult when you know the behaviour you want and not the setting that controls it:

ansible-config list | grep -iE 'interpreter|host_key|forks|timeout' | head

ansible-config init --disabled generates a template of every setting, commented out, with its documentation inline — 705 lines on 2.21.3:

[defaults]
# (boolean) By default, Ansible will issue a warning when received from a task action (module or action plugin).
# These warnings can be silenced by adjusting this setting to False.
;action_warnings=True

A four-command diagnostic

When Ansible is behaving differently from how you expect, in this order:

1.  ansible --version
        Which config file, which core version, which Python?
2.  ansible-config dump --only-changed -t all
        What differs from the defaults, and what is its source?
        Use -t all: without it you see base settings only, and a
        connection-plugin override such as ssh_args does not appear.
3.  ansible-config view
        What does the loaded file actually say?
4.  ansible-config validate && ansible-config validate --format env
        Is anything in it, or in the environment, misspelled?

Step 2 before step 3 is deliberate. view shows you the file, and the file may not be the whole story — dump accounts for the environment as well and tells you which source won.

Knowledge check