ansible.builtin.config lookup – Lookup current Ansible configuration values

Note

This lookup plugin is part of ansible-core and included in all Ansible installations. In most cases, you can use the short plugin name config. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.config for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same lookup plugin name.

Synopsis

  • Retrieves the value of an Ansible configuration setting.

  • You can use ansible-config list to see all available settings.

Terms

Parameter

Comments

Terms

string / required

The key(s) to look up

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('ansible.builtin.config', key1=value1, key2=value2, ...) and query('ansible.builtin.config', key1=value1, key2=value2, ...)

Parameter

Comments

on_missing

string

action to take if term is missing from config

Error will raise a fatal error

Skip will just ignore the term

Warn will skip over it but issue a warning

Choices:

  • "error" ← (default)

  • "skip"

  • "warn"

plugin_name

string

added in ansible-core 2.12

name of the plugin for which you want to retrieve configuration settings.

plugin_type

string

added in ansible-core 2.12

the type of the plugin referenced by ‘plugin_name’ option.

Choices:

  • "become"

  • "cache"

  • "callback"

  • "cliconf"

  • "connection"

  • "httpapi"

  • "inventory"

  • "lookup"

  • "netconf"

  • "shell"

  • "vars"

show_origin

boolean

added in ansible-core 2.16

toggle the display of what configuration subsystem the value came from

Choices:

  • false

  • true

Notes

Note

  • When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: lookup('ansible.builtin.config', term1, term2, key1=value1, key2=value2) and query('ansible.builtin.config', term1, term2, key1=value1, key2=value2)

Examples

- name: Show configured default become user
  ansible.builtin.debug: msg="{{ lookup('ansible.builtin.config', 'DEFAULT_BECOME_USER')}}"

- name: print out role paths
  ansible.builtin.debug:
    msg: "These are the configured role paths: {{lookup('ansible.builtin.config', 'DEFAULT_ROLES_PATH')}}"

- name: find retry files, skip if missing that key
  ansible.builtin.find:
    paths: "{{lookup('ansible.builtin.config', 'RETRY_FILES_SAVE_PATH')|default(playbook_dir, True)}}"
    patterns: "*.retry"

- name: see the colors
  ansible.builtin.debug: msg="{{item}}"
  loop: "{{lookup('ansible.builtin.config', 'COLOR_OK', 'COLOR_CHANGED', 'COLOR_SKIP', wantlist=True)}}"

- name: skip if bad value in var
  ansible.builtin.debug: msg="{{ lookup('ansible.builtin.config', config_in_var, on_missing='skip')}}"
  var:
    config_in_var: UNKNOWN

- name: show remote user and port for ssh connection
  ansible.builtin.debug: msg={{q("ansible.builtin.config", "remote_user", "port", plugin_type="connection", plugin_name="ssh", on_missing='skip')}}

- name: show remote_tmp setting for shell (sh) plugin
  ansible.builtin.debug: msg={{q("ansible.builtin.config", "remote_tmp", plugin_type="shell", plugin_name="sh")}}

Return Value

Key

Description

Return value

any

A list of value(s) of the key(s) in the config if show_origin is false (default)

Optionally, a list of 2 element lists (value, origin) if show_origin is true

Returned: success

Authors

  • Ansible Core Team

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.