Expose nodepool slot attribute

Nodepool now exposes a slot attribute which is set by the static
and metastatic drivers to provide a stable id for which "slot"
is occupied by a node on a host with max-parallel-jobs > 1.

Expose this as a variable to Ansible so that jobs can use it
to provide stable but non-conflicting workspace paths.

This also documents all of the current "nodepool" host vars.

Change-Id: I07cea423df7811c1de7763ff48b8308768246810

4 files changed, 71 insertions, 0 deletions

diff --git a/doc/source/job-content.rst b/doc/source/job-content.rst
index 75044cf1c..0ef9f5995 100644
--- a/doc/source/job-content.rst
+++ b/doc/source/job-content.rst
@@ -670,6 +670,68 @@ of item.
        - shell: echo example
          when: zuul_success | bool
 
+.. var:: nodepool
+
+   Information about each host from Nodepool is supplied in the
+   `nodepool` host variable.  Availability of values varies based on
+   the node and the driver that supplied it.  Values may be ``null``
+   if they are not applicable.
+
+   .. var:: label
+
+      The nodepool label of this node.
+
+   .. var:: az
+
+      The availability zone in which this node was placed.
+
+   .. var:: cloud
+
+      The name of the cloud in which this node was created.
+
+   .. var:: provider
+
+      The name of the nodepool provider of this node.
+
+   .. var:: region
+
+      The name of the nodepool provider's region.
+
+   .. var:: host_id
+
+      The cloud's host identification for this node's hypervisor.
+
+   .. var:: external_id
+
+      The cloud's identifier for this node.
+
+   .. var:: slot
+
+      If the node supports running multiple jobs on the node, a unique
+      numeric ID for the subdivision of the node assigned to this job.
+      This may be used to avoid build directory collisions.
+
+   .. var:: interface_ip
+
+      The best IP address to use to contact the node as determined by
+      the cloud provider and nodepool.
+
+   .. var:: public_ipv4
+
+      A public IPv4 address of the node.
+
+   .. var:: private_ipv4
+
+      A private IPv4 address of the node.
+
+   .. var:: public_ipv6
+
+      A public IPv6 address of the node.
+
+   .. var:: private_ipv6
+
+      A private IPv6 address of the node.
+
 
 Change Items
 ~~~~~~~~~~~~
diff --git a/releasenotes/notes/nodepool-slot-2061128253e50580.yaml b/releasenotes/notes/nodepool-slot-2061128253e50580.yaml
new file mode 100644
index 000000000..c7ba3e1dc
--- /dev/null
+++ b/releasenotes/notes/nodepool-slot-2061128253e50580.yaml
@@ -0,0 +1,7 @@
+---
+features:
+  - |
+    The :var:`nodepool.slot` variable has been added to host vars.
+    This is supplied by the nodepool static and metastatic drivers
+    starting with version 8.0.0.  It may be used to avoid build
+    directory collisions on nodes that run more than one job.
diff --git a/zuul/executor/server.py b/zuul/executor/server.py
index b7fed2a8c..b6845c9bc 100644
--- a/zuul/executor/server.py
+++ b/zuul/executor/server.py
@@ -1929,6 +1929,7 @@ class AnsibleJob(object):
                         region=node.region,
                         host_id=node.host_id,
                         external_id=getattr(node, 'external_id', None),
+                        slot=node.slot,
                         interface_ip=node.interface_ip,
                         public_ipv4=node.public_ipv4,
                         private_ipv4=node.private_ipv4,
diff --git a/zuul/model.py b/zuul/model.py
index c2da4f65c..4e1701376 100644
--- a/zuul/model.py
+++ b/zuul/model.py
@@ -1336,6 +1336,7 @@ class Node(ConfigObject):
         self.private_ipv6 = None
         self.connection_port = 22
         self.connection_type = None
+        self.slot = None
         self._keys = []
         self.az = None
         self.provider = None