Discuss executor-only jobs, add unit-test

This expands the discussion of executor-only jobs with some additional
notes.

Additionally a unit test is added to explicitly test executor-only
(i.e. blank nodeset) jobs.

Change-Id: I8fd2f932290e49da5a3605737e8940425cd092f4

doc/source/user/config.rst

@@ -822,8 +822,36 @@ Here is an example of two job definitions:
       Nodeset definition unique to this job).  See the :ref:`nodeset`
       reference for the syntax to use in that case.
 
-      If a job has an empty or no nodeset definition, it will still
-      run and may be able to perform actions on the Zuul executor.
+      If a job has an empty (or no) :ref:`nodeset` definition, it will
+      still run and is able to perform limited actions within the Zuul
+      executor sandbox (e.g. copying files or triggering APIs).  Note
+      so-called "executor-only" jobs run with an empty inventory, and
+      hence Ansible's *implicit localhost*.  This means an
+      executor-only playbook must be written to match ``localhost``
+      directly; i.e.
+
+      .. code-block:: yaml
+
+          - hosts: localhost
+            tasks:
+             ...
+
+      not with ``hosts: all`` (as this does not match the implicit
+      localhost and the playbook will not run).  There are also
+      caveats around things like enumerating the magic variable
+      ``hostvars`` in this situation.  For more information see the
+      Ansible `implicit localhost documentation
+      <https://docs.ansible.com/ansible/latest/inventory/implicit_localhost.html>`__.
+
+      A useful example of executor-only jobs is saving resources by
+      directly utilising the prior results from testing a committed
+      change.  For example, a review which updates documentation
+      source files would generally test validity by building a
+      documentation tree.  When this change is committed, the
+      pre-built output can be copied in an executor-only job directly
+      to the publishing location in a post-commit *promote* pipeline;
+      avoiding having to use a node to rebuild the documentation for
+      final publishing.
 
    .. attr:: override-checkout
 

tests/fixtures/config/inventory/git/common-config/playbooks/executor-only-inventory.yaml

@@ -0,0 +1,2 @@
+- hosts: localhost
+  tasks: []

tests/fixtures/config/inventory/git/common-config/zuul.yaml

@@ -65,6 +65,12 @@
           label: ubuntu-xenial
     run: playbooks/single-inventory.yaml
 
+- job:
+    name: executor-only-inventory
+    nodeset:
+      nodes: []
+    run: playbooks/executor-only-inventory.yaml
+
 - job:
     name: group-inventory
     nodeset: nodeset1

tests/fixtures/config/inventory/git/org_project/.zuul.yaml

@@ -4,5 +4,6 @@
       jobs:
         - single-inventory
         - single-inventory-list
+        - executor-only-inventory
         - group-inventory
         - hostvars-inventory

tests/unit/test_inventory.py

@@ -122,6 +122,27 @@ class TestInventory(TestInventoryBase):
         self.executor_server.release()
         self.waitUntilSettled()
 
+    def test_executor_only_inventory(self):
+        inventory = self._get_build_inventory('executor-only-inventory')
+
+        self.assertIn('all', inventory)
+        self.assertIn('hosts', inventory['all'])
+        self.assertIn('vars', inventory['all'])
+
+        # Should be blank; i.e. rely on the implicit localhost
+        self.assertEqual(0, len(inventory['all']['hosts']))
+
+        self.assertIn('zuul', inventory['all']['vars'])
+        z_vars = inventory['all']['vars']['zuul']
+        self.assertIn('executor', z_vars)
+        self.assertIn('src_root', z_vars['executor'])
+        self.assertIn('job', z_vars)
+        self.assertEqual(z_vars['job'], 'executor-only-inventory')
+        self.assertEqual(z_vars['message'], 'QQ==')
+
+        self.executor_server.release()
+        self.waitUntilSettled()
+
     def test_group_inventory(self):
 
         inventory = self._get_build_inventory('group-inventory')