Getting started
Usage as a role dependency
To use the custom Ansible plugins from this role in your own Ansible roles, you
should include the ansible_plugins
role as a dependency, in
meta/main.yml
file of a given role:
---
dependencies:
- role: ansible_plugins
This will make the ansible_plugins
role a hard dependency of a given role,
which should ensure that the ansible_plugins
role is always included, and
doesn't need to be included in all playbooks that use a given role.
Custom Ansible filter plugins
The role contains a set of custom Ansible filter plugins which can be used in Jinja templates:
globmatch
This filter plugin can be used to filter strings or lists that match shell glob patterns.
split
This filter plugin can be used to split strings, similarly to the
.split()
function in Python.
Configuration filters
These filters are used to implement DebOps Universal Configuration. See the user-facing documentation for the behaviors they are meant to facilitate.
debops.debops.parse_kv_config
Parse a YAML list of dictionaries and output a sorted and expanded list of YAML dictionaries that contain a common set of dictionary keys. The filter supports dynamic order of the entries using weight model, and can be used to generate a configuration file which uses a key/value syntax with unique keys.
The
debops.debops.parse_kv_config
filter accepts this argument:name
Optional, String. Defaults to
name
. Sets the name of the field to be used as the unique key.
debops.debops.parse_kv_items
This is a wrapper for the
debops.debops.parse_kv_config
filter which can be used in the looped Ansible tasks to manage multiple files with key/value syntax, or generate a configuration file with multiple key/value configuration structures.The
debops.debops.parse_kv_items
filter accepts the following arguments:name
Optional, String. Defaults to
name
. Sets the name of the field to be used as the unique key.defaults
Optional, Dict. Keys are parameter names, values are default values to use when a parameter is not specified. Examples:
{{ variable | debops.debops.parse_kv_items(defaults={'some_param': 'default_value'}) }}
empty
Optional, Dict. Keys are fields which might be empty, values are other field names or lists of field names.
The value of the first field with a value other than
None
will be used as the value of the specified field, if the specified field is empty.This behavior does not extend to fields in second-level lists, such as
options
or other definedmerge_keys
.For example, running the filter with the following dict as
empty
:{{ variable | debops.debops.parse_kv_items( empty={ 'some_param': 'other_param', 'empty_param': ['param1', 'param2'] }) }}
Will turn these input items:
- name: foo other_param: bar - name: fizz param2: buzz
Into ones looking like this (plus the extra fields described later on):
- name: foo some_param: bar other_param: bar - name: fizz empty_param: buzz param2: buzz
merge_keys
Optional. List of keys in the item that will be processed by the filter. If not specified, lists in the
options
field will be processed by default.
Output mappings
These values get populated in the parse_kv_*
output mappings:
id
: The initial source order of the items in the input list* 10
.state
defaults topresent
weight
: The weight as defined in the source mapping. Defaults to0
.real_weight
: Calculated from addingweight
andid
.section
: defaults tounknown
. Can be used by roles to split sections.separator
: defaults toFalse
. Can be used by roles to affect formatting.
Any other values in the mappings are preserved, so the parse_kv_*
filters
can be used to weigh and merge arbitrary of mappings, as long as they have a
unique key field.
The filter plugins source contains tests you may find useful in better
understanding the parse_kv_*
filters' behavior.
Custom Ansible lookup plugins
The role contains a set of custom Ansible lookup plugins which can be used in Ansible roles:
debops.debops.file_src
This lookup plugin allows "sideloading" files to copy into roles without the need to modify the roles themselves. It requires the
debops
Python module to be installed and uses configuration in.debops.cfg
to get a list of directories that are bases to look for custom files.If a file in specified subdirectory is found in one of the base directories, its path will be returned to Ansible to use as a file source. If no custom files are found, the lookup plugin returns the original path which corresponds to the file included in the role itself.
debops.debops.lists
This lookup plugin implements the
with_lists
lookup. Similar towith_flattened
lookup, the difference is the lists are not flattened all the way into a single list, therefore you can perform a "list of lists" tasks.debops.debops.task_src
This lookup plugin allows injection of custom Ansible tasks into roles without the need to modify the roles themselves. It requires the
debops
Python module to be installed and uses configuration in.debops.cfg
to get a list of directories that are bases to look for a list of Ansible tasks.If a file with list of tasks is found, they will be added to the Ansible playbook execution, usually as "pre" or "post" tasks at the beginning or end of a role. If no tasks are found, the plugin returns the path to a predefined, usually empty file with no tasks, that gets included by Ansible, avoiding the issue of missing task list. The roles that use this plugin need to be prepared for this usage beforehand.
debops.debops.template_src
This lookup plugin allows "sideloading" Jinja templates into roles without the need to modify the roles themselves. It requires the
debops
Python module to be installed and uses configuration in.debops.cfg
to get a list of directories that are bases to look for templates.If a template file in specified subdirectory is found in one of the base directories, its path will be returned to Ansible to use as a template. If no custom templates are found, the lookup plugin returns the original path which corresponds to the template included in the role itself.