Document execution_wrapper setting.
Previously this setting, and the nullwrap/bubblewrap driver difference,
were undocumented.
Change-Id: I10a283dee44012f6697ddba0c3bd99b3993b1606
diff --git a/doc/source/admin/components.rst b/doc/source/admin/components.rst
index aa6d8c8..2c70d47 100644
--- a/doc/source/admin/components.rst
+++ b/doc/source/admin/components.rst
@@ -311,10 +311,10 @@
*trusted* execution context, otherwise, it is run in the *untrusted*
execution context.
-Both execution contexts use `bubblewrap`_ to create a namespace to
-ensure that playbook executions are isolated and are unable to access
-files outside of a restricted environment. The administrator may
-configure additional local directories on the executor to be made
+Both execution contexts use `bubblewrap`_ [#nullwrap]_ to create a
+namespace to ensure that playbook executions are isolated and are unable
+to access files outside of a restricted environment. The administrator
+may configure additional local directories on the executor to be made
available to the restricted environment.
The trusted execution context has access to all Ansible features,
@@ -335,6 +335,8 @@
protections are made as part of a defense-in-depth strategy.
.. _bubblewrap: https://github.com/projectatomic/bubblewrap
+.. [#nullwrap] Unless one has set execution_wrapper to nullwrap in the
+ executor configuration.
Configuration
~~~~~~~~~~~~~
@@ -437,6 +439,25 @@
List of paths, separated by ``:`` to read-write bind mount into
untrusted bubblewrap contexts.
+ .. attr:: execution_wrapper
+ :default: bubblewrap
+
+ Name of the execution wrapper to use when executing
+ `ansible-playbook`. The default, `bubblewrap` is recommended for
+ all installations.
+
+ There is also a `nullwrap` driver for situations where one wants
+ to run Zuul without access to bubblewrap or in such a way that
+ bubblewrap may interfere with the jobs themselves. However,
+ `nullwrap` is considered unsafe, as `bubblewrap` provides
+ significant protections against malicious users and accidental
+ breakage in playbooks. As such, `nullwrap` is not recommended
+ for use in production.
+
+ This option, and thus, `nullwrap`, may be removed in the future.
+ `bubblewrap` has become integral to securely operating Zuul. If you
+ have a valid use case for it, we encourage you to let us know.
+
.. attr:: merger
.. attr:: git_user_email