helper_ini

An Ansible role for managing INI-style configuration files using the community.general.ini_file module.

---

Description

This role provides a flexible and structured way to manage INI configuration files.

It supports:

• multiple files,

• multiple sections per file,

• multiple options per section,

• file-level attributes (permissions, ownership, SELinux context),

• fine-grained control over entries (state, exclusive),

• hierarchical task processing without flattening the input structure,

• hierarchical inheritance:

  • option-level overrides section-level,
  • section-level overrides module defaults.

The role is designed to be reusable across different applications and services that rely on INI configuration files.

---

Opis (PL)

Rola umożliwia zarządzanie plikami konfiguracyjnymi w formacie INI przy użyciu modułu community.general.ini_file.

Obsługuje:

• wiele plików,

• wiele sekcji i opcji,

• parametry na poziomie pliku (uprawnienia, właściciel, SELinux),

• kontrolę wpisów (state, exclusive),

• przetwarzanie hierarchiczne bez spłaszczania struktury wejściowej,

• dziedziczenie parametrów:

  • wpis nadpisuje sekcję,
  • sekcja nadpisuje domyślne zachowanie modułu.

Rola jest uniwersalna i nadaje się do konfiguracji różnych aplikacji korzystających z formatu INI.

---

Requirements

• Ansible >= 2.14

• Collection:

  • community.general

Install required collection:

ansible-galaxy collection install community.general

---

Role Variables

Main variable

ini_config:
  - file: <path>
    owner: <string>        # optional
    group: <string>        # optional
    mode: <string>         # optional (e.g. "0644")
    create: <bool>         # optional
    backup: <bool>         # optional
    setype: <string>       # optional (SELinux context)

    sections:
      - section: <name>
        state: present|absent      # optional
        exclusive: <bool>          # optional

        options:
          - option: <key>
            value: <value>         # optional if state=absent
            state: present|absent  # optional
            exclusive: <bool>      # optional

---

Parameter Behavior

The input structure is processed in three nested task levels:

ini_config[] -> sections[] -> options[]

The role does not build an intermediate flat list of INI entries. File-level and section-level values stay available through scoped loop variables while each option is passed to community.general.ini_file.

File-level

Applies to all entries in the file:

• owner
• group
• mode
• create
• backup
• setype

Section / Option-level

• state
• exclusive

Inheritance order

option > section > module defaults

---

Dependencies

None (except required collection).

---

Example Playbook

- hosts: all
  gather_facts: false
  collections:
    - community.general

  roles:
    - role: helper_ini
      vars:
        ini_config:
          - file: /etc/example/app.ini
            owner: root
            mode: "0644"
            sections:
              - section: general
                options:
                  - option: enabled
                    value: true
                  - option: timeout
                    value: 30

---

Examples

Multiple files

ini_config:
  - file: /etc/app1/config.ini
    sections:
      - section: main
        options:
          - option: log_level
            value: INFO

  - file: /etc/app2/config.ini
    sections:
      - section: security
        options:
          - option: enable_tls
            value: true

---

Section-level defaults

ini_config:
  - file: /etc/example/service.ini
    sections:
      - section: service
        state: present
        exclusive: true
        options:
          - option: workers
            value: 4
          - option: retries
            value: 3

---

Override per option

ini_config:
  - file: /etc/example/service.ini
    sections:
      - section: service
        exclusive: true
        options:
          - option: workers
            value: 4
          - option: debug
            value: true
            exclusive: false

---

Remove option

ini_config:
  - file: /etc/example/app.ini
    sections:
      - section: deprecated
        options:
          - option: old_setting
            state: absent

---

Best Practices

1. Use file-level attributes consistently

Define owner, group, and mode at file level to ensure consistent permissions across all entries.

2. Prefer section-level defaults

If multiple options share the same behavior (e.g. state, exclusive), define it at section level instead of repeating it per option.

3. Use option-level overrides sparingly

Override state or exclusive only when necessary to avoid configuration complexity.

4. Be careful with exclusive=true

• Ensures only the specified value exists for an option.
• May remove additional entries unintentionally.
• Recommended only when strict control is required.

5. Use state=absent without value for full removal

If the goal is to remove an option entirely, omit value.

6. Ensure parent directories exist

The role does not create directories automatically.

7. Validate inputs early

Use role validation (argument_specs) to prevent runtime errors.

8. Keep configuration declarative

Avoid mixing conflicting definitions across sections and options.

---

Notes

• Parameters not defined are omitted and default module behavior is used.
• The role keeps the public ini_config structure hierarchical; no separate flattened variable is required.
• value is optional when state=absent.
• Requires community.general collection (not part of ansible-core).

---

License

MIT

---

Author Information

Author: grenn krzysiek@devnull.com.pl

Repository: https://code.devnull.com.pl/ansible-pub/helper_ini.git