DEBOPS.ENVIRONMENT(5)

NAME
debops.environment - Manage system environment variables using Ansible

SYNOPSIS

debops run service/environment [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The debops.environment role can be used to manage system-wide environment variables, by default located in /etc/environment file. Variables are gathered from multiple sources and combined to allow global/group/host tiered environment modeled after Ansible inventory.

This role can also be used by other Ansible roles as a dependency to create global environment variables in a safe way, that preserves idempotency.

GETTING STARTED

  Usage with inventory__environment

The DebOps playbooks use a set of Ansible inventory variables to provide custom environment during the playbook execution. These are YAML dictionary variables:

•   inventory__environment

•   inventory__group_environment

•   inventory__host_environment

    The debops.environment includes contents of these variables in its own environment__default_variables list, which is then added to the /etc/environment file on each host. Other variable lists described below can override these environment variables if necessary.

    The inventory__*_environment variables are the best place to set variables if you want to have the same environment during Ansible playbook execution and on the host itself over ssh or via cron, etc. See the documentation on custom environment variables <https://docs.debops.org/en/latest/user-guide/custom-environment.html> for more details.

  Ansible inventory layout

The role uses multiple lists of variables which can be defined in Ansible inventory:

environment__variables
    This list can be defined in inventory/group_vars/debops_all_hosts/environment.yml file to define variables that should be set on all hosts in the inventory.

environment__group_variables
    This list can be defined in a specific group, for example inventory/group_vars/<group_name>/environment.yml to set variables on a group of hosts. Only one "level" of such variables is supported.

environment__host_variables
    This list can be defined for a specific host, for example in inventory/host_vars/<hostname>/environment.yml file, to set variables only on that host.

    The environment variables set in above lists are combined in above order, therefore more specific variables will "mask" more general ones, just like Ansible inventory variables. If you remove already set variables, they will be automatically removed on the corresponding hosts as well on the next Ansible playbook run.

  Usage as a role dependency

Other roles can use debops.environment role in their own playbooks to idempotently set environment variables in /etc/environment file. Variables set in this way (using environment__dependent_variables list) will be stored in Ansible local facts on the affected hosts so that they will be preserved on subsequent Ansble runs. They will not be removed automatically.

The variables defined by roles override variables defined through Ansible inventory.

  Example inventory

The debops.environment role is included in the common.yml DebOps playbook, therefore you don't need to add a host to specific group to use it.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.environment role:

---
- name: Manage system environment variables
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_environment' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: environment
      tags: [ 'role::environment', 'skip::environment' ]

DEFAULT VARIABLE DETAILS

Some of debops.environment default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  environment__variables

The environment variable lists can use different formats of list entries.

Strings:

environment__variables:
  - 'variable1=value1'
  - 'variable2=value2'
  - 'variable3=value3'

YAML dictionaries of variables:

environment__variables:
  - variable1: 'value1'
    variable2: 'value2'
    variable3: 'value3'

YAML dictionaries of conditional variables - they are detected when name and value keys are used in the same YAML dictionary:

environment__variables:
  - name: 'variable1'
    value: 'value1'
  - name: 'variable2'
    value: 'value2'
    state: 'absent'
  - name: 'variable3'
    value: 'value3'
    upper: True

When the conditional variables are detected, you can specify these parameters:

name
    Required. Name of the environment variable.

value
    Required. Value of the environment variable.

state
    Optional. If not specified or present, variable will be set in the /etc/environment file. If absent, variable will not be included. The role does not remove already set variables in the /etc/environment file outside of the Ansible block.

case
    Optional. Change the case of the variable name, either upper or lower. If not set, the current case will be preserved.

    To set the name and value variables in the environment, you need to specify them separately:

    environment__variables:
      - name: 'value1'
      - value: 'value2'

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others