Usage as a role dependency

The debops.etc_aliases role can be used as a dependency by other Ansible roles to manage contents of the /etc/aliases file idempotently. Configuration options from multiple roles can be merged together and included in the alias database, or removed conditionally.

Dependent role variable

The role exposes the etc_aliases__dependent_recipients variable which can be used to define mail aliases and recipients by other Ansible roles through the role dependent variables.

The variable is a YAML list with YAML dictionaries as entries. A short format of the configuration uses the dictionary key as a name of the dependent role and dictionary value as that role's configuration, in the format defined by etc_aliases__recipients variable (see playbook excerpt below):

roles:

  - role: debops.etc_aliases
    etc_aliases__dependent_recipients:
      - role_name: '{{ role_name__etc_aliases__dependent_recipients }}'

The extended version of the configuration uses a YAML dictionary with specific parameters:

role

Required. Name of the role, used to save its configuration in a YAML dictionary on the Ansible Controller. Shouldn't be changed once selected, otherwise the configuration will be desynchronized.

config

Required. YAML list with configuration of the aliases and recipients in the same format defined by etc_aliases__recipients variable.

state

Optional. If not specified or present, the configuration will be included in the generated alias database. If absent, the configuration will be removed from the alias database. If ignore, a given configuration entries will be skipped during alias evaluation and won't affect any existing entries.

An example extended configuration (playbook excerpt):

roles:

  - role: debops.etc_aliases
    etc_aliases__dependent_recipients:
      - role: 'role_name'
        config: '{{ role_name__etc_aliases__dependent_recipients }}'

The above configuration layout allows for use of the multiple role dependencies in one playbook by providing configuration of each role in a separate configuration entry.

Dependent configuration storage and retrieval

The dependent configuration from other roles is stored in the secret/ directory on the Ansible Controller (see debops.secret for more details) in a JSON file, with each role configuration in a separate dictionary. The debops.etc_aliases role reads this file when Ansible local facts indicate that the /etc/aliases file is configured, otherwise a new empty file is created. This ensures that the stale configuration is not present on a new or re-installed host.

The YAML dictionaries from different roles are be merged with the main configuration in the etc_aliases__combined_recipients variable that is used to generate the final configuration. The merge order of the different etc_aliases__*_recipients variables allows to further affect the dependent configuration through Ansible inventory if necessary, therefore the Ansible roles that use this method don't need to provide additional variables for this purpose themselves.

Example role default variables

---

# This is a set of default variables in an example 'application' role that uses
# dependent variables to pass configuration to 'debops.etc_aliases' role.

# /etc/aliases mail recipients defined by the application
application__etc_aliases__dependent_recipients:

  - name: 'application'
    dest: [ 'user1', 'user2' ]

Example role playbook

---

# This is a playbook for an example 'application' role which uses
# 'debops.etc_aliases' as a dependency and passes its own set of
# configuration options to it.

- name: Manage application
  collections: [ 'debops.debops' ]
  hosts: [ 'debops_service_application' ]
  become: True

  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'

  pre_tasks:

    - name: Prepare etc_aliases environment
      ansible.builtin.import_role:
        name: 'etc_aliases'
        tasks_from: 'main_env'
      tags: [ 'role::etc_aliases', 'role::secret' ]

  roles:

    - role: secret
      tags: [ 'role::secret', 'role::etc_aliases' ]
      secret__directories:
        - '{{ etc_aliases__secret__directories }}'

    - role: etc_aliases
      tags: [ 'role::etc_aliases' ]
      etc_aliases__dependent_recipients:

        # Short form of dependent configuration
        - application: '{{ application__etc_aliases__dependent_recipients }}'

        # Alternavie form of dependent configuration
        - role: 'application'
          config: '{{ application__etc_aliases__dependent_recipients }}'
          state: 'present'

    - role: application
      tags: [ 'role::application' ]