From f94fe61b6b393daa2256977d495014d0c54e8a5d Mon Sep 17 00:00:00 2001 From: Toshio Kuratomi Date: Mon, 22 Jan 2018 16:58:43 -0800 Subject: [PATCH] Documentation and changelog for the plugin_filtering config option --- CHANGELOG.md | 1 + docs/docsite/rst/plugin_filtering_config.rst | 26 ++++++++++++++++++++ lib/ansible/config/base.yml | 3 ++- 3 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 docs/docsite/rst/plugin_filtering_config.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index a7141b1e480..4844867d4c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ Ansible Changes By Release * Added fact namespacing, from now on facts will be available under `ansible_facts` namespace (i.e. `ansible_facts.os_distribution`) w/o the `ansible_` prefix. They will continue to be added into the main namespace directly, but now with a configuration toggle to enable this, currently on by default, in the future it will be off. +* Add a configuration file to filter modules that a site administrator wants to exclude from being used. ### Deprecations * Previously deprecated 'hostfile' config settings have been 're-deprecated' as previously code did not warn about deprecated configuration settings. diff --git a/docs/docsite/rst/plugin_filtering_config.rst b/docs/docsite/rst/plugin_filtering_config.rst new file mode 100644 index 00000000000..e17a7aadaa7 --- /dev/null +++ b/docs/docsite/rst/plugin_filtering_config.rst @@ -0,0 +1,26 @@ +.. _plugin_filter_config: + +Plugin Filter Configuration +=========================== + +Ansible 2.5 adds the ability for a site administrator to blacklist modules that they do not want to +be available to Ansible. This is configured via a yaml configuration file (by default, +:file:`/etc/ansible/plugin_filters.yml`). The format of the file is: + +.. code-block:: YAML + + --- + filter_version: '1.0' + module_blacklist: + # Deprecated + - docker + # We only allow pip, not easy_install + - easy_install + +The file contains two fields: + +* a version so that it will be possible to update the format while keeping backwards + compatibility in the future The present version should be the string, ``"1.0"`` + +* a list of modules to blacklist. Any module listed here will not be found by Ansible when it + searches for a module to invoke for a task. diff --git a/lib/ansible/config/base.yml b/lib/ansible/config/base.yml index 8f791eeac2f..5d25cc9e716 100644 --- a/lib/ansible/config/base.yml +++ b/lib/ansible/config/base.yml @@ -1392,7 +1392,8 @@ PLUGIN_FILTERS_CFG: default: null version_added: "2.5.0" description: - - "A path to configuration for filtering which plugins installed on the system are allowed to be used" + - "A path to configuration for filtering which plugins installed on the system are allowed to be used." + - "See :doc:`plugin_filtering_config` for details of the filter file's format." - " The default is /etc/ansible/plugin_filters.yml" ini: - key: plugin_filters_cfg