Documentation and changelog for the plugin_filtering config option

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.

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.

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