community.general.merge_variables lookup – Merge variables whose names match a given pattern

Note

This lookup plugin is part of the community.general collection (version 12.5.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.merge_variables.

New in community.general 6.5.0

Synopsis

  • This lookup returns the merged result of all variables in scope that match the given prefixes, suffixes, or regular expressions, optionally.

Terms

Parameter

Comments

Terms

list / elements=string / required

Depending on the value of pattern_type, this is a list of prefixes, suffixes, or regular expressions that is used to match all variables that should be merged.

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('community.general.merge_variables', key1=value1, key2=value2, ...) and query('community.general.merge_variables', key1=value1, key2=value2, ...)

Parameter

Comments

default_merge

string

added in community.general 12.5.0

Merge strategy applied to other types.

This value is only considered in case of override=warn or override=ignore.

Choices:

  • "keep": Keep existing values.

  • "replace" (default): Overwrite existing values.

dict_merge

string

added in community.general 12.5.0

Behavior when encountering dictionary values.

Choices:

  • "deep" (default): Merge dictionaries recursively.

  • "keep": Keep existing dictionaries.

  • "replace": Overwrite existing dictionaries.

  • "shallow": Merge only top-level values.

groups

list / elements=string

added in community.general 8.5.0

Search for variables across hosts that belong to the given groups. This allows to collect configuration pieces across different hosts (for example a service on a host with its database on another host).

initial_value

any

An initial value to start with.

list_merge

string

added in community.general 12.5.0

Behavior when encountering list values.

Choices:

  • "append" (default): Append elements to the end of an existing list.

  • "keep": Keep existing lists.

  • "merge": Take the index as key and merge each element.

  • "prepend": Insert elements at the beginning of an existing list.

  • "replace": Overwrite existing lists.

list_transformations

list / elements=any

added in community.general 12.5.0

List transformations applied to list types.

The definition order corresponds to the order in which these transformations are applied.

Elements can be a dict with the keys mentioned below or a string naming the transformation to apply.

Default: []

name

string / required

Name of the list transformation.

Choices:

  • "dedup": Remove duplicates from lists. Supported option is keep.

  • "flatten": Flatten lists, converting nested lists into single lists. Does not support any additional options.

options

dictionary

Options as key value pairs.

keep

string

Determines which duplicates (if any) to keep.

Only valid in combination with the list_transformations[].name=dedup list transformation.

Choices:

  • "first" (default): Drop duplicates except for the first occurrence.

  • "last": Drop duplicates except for the last occurrence.

override

string

Return an error, print a warning or ignore it when a key is overwritten.

The default behavior error makes the plugin fail when a key would be overwritten.

When warn and ignore are used, note that it is important to know that the variables are sorted by name before being merged. Keys for later variables in this order overwrite keys of the same name for variables earlier in this order. To avoid potential confusion, better use override=error whenever possible.

Choices:

  • "error" ← (default)

  • "warn"

  • "ignore"

Configuration:

pattern_type

string

Change the way of searching for the specified pattern.

Choices:

  • "prefix"

  • "suffix"

  • "regex" ← (default)

Configuration:

type_conflict_merge

string

added in community.general 12.5.0

Merge strategy to apply on type conflicts.

This value is only considered in case of override=warn or override=ignore.

Choices:

  • "keep": Keep existing values.

  • "replace" (default): Overwrite existing values.

Note

Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) 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. The entry types are also ordered by precedence from low to high priority order. For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).

Notes

Note

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

Examples

# Some example variables, they can be defined anywhere as long as they are in scope
test_init_list:
  - "list init item 1"
  - "list init item 2"

testa__test_list:
  - "test a item 1"

testb__test_list:
  - "test b item 1"

testa__test_dict:
  ports:
    - 1

testb__test_dict:
  ports:
    - 3

testa_low_dict__test:
  a:
    a:
      x: low_value
      y: low_value
      list:
        - low_value
  b:
    - 1
    - 1
    - 2
    - 3

testb_high_dict__test:
  a:
    a:
      y: high_value
      z: high_value
      list:
        - high_value
  b:
    - 3
    - 4
    - 4
    - '5': value

# Merge variables that end with '__test_dict' and store the result in a variable 'example_a'
example_a: "{{ lookup('community.general.merge_variables', '__test_dict', pattern_type='suffix') }}"

# The variable example_a now contains:
# ports:
#   - 1
#   - 3

# Merge variables that match the '^.+__test_list$' regular expression, starting with an initial value and store the
# result in a variable 'example_b'
example_b: "{{ lookup('community.general.merge_variables', '^.+__test_list$', initial_value=test_init_list) }}"

# The variable example_b now contains:
#   - "list init item 1"
#   - "list init item 2"
#   - "test a item 1"
#   - "test b item 1"

# Shallow merge variables that end with '__test', insert list elements at the beginning of the list,
# remove duplicates from lists (keep the first occurrence), and store the result in a variable 'example_c'
example_c: "{{
  lookup(
    'community.general.merge_variables',
    '^.+__test$',
    dict_merge='shallow',
    list_merge='prepend',
    list_transformations=['dedup']) }}"

# The variable example_c now contains:
# a:
#   a:
#     y: high_value
#     z: high_value
#     list:
#       - high_value
# b:
#   - 3
#   - 4
#   - '5': value
#   - 1
#   - 2

# Deep merge variables that end with '__test', merge list elements by index, ignore overrides, apply the strategies
# 'keep' for type conflicts and 'replace' for other types, and store the result in a variable 'example_d'
example_d: "{{
  lookup(
    'community.general.merge_variables',
    '^.+__test$',
    dict_merge='deep',
    list_merge='merge',
    override='ignore',
    type_conflict_merge='keep',
    default_merge='replace') }}"

# The variable example_d now contains:
# a:
#   a:
#     x: low_value
#     y: high_value
#     list:
#       - high_value
#     z: high_value
# b:
#   - 3
#   - 4
#   - 4
#   - 3

Return Value

Key

Description

Return value

any

In case the search matches list items, a list is returned. In case the search matches dicts, a dict is returned.

Returned: success

Authors

  • Roy Lenferink (@rlenferink)

  • Mark Ettema (@m-a-r-k-e)

  • Alexander Petrenz (@alpex8)

  • Christoph Fiehe (@cfiehe)