Much like distributing custom modules, there are standard places to store custom plugins alongside playbooks that expect to use plugins. The default locations for plugins are the locations that are shipped with the Ansible code install, subdirectories within ~/.ansible/plugins/, and subdirectories of the project root (the place where the top-level playbook is stored). Plugins can be distributed within the same subdirectories of a role as well. To utilize plugins from any other location, we need to define the location to find the plugin for the plugin type in an ansible.cfg file.
When distributing plugins inside the project root, each plugin type gets its own top-level directory:
- action_plugins/
- cache_plugins/
- callback_plugins/
- connection_plugins/
- shell_plugins/
- lookup_plugins/
- vars_plugins/
- filter_plugins/
As with other Ansible constructs, the first plugin with a given name found will be used, and just as with modules, the paths relative to the project root are checked first, allowing a local override of an existing plugin. Simply place the filter file into the appropriate subdirectory, and it will automatically get used when referenced.