Allow loading additional variables file for site config
It would be useful to allow deployment specific configuration that can
be fed into the project-config deployments so that we can customize
things like host ip without having to change job definitions for each
site.
Also, add a method to display the build log from a failed assertion in
the Ansible test (this was used in the development of the tests for
this change).
Change-Id: I87e8bffc540bcafab543c46244f3d5327b56fcae
Co-Authored-By: James E. Blair <jeblair@redhat.com>
diff --git a/doc/source/admin/components.rst b/doc/source/admin/components.rst
index cc9d181..99912d7 100644
--- a/doc/source/admin/components.rst
+++ b/doc/source/admin/components.rst
@@ -317,6 +317,24 @@
user=zuul
+.. _admin_sitewide_variables:
+
+**variables**
+ Path to an Ansible variables file to supply site-wide variables.
+ This should be a YAML-formatted file consisting of a single
+ dictionary. The contents will be made available to all jobs as
+ Ansible variables. These variables take precedence over all other
+ forms (job variables and secrets). Care should be taken when naming
+ these variables to avoid potential collisions with those used by
+ jobs. Prefixing variable names with a site-specific identifier is
+ recommended. The default is not to add any site-wide variables.
+ See the :ref:`User's Guide <user_sitewide_variables>` for more
+ information.
+
+ Example::
+
+ variables=/etc/zuul/variables.yaml
+
merger
""""""
diff --git a/doc/source/user/jobs.rst b/doc/source/user/jobs.rst
index a367aa0..1812bc5 100644
--- a/doc/source/user/jobs.rst
+++ b/doc/source/user/jobs.rst
@@ -73,6 +73,24 @@
Variables
---------
+There are several sources of variables which are available to Ansible:
+variables defined in jobs, secrets, and site-wide variables. The
+order of precedence is:
+
+* Site-wide variables
+
+* Secrets
+
+* Job variables
+
+Meaning that a site-wide variable with the same name as any other will
+override its value, and similarly, secrets override job variables of
+the same name. Each of the three sources is described below.
+
+
+Job Variables
+~~~~~~~~~~~~~
+
Any variables specified in the job definition are available as Ansible
host variables. They are added to the `vars` section of the inventory
file under the `all` hosts group, so they are available to all hosts.
@@ -293,6 +311,19 @@
**zuul.executor.log_root**
The path to the logs directory.
+
+.. _user_sitewide_variables:
+
+Site-wide Variables
+~~~~~~~~~~~~~~~~~~~
+
+The Zuul administrator may define variables which will be available to
+all jobs running in the system. These are statically defined and may
+not be altered by jobs. See the :ref:`Administrator's Guide
+<admin_sitewide_variables>` for information on how a site
+administrator may define these variables.
+
+
SSH Keys
--------