Usage Guide

The community.library_inventory_filtering_v1 collection enables other collections to add common filter functionality to inventory plugins.

Requirements

The stable-1 branch of this collection, released as , works with all ansible-base and ansible-core versions, and with Ansible >= 2.9.10.

Adding filter functionality to an inventory plugin

The preferred way to use this collection is to use the inventory_filter docs fragment and the inventory_filter plugin utils.

To use the documentation fragment, add it to the extends_documentation_fragment list in DOCUMENTATION:

extends_documentation_fragment:
  - community.library_inventory_filtering_v1.inventory_filter

For the filtering, you need to import two functions from the plugin util, parse_filters() and filter_host():

from ansible_collections.community.library_inventory_filtering_v1.plugins.plugin_utils.inventory_filter import (
    parse_filters,
    filter_host,
)

You can use parse_filters() to parse the filters option’s value (self.get_option('filters')), and filter_host() to determine whether to include a host:

class InventoryModule(BaseInventoryPlugin, ...):

    def parse(self, inventory, loader, path, cache=True):
        super(InventoryModule, self).parse(inventory, loader, path, cache)
        self._read_config_data(path)

        ...

        # Parse the filters option
        filters = parse_filters(self.get_option('filters'))

        ...

        for host in hosts:
            # Compile the host vars
            host_vars = ...

            # Now we can evaluate potential filter conditions
            # based on the host name and host vars:
            if not filter_host(self, host, host_vars, filters):
                continue

            # Add the host with its vars
            self.inventory.add_host(name)
            for key, value in host_vars.items():
                self.inventory.set_variable(name, key, value)

        ...