ansible.builtin.ini lookup – read data from an ini file

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 ini even without specifying the collections: keyword. However, we recommend you use the FQCN for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same lookup plugin name.

New in version 2.0: of ansible.builtin

Synopsis

  • The ini lookup reads the contents of a file in INI format key1=value1. This plugin retrieves the value on the right side after the equal sign '=' of a given section [section].

  • You can also read a property file which - in this case - does not contain section.

Parameters

Parameter

Comments

_terms

string / required

The key(s) to look up.

allow_no_value

aliases: allow_none

boolean

added in 2.12 of ansible.builtin

Read an ini file which contains key without value and without ‘=’ symbol.

Choices:

  • no ← (default)

  • yes

case_sensitive

string

added in 2.12 of ansible.builtin

Whether key names read from file should be case sensitive. This prevents duplicate key errors if keys only differ in case.

Default: “no”

default

string

Return value if the key is not in the ini file.

Default: “”

encoding

string

Text encoding to use.

Default: “utf-8”

file

string

Name of the file to load.

Default: “ansible.ini”

re

boolean

Flag to indicate if the key supplied is a regexp.

Choices:

  • no ← (default)

  • yes

section

string

Section where to lookup the key.

Default: “global”

type

string

Type of the file. ‘properties’ refers to the Java properties files.

Choices:

  • ini ← (default)

  • properties

Examples

- ansible.builtin.debug: msg="User in integration is {{ lookup('ansible.builtin.ini', 'user', section='integration', file='users.ini') }}"

- ansible.builtin.debug: msg="User in production  is {{ lookup('ansible.builtin.ini', 'user', section='production',  file='users.ini') }}"

- ansible.builtin.debug: msg="user.name is {{ lookup('ansible.builtin.ini', 'user.name', type='properties', file='user.properties') }}"

- ansible.builtin.debug:
    msg: "{{ item }}"
  loop: "{{ q('ansible.builtin.ini', '.*', section='section1', file='test.ini', re=True) }}"

- name: Read an ini file with allow_no_value
  ansible.builtin.debug:
    msg: "{{ lookup('ansible.builtin.ini', 'user', file='mysql.ini', section='mysqld', allow_no_value=True) }}"

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key

Description

_raw

list / elements=string

value(s) of the key(s) in the ini file

Returned: success

Authors

  • Yannig Perre <yannig.perre(at)gmail.com>

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.