From 76654077992b5e95658f5069dae9791326b53f6d Mon Sep 17 00:00:00 2001
From: Albin Vass <albin.vass@gmail.com>
Date: Tue, 10 Nov 2020 21:51:31 +0100
Subject: [PATCH] Reorganize drivers into separate documents

Change-Id: I4274d8d87058a2a5c91da3e994a32d61b2f2aafe
---
 doc/source/aws.rst            |  334 ++++++
 doc/source/azure.rst          |  220 ++++
 doc/source/configuration.rst  | 2135 +--------------------------------
 doc/source/gce.rst            |  259 ++++
 doc/source/kubernetes.rst     |  174 +++
 doc/source/openshift-pods.rst |  140 +++
 doc/source/openshift.rst      |  181 +++
 doc/source/openstack.rst      |  635 ++++++++++
 doc/source/static.rst         |  150 +++
 9 files changed, 2133 insertions(+), 2095 deletions(-)
 create mode 100644 doc/source/aws.rst
 create mode 100644 doc/source/azure.rst
 create mode 100644 doc/source/gce.rst
 create mode 100644 doc/source/kubernetes.rst
 create mode 100644 doc/source/openshift-pods.rst
 create mode 100644 doc/source/openshift.rst
 create mode 100644 doc/source/openstack.rst
 create mode 100644 doc/source/static.rst

diff --git a/doc/source/aws.rst b/doc/source/aws.rst
new file mode 100644
index 000000000..432459c6e
--- /dev/null
+++ b/doc/source/aws.rst
@@ -0,0 +1,334 @@
+.. _aws-driver:
+
+.. default-domain:: zuul
+
+AWS EC2 Driver
+--------------
+
+Selecting the aws driver adds the following options to the :attr:`providers`
+section of the configuration.
+
+.. attr-overview::
+   :prefix: providers.[aws]
+   :maxdepth: 3
+
+.. attr:: providers.[aws]
+   :type: list
+
+   An AWS provider's resources are partitioned into groups called `pool`
+   (see :attr:`providers.[aws].pools` for details), and within a pool,
+   the node types which are to be made available are listed
+   (see :attr:`providers.[aws].pools.labels` for details).
+
+   See `Boto Configuration`_ for information on how to configure credentials
+   and other settings for AWS access in Nodepool's runtime environment.
+
+   .. note:: For documentation purposes the option names are prefixed
+             ``providers.[aws]`` to disambiguate from other
+             drivers, but ``[aws]`` is not required in the
+             configuration (e.g. below
+             ``providers.[aws].pools`` refers to the ``pools``
+             key in the ``providers`` section when the ``aws``
+             driver is selected).
+
+   Example:
+
+   .. code-block:: yaml
+
+     providers:
+       - name: ec2-us-west-2
+         driver: aws
+         region-name: us-west-2
+         cloud-images:
+           - name: debian9
+             image-id: ami-09c308526d9534717
+             username: admin
+         pools:
+           - name: main
+             max-servers: 5
+             subnet-id: subnet-0123456789abcdef0
+             security-group-id: sg-01234567890abcdef
+             labels:
+               - name: debian9
+                 cloud-image: debian9
+                 instance-type: t3.medium
+                 iam-instance-profile:
+                   arn: arn:aws:iam::123456789012:instance-profile/s3-read-only
+                 key-name: zuul
+                 tags:
+                   key1: value1
+               - name: debian9-large
+                 cloud-image: debian9
+                 instance-type: t3.large
+                 key-name: zuul
+                 tags:
+                   key1: value1
+                   key2: value2
+
+   .. attr:: name
+      :required:
+
+      A unique name for this provider configuration.
+
+   .. attr:: region-name
+      :required:
+
+      Name of the `AWS region`_ to interact with.
+
+   .. attr:: profile-name
+
+      The AWS credentials profile to load for this provider. If unspecified the
+      `boto3` library will select a profile.
+
+      See `Boto Configuration`_ for more information.
+
+   .. attr:: boot-timeout
+      :type: int seconds
+      :default: 60
+
+      Once an instance is active, how long to try connecting to the
+      image via SSH.  If the timeout is exceeded, the node launch is
+      aborted and the instance deleted.
+
+   .. attr:: launch-retries
+      :default: 3
+
+      The number of times to retry launching a node before considering
+      the job failed.
+
+   .. attr:: cloud-images
+      :type: list
+
+      Each entry in this section must refer to an entry in the
+      :attr:`labels` section.
+
+      .. code-block:: yaml
+
+         cloud-images:
+           - name: ubuntu1804
+             image-id: ami-082fd9a18128c9e8c
+             username: ubuntu
+           - name: ubuntu1804-by-filters
+             image-filters:
+               - name: name
+                 values:
+                  - named-ami
+             username: ubuntu
+           - name: my-custom-win2k3
+             connection-type: winrm
+             username: admin
+
+      Each entry is a dictionary with the following keys
+
+      .. attr:: name
+         :type: string
+         :required:
+
+         Identifier to refer this cloud-image from :attr:`providers.[aws].pools.labels` section.
+         Since this name appears elsewhere in the nodepool configuration file,
+         you may want to use your own descriptive name here and use
+         ``image-id`` to specify the cloud image so that if
+         the image id changes on the cloud, the impact to your Nodepool
+         configuration will be minimal. However, if ``image-id`` is not
+         provided, this is assumed to be the image id in the cloud.
+
+      .. attr:: image-id
+         :type: str
+
+         If this is provided, it is used to select the image from the cloud
+         provider by ID.
+
+      .. attr:: image-filters
+         :type: list
+
+         If provided, this is used to select an AMI by filters.  If the filters
+         provided match more than one image, the most recent will be returned.
+         `image-filters` are not valid if `image-id` is also specified.
+
+         Each entry is a dictionary with the following keys
+
+         .. attr:: name
+            :type: str
+            :required:
+
+            The filter name. See `Boto describe images`_ for a list of valid filters.
+
+         .. attr:: values
+            :type: list
+            :required:
+
+            A list of str values to filter on
+
+      .. attr:: username
+         :type: str
+
+         The username that a consumer should use when connecting to the node.
+
+      .. attr:: python-path
+         :type: str
+         :default: auto
+
+         The path of the default python interpreter.  Used by Zuul to set
+         ``ansible_python_interpreter``.  The special value ``auto`` will
+         direct Zuul to use inbuilt Ansible logic to select the
+         interpreter on Ansible >=2.8, and default to
+         ``/usr/bin/python2`` for earlier versions.
+
+      .. attr:: connection-type
+         :type: str
+
+         The connection type that a consumer should use when connecting to the
+         node. For most images this is not necessary. However when creating
+         Windows images this could be 'winrm' to enable access via ansible.
+
+      .. attr:: connection-port
+         :type: int
+         :default: 22/ 5986
+
+         The port that a consumer should use when connecting to the node. For
+         most diskimages this is not necessary. This defaults to 22 for ssh and
+         5986 for winrm.
+
+   .. attr:: pools
+      :type: list
+
+      A pool defines a group of resources from an AWS provider. Each pool has a
+      maximum number of nodes which can be launched from it, along with a number
+      of cloud-related attributes used when launching nodes.
+
+      .. attr:: name
+         :required:
+
+         A unique name within the provider for this pool of resources.
+
+      .. attr:: node-attributes
+         :type: dict
+
+         A dictionary of key-value pairs that will be stored with the node data
+         in ZooKeeper. The keys and values can be any arbitrary string.
+
+      .. attr:: subnet-id
+
+         If provided, specifies the subnet to assign to the primary network
+         interface of nodes.
+
+      .. attr:: security-group-id
+
+         If provided, specifies the security group ID to assign to the primary
+         network interface of nodes.
+
+      .. attr:: public-ip-address
+         :type: bool
+         :default: True
+
+         Specify if a public ip address shall be attached to nodes.
+
+      .. attr:: host-key-checking
+         :type: bool
+         :default: True
+
+         Specify custom behavior of validation of SSH host keys.  When set to
+         False, nodepool-launcher will not ssh-keyscan nodes after they are
+         booted. This might be needed if nodepool-launcher and the nodes it
+         launches are on different networks.  The default value is True.
+
+      .. attr:: labels
+         :type: list
+
+         Each entry in a pool's `labels` section indicates that the
+         corresponding label is available for use in this pool.  When creating
+         nodes for a label, the flavor-related attributes in that label's
+         section will be used.
+
+         .. code-block:: yaml
+
+            labels:
+              - name: bionic
+                instance-type: m5a.large
+
+         Each entry is a dictionary with the following keys
+
+           .. attr:: name
+              :type: str
+              :required:
+
+              Identifier to refer this label.
+              Nodepool will use this to set the name of the instance unless
+              the name is specified as a tag.
+
+           .. attr:: cloud-image
+              :type: str
+              :required:
+
+              Refers to the name of an externally managed image in the
+              cloud that already exists on the provider. The value of
+              ``cloud-image`` should match the ``name`` of a previously
+              configured entry from the ``cloud-images`` section of the
+              provider. See :attr:`providers.[aws].cloud-images`.
+
+           .. attr:: ebs-optimized
+              :type: bool
+              :default: False
+
+              Indicates whether EBS optimization
+              (additional, dedicated throughput between Amazon EC2 and Amazon EBS,)
+              has been enabled for the instance.
+
+           .. attr:: instance-type
+              :type: str
+              :required:
+
+              Name of the flavor to use.
+
+           .. attr:: iam-instance-profile
+              :type: dict
+
+              Used to attach an iam instance profile.
+              Useful for giving access to services without needing any secrets.
+
+              .. attr:: name
+
+                 Name of the instance profile.
+                 Mutually exclusive with :attr:`providers.[aws].pools.labels.iam-instance-profile.arn`
+
+              .. attr:: arn
+
+                 ARN identifier of the profile.
+                 Mutually exclusive with :attr:`providers.[aws].pools.labels.iam-instance-profile.name`
+
+           .. attr:: key-name
+              :type: string
+              :required:
+
+              The name of a keypair that will be used when
+              booting each server.
+
+           .. attr:: volume-type
+              :type: string
+
+              If given, the root `EBS volume type`_
+
+           .. attr:: volume-size
+              :type: int
+
+              If given, the size of the root EBS volume, in GiB.
+
+           .. attr:: userdata
+              :type: str
+              :default: None
+
+              A string of userdata for a node. Example usage is to install
+              cloud-init package on image which will apply the userdata.
+              Additional info about options in cloud-config:
+              https://cloudinit.readthedocs.io/en/latest/topics/examples.html
+
+           .. attr:: tags
+              :type: dict
+              :default: None
+
+              A dictionary of tags to add to the EC2 instances
+
+.. _`EBS volume type`: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html
+.. _`AWS region`: https://docs.aws.amazon.com/general/latest/gr/rande.html
+.. _`Boto configuration`: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html
+.. _`Boto describe images`: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.describe_images
diff --git a/doc/source/azure.rst b/doc/source/azure.rst
new file mode 100644
index 000000000..a25fb67e7
--- /dev/null
+++ b/doc/source/azure.rst
@@ -0,0 +1,220 @@
+.. _azure-driver:
+
+.. default-domain:: zuul
+
+Azure Compute Driver
+--------------------
+
+Selecting the azure driver adds the following options to the :attr:`providers`
+section of the configuration.
+
+.. attr-overview::
+   :prefix: providers.[azure]
+   :maxdepth: 3
+
+.. attr:: providers.[azure]
+   :type: list
+
+   An Azure provider's resources are partitioned into groups called `pool`,
+   and within a pool, the node types which are to be made available are listed
+
+
+   .. note:: For documentation purposes the option names are prefixed
+             ``providers.[azure]`` to disambiguate from other
+             drivers, but ``[azure]`` is not required in the
+             configuration (e.g. below
+             ``providers.[azure].pools`` refers to the ``pools``
+             key in the ``providers`` section when the ``azure``
+             driver is selected).
+
+   Example:
+
+   .. code-block:: yaml
+
+     providers:
+        - name: azure-central-us
+          driver: azure
+          zuul-public-key: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAA...
+          resource-group-location: centralus
+          location: centralus
+          resource-group: ZuulCIDev
+          auth-path: /Users/grhayes/.azure/nodepoolCreds.json
+          subnet-id: /subscriptions/<subscription-id>/resourceGroups/ZuulCI/providers/Microsoft.Network/virtualNetworks/NodePool/subnets/default
+          cloud-images:
+            - name: bionic
+              username: zuul
+              image-reference:
+                sku: 18.04-LTS
+                publisher: Canonical
+                version: latest
+                offer: UbuntuServer
+          pools:
+            - name: main
+              max-servers: 10
+              labels:
+                - name: bionic
+                  cloud-image: bionic
+                  hardware-profile:
+                    vm-size: Standard_D1_v2
+                  tags:
+                    department: R&D
+                    purpose: CI/CD
+
+   .. attr:: name
+      :required:
+
+      A unique name for this provider configuration.
+
+   .. attr:: location
+      :required:
+
+      Name of the Azure region to interact with.
+
+   .. attr:: resource-group-location
+      :required:
+
+      Name of the Azure region to where the home Resource Group is or should be created.
+
+   .. attr:: auth-path
+      :required:
+
+      Path to the JSON file containing the service principal credentials.
+      Create with the `Azure CLI`_ and the ``--sdk-auth`` flag
+
+   .. attr:: subnet-id
+      :required:
+
+      Subnet to create VMs on
+
+  .. attr:: cloud-images
+     :type: list
+
+     Each entry in this section must refer to an entry in the
+     :attr:`labels` section.
+
+     .. code-block:: yaml
+
+        cloud-images:
+          - name: bionic
+            username: zuul
+            image-reference:
+              sku: 18.04-LTS
+              publisher: Canonical
+              version: latest
+              offer: UbuntuServer
+          - name: windows-server-2016
+            username: zuul
+            image-reference:
+               sku: 2016-Datacenter
+               publisher: MicrosoftWindowsServer
+               version: latest
+               offer: WindowsServer
+
+
+     Each entry is a dictionary with the following keys
+
+     .. attr:: name
+        :type: string
+        :required:
+
+        Identifier to refer this cloud-image from :attr:`labels`
+        section.  Since this name appears elsewhere in the nodepool
+        configuration file, you may want to use your own descriptive
+        name here.
+
+     .. attr:: username
+        :type: str
+
+        The username that a consumer should use when connecting to the
+        node.
+
+     .. attr:: image-reference
+        :type: dict
+        :required:
+
+        .. attr:: sku
+           :type: str
+           :required:
+
+           Image SKU
+
+        .. attr:: publisher
+           :type: str
+           :required:
+
+           Image Publisher
+
+        .. attr:: offer
+           :type: str
+           :required:
+
+           Image offers
+
+        .. attr:: version
+           :type: str
+           :required:
+
+           Image version
+
+
+  .. attr:: pools
+      :type: list
+
+      A pool defines a group of resources from an Azure provider. Each pool has a
+      maximum number of nodes which can be launched from it, along with a number
+      of cloud-related attributes used when launching nodes.
+
+      .. attr:: name
+         :required:
+
+         A unique name within the provider for this pool of resources.
+
+      .. attr:: labels
+         :type: list
+
+         Each entry in a pool's `labels` section indicates that the
+         corresponding label is available for use in this pool.  When creating
+         nodes for a label, the flavor-related attributes in that label's
+         section will be used.
+
+         .. code-block:: yaml
+
+            labels:
+              - name: bionic
+                cloud-image: bionic
+                hardware-profile:
+                  vm-size: Standard_D1_v2
+
+         Each entry is a dictionary with the following keys
+
+           .. attr:: name
+              :type: str
+              :required:
+
+              Identifier to refer this label.
+
+           .. attr:: cloud-image
+             :type: str
+             :required:
+
+             Refers to the name of an externally managed image in the
+             cloud that already exists on the provider. The value of
+             ``cloud-image`` should match the ``name`` of a previously
+             configured entry from the ``cloud-images`` section of the
+             provider.
+
+           .. attr:: hardware-profile
+             :required:
+
+             .. attr:: vm-size
+                :required:
+                :type: str
+
+                VM Size of the VMs to use in Azure. See the VM size list on `azure.microsoft.com`_
+                for the list of sizes availabile in each region.
+
+
+.. _`Azure CLI`: https://docs.microsoft.com/en-us/cli/azure/create-an-azure-service-principal-azure-cli?view=azure-cli-latest
+
+.. _azure.microsoft.com: https://azure.microsoft.com/en-us/global-infrastructure/services/?products=virtual-machines
+
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index a1141352c..3e13ceecd 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -18,6 +18,20 @@ and ``providers`` sections::
   providers:
     ...
 
+The following drivers are available.
+
+.. toctree::
+   :maxdepth: 1
+
+   aws
+   azure
+   gce
+   kubernetes
+   openshift
+   openshift-pods
+   openstack
+   static
+
 The following sections are available.  All are required unless
 otherwise indicated.
 
@@ -437,2115 +451,46 @@ Options
 
          For details on the extra options required and provided by the
          AWS driver, see the separate section
-         :attr:`providers.[aws]`
-
-      .. value:: gce
-
-         For details on the extra options required and provided by the
-         GCE driver, see the separate section
-         :attr:`providers.[gce]`
-
-      .. value:: kubernetes
-
-         For details on the extra options required and provided by the
-         kubernetes driver, see the separate section
-         :attr:`providers.[kubernetes]`
-
-      .. value:: openshift
-
-         For details on the extra options required and provided by the
-         openshift driver, see the separate section
-         :attr:`providers.[openshift]`
-
-      .. value:: openshiftpods
-
-         For details on the extra options required and provided by the
-         openshiftpods driver, see the separate section
-         :attr:`providers.[openshiftpods]`
-
-      .. value:: openstack
-
-         For details on the extra options required and provided by the
-         OpenStack driver, see the separate section
-         :attr:`providers.[openstack]`
-
-      .. value:: static
-
-         For details on the extra options required and provided by the
-         static driver, see the separate section
-         :attr:`providers.[static]`
+         :ref:`aws-driver`
 
       .. value:: azure
 
          For details on the extra options required and provided by the
          Azure driver, see the separate section
-         :attr:`providers.[azure]`
+         :ref:`azure-driver`
 
+      .. value:: gce
 
-OpenStack Driver
-----------------
+         For details on the extra options required and provided by the
+         GCE driver, see the separate section
+         :ref:`gce-driver`
 
-Selecting the OpenStack driver adds the following options to the
-:attr:`providers` section of the configuration.
+      .. value:: kubernetes
 
-.. attr-overview::
-   :prefix: providers.[openstack]
-   :maxdepth: 3
+         For details on the extra options required and provided by the
+         kubernetes driver, see the separate section
+         :ref:`kubernetes-driver`
 
-.. attr:: providers.[openstack]
+      .. value:: openshift
 
-   Specifying the ``openstack`` driver for a provider adds the
-   following keys to the :attr:`providers` configuration.
+         For details on the extra options required and provided by the
+         openshift driver, see the separate section
+         :ref:`openshift-driver`
 
-   .. note:: For documentation purposes the option names are prefixed
-             ``providers.[openstack]`` to disambiguate from other
-             drivers, but ``[openstack]`` is not required in the
-             configuration (e.g. below ``providers.[openstack].cloud``
-             refers to the ``cloud`` key in the ``providers`` section
-             when the ``openstack`` driver is selected).
+      .. value:: openshiftpods
 
-   An OpenStack provider's resources are partitioned into groups
-   called "pools" (see :attr:`providers.[openstack].pools` for details),
-   and within a pool, the node types which are to be made available
-   are listed (see :attr:`providers.[openstack].pools.labels` for
-   details).
+         For details on the extra options required and provided by the
+         openshiftpods driver, see the separate section
+         :ref:`openshift-pods-driver`
 
-   Within each OpenStack provider the available Nodepool image types
-   are defined (see :attr:`providers.[openstack].diskimages`).
+      .. value:: openstack
 
-   .. code-block:: yaml
+         For details on the extra options required and provided by the
+         OpenStack driver, see the separate section
+         :ref:`openstack-driver`
 
-      providers:
-        - name: provider1
-          driver: openstack
-          cloud: example
-          region-name: 'region1'
-          rate: 1.0
-          boot-timeout: 120
-          launch-timeout: 900
-          launch-retries: 3
-          image-name-format: '{image_name}-{timestamp}'
-          hostname-format: '{label.name}-{provider.name}-{node.id}'
-          post-upload-hook: /usr/bin/custom-hook
-          diskimages:
-            - name: trusty
-              meta:
-                  key: value
-                  key2: value
-            - name: precise
-            - name: devstack-trusty
-          pools:
-            - name: main
-              max-servers: 96
-              availability-zones:
-                - az1
-              networks:
-                - some-network-name
-              security-groups:
-                - zuul-security-group
-              labels:
-                - name: trusty
-                  min-ram: 8192
-                  diskimage: trusty
-                  console-log: True
-                - name: precise
-                  min-ram: 8192
-                  diskimage: precise
-                - name: devstack-trusty
-                  min-ram: 8192
-                  diskimage: devstack-trusty
-        - name: provider2
-          driver: openstack
-          cloud: example2
-          region-name: 'region1'
-          rate: 1.0
-          image-name-format: '{image_name}-{timestamp}'
-          hostname-format: '{label.name}-{provider.name}-{node.id}'
-          diskimages:
-            - name: precise
-              meta:
-                  key: value
-                  key2: value
-          pools:
-            - name: main
-              max-servers: 96
-              labels:
-                - name: trusty
-                  min-ram: 8192
-                  diskimage: trusty
-                - name: precise
-                  min-ram: 8192
-                  diskimage: precise
-                - name: devstack-trusty
-                  min-ram: 8192
-                  diskimage: devstack-trusty
+      .. value:: static
 
-   .. attr:: cloud
-      :type: string
-      :required:
-
-      Name of a cloud configured in ``clouds.yaml``.
-
-      The instances spawned by nodepool will inherit the default
-      security group of the project specified in the cloud definition
-      in `clouds.yaml` (if other values not specified). This means
-      that when working with Zuul, for example, SSH traffic (TCP/22)
-      must be allowed in the project's default security group for Zuul
-      to be able to reach instances.
-
-      More information about the contents of `clouds.yaml` can be
-      found in `the openstacksdk documentation
-      <https://docs.openstack.org/openstacksdk/>`_.
-
-   .. attr:: boot-timeout
-      :type: int seconds
-      :default: 60
-
-      Once an instance is active, how long to try connecting to the
-      image via SSH.  If the timeout is exceeded, the node launch is
-      aborted and the instance deleted.
-
-   .. attr:: launch-timeout
-      :type: int seconds
-      :default: 3600
-
-      The time to wait from issuing the command to create a new instance
-      until that instance is reported as "active".  If the timeout is
-      exceeded, the node launch is aborted and the instance deleted.
-
-   .. attr:: nodepool-id
-      :type: string
-      :default: None
-
-      *Deprecated*
-
-      A unique string to identify which nodepool instances is using a
-      provider.  This is useful if you want to configure production
-      and development instances of nodepool but share the same
-      provider.
-
-  .. attr:: launch-retries
-     :type: int
-     :default: 3
-
-      The number of times to retry launching a server before
-      considering the job failed.
-
-  .. attr:: region-name
-     :type: string
-
-     The region name if the provider cloud has multiple regions.
-
-  .. attr:: hostname-format
-     :type: string
-     :default: {label.name}-{provider.name}-{node.id}
-
-     Hostname template to use for the spawned instance.
-
-  .. attr:: image-name-format
-     :type: string
-     :default: {image_name}-{timestamp}
-
-     Format for image names that are uploaded to providers.
-
-  .. attr:: post-upload-hook
-     :type: string
-     :default: None
-
-     Filename of an optional script that can be called after an image has
-     been uploaded to a provider but before it is taken into use. This is
-     useful to perform last minute validation tests before an image is
-     really used for build nodes. The script will be called as follows:
-
-     ``<SCRIPT> <PROVIDER> <EXTERNAL_IMAGE_ID> <LOCAL_IMAGE_FILENAME>``
-
-     If the script returns with result code 0 it is treated as successful
-     otherwise it is treated as failed and the image gets deleted.
-
-  .. attr:: rate
-     :type: int seconds
-     :default: 1
-
-     In seconds, amount to wait between operations on the provider.
-
-  .. attr:: clean-floating-ips
-     :type: bool
-     :default: True
-
-     If it is set to True, nodepool will assume it is the only user of
-     the OpenStack project and will attempt to clean unattached
-     floating ips that may have leaked around restarts.
-
-  .. attr:: port-cleanup-interval
-     :type: int seconds
-     :default: 600
-
-     If greater than 0, nodepool will assume it is the only user of the
-     OpenStack project and will attempt to clean ports in `DOWN` state after
-     the cleanup interval has elapsed. This value can be reduced if the
-     instance spawn time on the provider is reliably quicker.
-
-  .. attr:: diskimages
-     :type: list
-
-     Each entry in a provider's `diskimages` section must correspond
-     to an entry in :attr:`diskimages`.  Such an entry indicates that
-     the corresponding diskimage should be uploaded for use in this
-     provider.  Additionally, any nodes that are created using the
-     uploaded image will have the associated attributes (such as
-     flavor or metadata).
-
-     If an image is removed from this section, any previously uploaded
-     images will be deleted from the provider.
-
-     .. code-block:: yaml
-
-        diskimages:
-          - name: precise
-            pause: False
-            meta:
-                key: value
-                key2: value
-          - name: windows
-            connection-type: winrm
-            connection-port: 5986
-
-     Each entry is a dictionary with the following keys
-
-     .. attr:: name
-        :type: string
-        :required:
-
-        Identifier to refer this image from
-        :attr:`providers.[openstack].pools.labels` and
-        :attr:`diskimages` sections.
-
-     .. attr:: pause
-        :type: bool
-        :default: False
-
-        When set to True, nodepool-builder will not upload the image
-        to the provider.
-
-     .. attr:: config-drive
-        :type: bool
-        :default: unset
-
-        Whether config drive should be used for the image. Defaults to
-        unset which will use the cloud's default behavior.
-
-     .. attr:: meta
-        :type: dict
-
-        Arbitrary key/value metadata to store for this server using
-        the Nova metadata service. A maximum of five entries is
-        allowed, and both keys and values must be 255 characters or
-        less.
-
-     .. attr:: connection-type
-        :type: string
-
-        The connection type that a consumer should use when connecting
-        to the node. For most diskimages this is not
-        necessary. However when creating Windows images this could be
-        ``winrm`` to enable access via ansible.
-
-     .. attr:: connection-port
-        :type: int
-        :default: 22 / 5986
-
-        The port that a consumer should use when connecting to the
-        node. For most diskimages this is not necessary. This defaults
-        to 22 for ssh and 5986 for winrm.
-
-  .. attr:: cloud-images
-     :type: list
-
-     Each entry in this section must refer to an entry in the
-     :attr:`labels` section.
-
-     .. code-block:: yaml
-
-        cloud-images:
-          - name: trusty-external
-            config-drive: False
-          - name: windows-external
-            connection-type: winrm
-            connection-port: 5986
-
-     Each entry is a dictionary with the following keys
-
-     .. attr:: name
-        :type: string
-        :required:
-
-        Identifier to refer this cloud-image from :attr:`labels`
-        section.  Since this name appears elsewhere in the nodepool
-        configuration file, you may want to use your own descriptive
-        name here and use one of ``image-id`` or ``image-name`` to
-        specify the cloud image so that if the image name or id
-        changes on the cloud, the impact to your Nodepool
-        configuration will be minimal.  However, if neither of those
-        attributes are provided, this is also assumed to be the image
-        name or ID in the cloud.
-
-     .. attr:: config-drive
-        :type: bool
-        :default: unset
-
-        Whether config drive should be used for the cloud
-        image. Defaults to unset which will use the cloud's default
-        behavior.
-
-     .. attr:: image-id
-        :type: str
-
-        If this is provided, it is used to select the image from the
-        cloud provider by ID, rather than name.  Mutually exclusive
-        with :attr:`providers.[openstack].cloud-images.image-name`
-
-     .. attr:: image-name
-        :type: str
-
-        If this is provided, it is used to select the image from the
-        cloud provider by this name or ID.  Mutually exclusive with
-        :attr:`providers.[openstack].cloud-images.image-id`
-
-     .. attr:: username
-        :type: str
-
-        The username that a consumer should use when connecting to the
-        node.
-
-     .. attr:: python-path
-        :type: str
-        :default: auto
-
-        The path of the default python interpreter.  Used by Zuul to set
-        ``ansible_python_interpreter``.  The special value ``auto`` will
-        direct Zuul to use inbuilt Ansible logic to select the
-        interpreter on Ansible >=2.8, and default to
-        ``/usr/bin/python2`` for earlier versions.
-
-     .. attr:: connection-type
-        :type: str
-
-        The connection type that a consumer should use when connecting
-        to the node. For most diskimages this is not
-        necessary. However when creating Windows images this could be
-        'winrm' to enable access via ansible.
-
-     .. attr:: connection-port
-        :type: int
-        :default: 22/ 5986
-
-        The port that a consumer should use when connecting to the
-        node. For most diskimages this is not necessary. This defaults
-        to 22 for ssh and 5986 for winrm.
-
-  .. attr:: pools
-     :type: list
-
-     A pool defines a group of resources from an OpenStack
-     provider. Each pool has a maximum number of nodes which can be
-     launched from it, along with a number of cloud-related attributes
-     used when launching nodes.
-
-     .. code-block:: yaml
-
-        pools:
-          - name: main
-            max-servers: 96
-            availability-zones:
-              - az1
-            networks:
-              - some-network-name
-            security-groups:
-              - zuul-security-group
-            auto-floating-ip: False
-            host-key-checking: True
-            node-attributes:
-              key1: value1
-              key2: value2
-            labels:
-              - name: trusty
-                min-ram: 8192
-                diskimage: trusty
-                console-log: True
-              - name: precise
-                min-ram: 8192
-                diskimage: precise
-              - name: devstack-trusty
-                min-ram: 8192
-                diskimage: devstack-trusty
-
-     Each entry is a dictionary with the following keys
-
-     .. attr:: name
-        :type: string
-        :required:
-
-        Pool name
-
-     .. attr:: node-attributes
-        :type: dict
-
-        A dictionary of key-value pairs that will be stored with the node data
-        in ZooKeeper. The keys and values can be any arbitrary string.
-
-     .. attr:: max-cores
-        :type: int
-
-        Maximum number of cores usable from this pool. This can be used
-        to limit usage of the tenant. If not defined nodepool can use
-        all cores up to the quota of the tenant.
-
-     .. attr:: max-servers
-        :type: int
-
-        Maximum number of servers spawnable from this pool. This can
-        be used to limit the number of servers. If not defined
-        nodepool can create as many servers the tenant allows.
-
-     .. attr:: max-ram
-        :type: int
-
-        Maximum ram usable from this pool. This can be used to limit
-        the amount of ram allocated by nodepool. If not defined
-        nodepool can use as much ram as the tenant allows.
-
-     .. attr:: ignore-provider-quota
-        :type: bool
-        :default: False
-
-        Ignore the provider quota for this pool. Instead, only check
-        against the configured max values for this pool and the
-        current usage based on stored data. This may be useful in
-        circumstances where the provider is incorrectly calculating
-        quota.
-
-     .. attr:: availability-zones
-        :type: list
-
-        A list of availability zones to use.
-
-        If this setting is omitted, nodepool will fetch the list of
-        all availability zones from nova.  To restrict nodepool to a
-        subset of availability zones, supply a list of availability
-        zone names in this setting.
-
-        Nodepool chooses an availability zone from the list at random
-        when creating nodes but ensures that all nodes for a given
-        request are placed in the same availability zone.
-
-     .. attr:: networks
-        :type: list
-
-        Specify custom Neutron networks that get attached to each
-        node. Specify the name or id of the network as a string.
-
-     .. attr:: security-groups
-        :type: list
-
-        Specify custom Neutron security groups that get attached to
-        each node. Specify the name or id of the security_group as a
-        string.
-
-     .. attr:: auto-floating-ip
-        :type: bool
-        :default: True
-
-        Specify custom behavior of allocating floating ip for each
-        node.  When set to False, ``nodepool-launcher`` will not apply
-        floating ip for nodes. When zuul instances and nodes are
-        deployed in the same internal private network, set the option
-        to False to save floating ip for cloud provider.
-
-     .. attr:: host-key-checking
-        :type: bool
-        :default: True
-
-        Specify custom behavior of validation of SSH host keys.  When
-        set to False, nodepool-launcher will not ssh-keyscan nodes
-        after they are booted. This might be needed if
-        nodepool-launcher and the nodes it launches are on different
-        networks.  The default value is True.
-
-     .. attr:: labels
-        :type: list
-
-        Each entry in a pool`s `labels` section indicates that the
-        corresponding label is available for use in this pool.  When
-        creating nodes for a label, the flavor-related attributes in that
-        label's section will be used.
-
-        .. code-block:: yaml
-
-           labels:
-             - name: precise
-               min-ram: 8192
-               flavor-name: 'something to match'
-               console-log: True
-             - name: trusty
-               min-ram: 8192
-               networks:
-                 - public
-                 - private
-
-        Each entry is a dictionary with the following keys
-
-        .. attr:: name
-           :type: str
-           :required:
-
-           Identifier to refer this image; from :attr:`labels` and
-           :attr:`diskimages` sections.
-
-        .. attr:: diskimage
-           :type: str
-           :required:
-
-           Refers to provider's diskimages, see
-           :attr:`providers.[openstack].diskimages`.  Mutually exclusive
-           with :attr:`providers.[openstack].pools.labels.cloud-image`
-
-        .. attr:: cloud-image
-           :type: str
-           :required:
-
-           Refers to the name of an externally managed image in the
-           cloud that already exists on the provider. The value of
-           ``cloud-image`` should match the ``name`` of a previously
-           configured entry from the ``cloud-images`` section of the
-           provider. See :attr:`providers.[openstack].cloud-images`.
-           Mutually exclusive with
-           :attr:`providers.[openstack].pools.labels.diskimage`
-
-        .. attr:: flavor-name
-           :type: str
-
-           Name or id of the flavor to use. If
-           :attr:`providers.[openstack].pools.labels.min-ram` is
-           omitted, it must be an exact match. If
-           :attr:`providers.[openstack].pools.labels.min-ram` is given,
-           ``flavor-name`` will be used to find flavor names that meet
-           :attr:`providers.[openstack].pools.labels.min-ram` and also
-           contain ``flavor-name``.
-
-           One of :attr:`providers.[openstack].pools.labels.min-ram` or
-           :attr:`providers.[openstack].pools.labels.flavor-name` must
-           be specified.
-
-        .. attr:: min-ram
-           :type: int
-
-           Determine the flavor to use (e.g. ``m1.medium``,
-           ``m1.large``, etc).  The smallest flavor that meets the
-           ``min-ram`` requirements will be chosen.
-
-           One of :attr:`providers.[openstack].pools.labels.min-ram` or
-           :attr:`providers.[openstack].pools.labels.flavor-name` must
-           be specified.
-
-        .. attr:: boot-from-volume
-           :type: bool
-           :default: False
-
-            If given, the label for use in this pool will create a
-            volume from the image and boot the node from it.
-
-        .. attr:: host-key-checking
-           :type: bool
-           :default: True
-
-           Specify custom behavior of validation of SSH host keys.  When set to
-           False, nodepool-launcher will not ssh-keyscan nodes after they are
-           booted. This might be needed if nodepool-launcher and the nodes it
-           launches are on different networks.  The default value is True.
-
-           .. note:: This value will override the value for
-                     :attr:`providers.[openstack].pools.host-key-checking`.
-
-        .. attr:: networks
-           :type: list
-
-           Specify custom Neutron networks that get attached to each
-           node. Specify the name or id of the network as a string.
-
-           .. note:: This value will override the value for
-                     :attr:`providers.[openstack].pools.networks`.
-
-        .. attr:: key-name
-           :type: string
-
-           If given, is the name of a keypair that will be used when
-           booting each server.
-
-        .. attr:: console-log
-           :type: bool
-           :default: False
-
-           On the failure of the ssh ready check, download the server
-           console log to aid in debugging the problem.
-
-        .. attr:: volume-size
-           :type: int gigabytes
-           :default: 50
-
-           When booting an image from volume, how big should the
-           created volume be.
-
-        .. attr:: instance-properties
-           :type: dict
-           :default: None
-
-           A dictionary of key/value properties to set when booting
-           each server.  These properties become available via the
-           ``meta-data`` on the active server (e.g. within
-           ``config-drive:openstack/latest/meta_data.json``)
-
-        .. attr:: userdata
-           :type: str
-           :default: None
-
-           A string of userdata for a node. Example usage is to install
-           cloud-init package on image which will apply the userdata.
-           Additional info about options in cloud-config:
-           https://cloudinit.readthedocs.io/en/latest/topics/examples.html
-
-
-Static Driver
--------------
-
-Selecting the static driver adds the following options to the
-:attr:`providers` section of the configuration.
-
-.. attr-overview::
-   :prefix: providers.[static]
-   :maxdepth: 3
-
-.. attr:: providers.[static]
-   :type: list
-
-   The static provider driver is used to define static nodes.
-
-   .. note:: For documentation purposes the option names are prefixed
-             ``providers.[static]`` to disambiguate from other
-             drivers, but ``[static]`` is not required in the
-             configuration (e.g. below ``providers.[static].pools``
-             refers to the ``pools`` key in the ``providers`` section
-             when the ``static`` driver is selected).
-
-   Example:
-
-   .. code-block:: yaml
-
-      providers:
-        - name: static-rack
-          driver: static
-          pools:
-            - name: main
-              nodes:
-                - name: trusty.example.com
-                  labels: trusty-static
-                  timeout: 13
-                  connection-port: 22022
-                  host-key: fake-key
-                  username: zuul
-                  max-parallel-jobs: 1
-
-   .. attr:: pools
-      :type: list
-
-      A pool defines a group of statically declared nodes.
-
-      .. note::
-
-         When providing different labels, it is better to have one pool per
-         label to avoid requests being queued when one label is at capacity.
-
-      Each entry is a dictionary with entries as follows
-
-      .. attr:: name
-         :type: str
-         :required:
-
-         Pool name
-
-      .. attr:: node-attributes
-         :type: dict
-
-         A dictionary of key-value pairs that will be stored with the node data
-         in ZooKeeper. The keys and values can be any arbitrary string.
-
-      .. attr:: nodes
-         :type: list
-         :required:
-
-         Each entry indicates a static node and it's attributes.
-
-         .. attr:: name
-            :type: str
-            :required:
-
-            The hostname or ip address of the static node. This must be
-            unique across all nodes defined within the configuration file.
-
-         .. attr:: labels
-            :type: list
-            :required:
-
-            The list of labels associated with the node.
-
-         .. attr:: host-key-checking
-             :type: bool
-             :default: True
-
-             Specify custom behavior of validation of host connection.
-             When set to False, nodepool-launcher will not scan the nodes
-             before they are registered. This might be needed if
-             nodepool-launcher and the static nodes are on isolated
-             networks. The default value is True.
-
-         .. attr:: timeout
-            :type: int
-            :default: 5
-
-            The timeout in second before the ssh ping is considered failed.
-
-         .. attr:: connection-type
-            :type: string
-            :default: ssh
-
-            The connection type that a consumer should use when connecting
-            to the node.
-
-            .. value:: winrm
-
-            .. value:: ssh
-
-         .. attr:: connection-port
-            :type: int
-            :default: 22 / 5986
-
-            The port that a consumer should use when connecting to the node.
-            For most nodes this is not necessary. This defaults to 22 when
-            ``connection-type`` is 'ssh' and 5986 when it is 'winrm'.
-
-         .. attr:: host-key
-            :type: str
-
-            The ssh host key of the node.
-
-         .. attr:: username
-            :type: str
-            :default: zuul
-
-            The username nodepool will use to validate it can connect to the
-            node.
-
-         .. attr:: python-path
-            :type: str
-            :default: /usr/bin/python2
-
-            The path of the default python interpreter.  Used by Zuul to set
-            ``ansible_python_interpreter``.  The special value ``auto`` will
-            direct Zuul to use inbuilt Ansible logic to select the
-            interpreter on Ansible >=2.8, and default to
-            ``/usr/bin/python2`` for earlier versions.
-
-         .. attr:: max-parallel-jobs
-            :type: int
-            :default: 1
-
-            The number of jobs that can run in parallel on this node.
-
-
-Kubernetes Driver
------------------
-
-Selecting the kubernetes driver adds the following options to the
-:attr:`providers` section of the configuration.
-
-.. attr-overview::
-   :prefix: providers.[kubernetes]
-   :maxdepth: 3
-
-.. attr:: providers.[kubernetes]
-   :type: list
-
-   A Kubernetes provider's resources are partitioned into groups
-   called `pools` (see :attr:`providers.[kubernetes].pools` for
-   details), and within a pool, the node types which are to be made
-   available are listed (see :attr:`providers.[kubernetes].pools.labels` for
-   details).
-
-   .. note:: For documentation purposes the option names are prefixed
-             ``providers.[kubernetes]`` to disambiguate from other
-             drivers, but ``[kubernetes]`` is not required in the
-             configuration (e.g. below
-             ``providers.[kubernetes].pools`` refers to the ``pools``
-             key in the ``providers`` section when the ``kubernetes``
-             driver is selected).
-
-   Example:
-
-   .. code-block:: yaml
-
-     providers:
-       - name: kubespray
-         driver: kubernetes
-         context: admin-cluster.local
-         pools:
-           - name: main
-             labels:
-               - name: kubernetes-namespace
-                 type: namespace
-               - name: pod-fedora
-                 type: pod
-                 image: docker.io/fedora:28
-
-
-   .. attr:: context
-
-      Name of the context configured in ``kube/config``.
-
-      Before using the driver, Nodepool either needs a ``kube/config``
-      file installed with a cluster admin context, in which case this
-      setting is required, or if Nodepool is running inside
-      Kubernetes, this setting and the ``kube/config`` file may be
-      omitted and Nodepool will use a service account loaded from the
-      in-cluster configuration path.
-
-   .. attr:: launch-retries
-      :default: 3
-
-      The number of times to retry launching a node before considering
-      the job failed.
-
-
-   .. attr:: pools
-      :type: list
-
-      A pool defines a group of resources from a Kubernetes
-      provider.
-
-      .. attr:: name
-         :required:
-
-         Namespaces are prefixed with the pool's name.
-
-      .. attr:: node-attributes
-         :type: dict
-
-         A dictionary of key-value pairs that will be stored with the node data
-         in ZooKeeper. The keys and values can be any arbitrary string.
-
-      .. attr:: labels
-         :type: list
-
-         Each entry in a pool`s `labels` section indicates that the
-         corresponding label is available for use in this pool.
-
-         Each entry is a dictionary with the following keys
-
-         .. attr:: name
-            :required:
-
-            Identifier for this label; references an entry in the
-            :attr:`labels` section.
-
-         .. attr:: type
-
-            The Kubernetes provider supports two types of labels:
-
-            .. value:: namespace
-
-               Namespace labels provide an empty namespace configured
-               with a service account that can create pods, services,
-               configmaps, etc.
-
-            .. value:: pod
-
-               Pod labels provide a dedicated namespace with a single pod
-               created using the
-               :attr:`providers.[kubernetes].pools.labels.image` parameter and it
-               is configured with a service account that can exec and get
-               the logs of the pod.
-
-         .. attr:: image
-
-            Only used by the
-            :value:`providers.[kubernetes].pools.labels.type.pod` label type;
-            specifies the image name used by the pod.
-
-         .. attr:: python-path
-            :type: str
-            :default: auto
-
-           The path of the default python interpreter.  Used by Zuul to set
-           ``ansible_python_interpreter``.  The special value ``auto`` will
-           direct Zuul to use inbuilt Ansible logic to select the
-           interpreter on Ansible >=2.8, and default to
-           ``/usr/bin/python2`` for earlier versions.
-
-         .. attr:: cpu
-            :type: int
-
-            Only used by the
-            :value:`providers.[kubernetes].pools.labels.type.pod` label type;
-            specifies the number of cpu to request for the pod.
-
-         .. attr:: memory
-            :type: int
-
-            Only used by the
-            :value:`providers.[kubernetes].pools.labels.type.pod` label type;
-            specifies the amount of memory in MB to request for the pod.
-
-         .. attr:: env
-            :type: list
-            :default: []
-
-            Only used by the
-            :value:`providers.[kubernetes].pools.labels.type.pod` label type;
-            A list of environment variables to pass to the Pod.
-
-            .. attr:: name
-               :type: str
-               :required:
-
-               The name of the environment variable passed to the Pod.
-
-            .. attr:: value
-               :type: str
-               :required:
-
-               The value of the environment variable passed to the Pod.
-
-         .. attr:: node-selector
-            :type: dict
-
-            Only used by the
-            :value:`providers.[kubernetes].pools.labels.type.pod` label type;
-            A map of key-value pairs to ensure the Kubernetes scheduler
-            places the Pod on a node with specific node labels.
-
-
-Openshift Driver
-----------------
-
-Selecting the openshift driver adds the following options to the
-:attr:`providers` section of the configuration.
-
-.. attr-overview::
-   :prefix: providers.[openshift]
-   :maxdepth: 3
-
-.. attr:: providers.[openshift]
-   :type: list
-
-   An Openshift provider's resources are partitioned into groups called `pool`
-   (see :attr:`providers.[openshift].pools` for details), and within a pool,
-   the node types which are to be made available are listed
-   (see :attr:`providers.[openshift].labels` for details).
-
-   .. note:: For documentation purposes the option names are prefixed
-             ``providers.[openshift]`` to disambiguate from other
-             drivers, but ``[openshift]`` is not required in the
-             configuration (e.g. below
-             ``providers.[openshift].pools`` refers to the ``pools``
-             key in the ``providers`` section when the ``openshift``
-             driver is selected).
-
-   Example:
-
-   .. code-block:: yaml
-
-     providers:
-       - name: cluster
-         driver: openshift
-         context: context-name
-         pools:
-           - name: main
-             labels:
-               - name: openshift-project
-                 type: project
-               - name: openshift-pod
-                 type: pod
-                 image: docker.io/fedora:28
-
-   .. attr:: context
-      :required:
-
-      Name of the context configured in ``kube/config``.
-
-      Before using the driver, Nodepool services need a ``kube/config`` file
-      manually installed with self-provisioner (the service account needs to
-      be able to create projects) context.
-      Make sure the context is present in ``oc config get-contexts`` command
-      output.
-
-   .. attr:: launch-retries
-      :default: 3
-
-      The number of times to retry launching a node before considering
-      the job failed.
-
-   .. attr:: max-projects
-      :default: infinite
-      :type: int
-
-      Maximum number of projects that can be used.
-
-   .. attr:: pools
-      :type: list
-
-      A pool defines a group of resources from an Openshift provider.
-
-      .. attr:: name
-         :required:
-
-         Project's name are prefixed with the pool's name.
-
-      .. attr:: node-attributes
-         :type: dict
-
-         A dictionary of key-value pairs that will be stored with the node data
-         in ZooKeeper. The keys and values can be any arbitrary string.
-
-   .. attr:: labels
-      :type: list
-
-      Each entry in a pool`s `labels` section indicates that the
-      corresponding label is available for use in this pool.
-
-      Each entry is a dictionary with the following keys
-
-      .. attr:: name
-         :required:
-
-         Identifier for this label; references an entry in the
-         :attr:`labels` section.
-
-      .. attr:: type
-
-         The Openshift provider supports two types of labels:
-
-         .. value:: project
-
-            Project labels provide an empty project configured
-            with a service account that can create pods, services,
-            configmaps, etc.
-
-         .. value:: pod
-
-            Pod labels provide a new dedicated project with a single
-            pod created using the
-            :attr:`providers.[openshift].labels.image` parameter and it
-            is configured with a service account that can exec and get
-            the logs of the pod.
-
-      .. attr:: image
-
-         Only used by the
-         :value:`providers.[openshift].labels.type.pod` label type;
-         specifies the image name used by the pod.
-
-      .. attr:: image-pull
-         :default: IfNotPresent
-         :type: str
-
-         The ImagePullPolicy, can be IfNotPresent, Always or Never.
-
-      .. attr:: python-path
-         :type: str
-         :default: auto
-
-          The path of the default python interpreter.  Used by Zuul to set
-          ``ansible_python_interpreter``.  The special value ``auto`` will
-          direct Zuul to use inbuilt Ansible logic to select the
-          interpreter on Ansible >=2.8, and default to
-          ``/usr/bin/python2`` for earlier versions.
-
-      .. attr:: cpu
-         :type: int
-
-         Only used by the
-         :value:`providers.[openshift].labels.type.pod` label type;
-         specifies the number of cpu to request for the pod.
-
-      .. attr:: memory
-         :type: int
-
-         Only used by the
-         :value:`providers.[openshift].labels.type.pod` label type;
-         specifies the amount of memory in MB to request for the pod.
-
-      .. attr:: env
-         :type: list
-         :default: []
-
-         Only used by the
-         :value:`providers.[openshift].labels.type.pod` label type;
-         A list of environment variables to pass to the Pod.
-
-         .. attr:: name
-            :type: str
-            :required:
-
-            The name of the environment variable passed to the Pod.
-
-         .. attr:: value
-            :type: str
-            :required:
-
-            The value of the environment variable passed to the Pod.
-
-      .. attr:: node-selector
-         :type: dict
-
-         Only used by the
-         :value:`providers.[openshift].labels.type.pod` label type;
-         A map of key-value pairs to ensure the OpenShift scheduler
-         places the Pod on a node with specific node labels.
-
-
-Openshift Pods Driver
----------------------
-
-Selecting the openshift pods driver adds the following options to the
-:attr:`providers` section of the configuration.
-
-.. attr:: providers.[openshiftpods]
-   :type: list
-
-   The Openshift Pods driver is similar to the Openshift driver, but it
-   only support pod label to be created in a single project. This enable
-   using an unprivileged service account that doesn't requires the
-   self-provisioner role.
-
-   Example:
-
-   .. code-block:: yaml
-
-     providers:
-       - name: cluster
-         driver: openshiftpods
-         context: unprivileged-context-name
-         pools:
-           - name: main
-             labels:
-               - name: openshift-pod
-                 image: docker.io/fedora:28
-
-   .. attr:: context
-      :required:
-
-      Name of the context configured in ``kube/config``.
-
-      Before using the driver, Nodepool services need a ``kube/config`` file
-      manually installed with self-provisioner (the service account needs to
-      be able to create projects) context.
-      Make sure the context is present in ``oc config get-contexts`` command
-      output.
-
-   .. attr:: launch-retries
-      :default: 3
-
-      The number of times to retry launching a pod before considering
-      the job failed.
-
-   .. attr:: max-pods
-      :default: infinite
-      :type: int
-
-      Maximum number of pods that can be used.
-
-   .. attr:: pools
-      :type: list
-
-      A pool defines a group of resources from an Openshift provider.
-
-      .. attr:: name
-         :required:
-
-         The project's name that will be used to create the pods.
-
-      .. attr:: node-attributes
-         :type: dict
-
-         A dictionary of key-value pairs that will be stored with the node data
-         in ZooKeeper. The keys and values can be any arbitrary string.
-
-   .. attr:: labels
-      :type: list
-
-      Each entry in a pool`s `labels` section indicates that the
-      corresponding label is available for use in this pool.
-
-      Each entry is a dictionary with the following keys
-
-      .. attr:: name
-         :required:
-
-         Identifier for this label; references an entry in the
-         :attr:`labels` section.
-
-      .. attr:: image
-
-         The image name.
-
-      .. attr:: image-pull
-         :default: IfNotPresent
-         :type: str
-
-         The ImagePullPolicy, can be IfNotPresent, Always or Never.
-
-      .. attr:: cpu
-         :type: int
-
-         The number of cpu to request for the pod.
-
-      .. attr:: memory
-         :type: int
-
-         The amount of memory in MB to request for the pod.
-
-      .. attr:: python-path
-         :type: str
-         :default: auto
-
-        The path of the default python interpreter.  Used by Zuul to set
-        ``ansible_python_interpreter``.  The special value ``auto`` will
-        direct Zuul to use inbuilt Ansible logic to select the
-        interpreter on Ansible >=2.8, and default to
-        ``/usr/bin/python2`` for earlier versions.
-
-      .. attr:: env
-         :type: list
-         :default: []
-
-         A list of environment variables to pass to the Pod.
-
-         .. attr:: name
-            :type: str
-            :required:
-
-            The name of the environment variable passed to the Pod.
-
-         .. attr:: value
-            :type: str
-            :required:
-
-            The value of the environment variable passed to the Pod.
-
-      .. attr:: node-selector
-         :type: dict
-
-         A map of key-value pairs to ensure the OpenShift scheduler
-         places the Pod on a node with specific node labels.
-
-
-AWS EC2 Driver
---------------
-
-Selecting the aws driver adds the following options to the :attr:`providers`
-section of the configuration.
-
-.. attr-overview::
-   :prefix: providers.[aws]
-   :maxdepth: 3
-
-.. attr:: providers.[aws]
-   :type: list
-
-   An AWS provider's resources are partitioned into groups called `pool`
-   (see :attr:`providers.[aws].pools` for details), and within a pool,
-   the node types which are to be made available are listed
-   (see :attr:`providers.[aws].pools.labels` for details).
-
-   See `Boto Configuration`_ for information on how to configure credentials
-   and other settings for AWS access in Nodepool's runtime environment.
-
-   .. note:: For documentation purposes the option names are prefixed
-             ``providers.[aws]`` to disambiguate from other
-             drivers, but ``[aws]`` is not required in the
-             configuration (e.g. below
-             ``providers.[aws].pools`` refers to the ``pools``
-             key in the ``providers`` section when the ``aws``
-             driver is selected).
-
-   Example:
-
-   .. code-block:: yaml
-
-     providers:
-       - name: ec2-us-west-2
-         driver: aws
-         region-name: us-west-2
-         cloud-images:
-           - name: debian9
-             image-id: ami-09c308526d9534717
-             username: admin
-         pools:
-           - name: main
-             max-servers: 5
-             subnet-id: subnet-0123456789abcdef0
-             security-group-id: sg-01234567890abcdef
-             labels:
-               - name: debian9
-                 cloud-image: debian9
-                 instance-type: t3.medium
-                 iam-instance-profile:
-                   arn: arn:aws:iam::123456789012:instance-profile/s3-read-only
-                 key-name: zuul
-                 tags:
-                   key1: value1
-               - name: debian9-large
-                 cloud-image: debian9
-                 instance-type: t3.large
-                 key-name: zuul
-                 tags:
-                   key1: value1
-                   key2: value2
-
-   .. attr:: name
-      :required:
-
-      A unique name for this provider configuration.
-
-   .. attr:: region-name
-      :required:
-
-      Name of the `AWS region`_ to interact with.
-
-   .. attr:: profile-name
-
-      The AWS credentials profile to load for this provider. If unspecified the
-      `boto3` library will select a profile.
-
-      See `Boto Configuration`_ for more information.
-
-   .. attr:: boot-timeout
-      :type: int seconds
-      :default: 60
-
-      Once an instance is active, how long to try connecting to the
-      image via SSH.  If the timeout is exceeded, the node launch is
-      aborted and the instance deleted.
-
-   .. attr:: launch-retries
-      :default: 3
-
-      The number of times to retry launching a node before considering
-      the job failed.
-
-   .. attr:: cloud-images
-      :type: list
-
-      Each entry in this section must refer to an entry in the
-      :attr:`labels` section.
-
-      .. code-block:: yaml
-
-         cloud-images:
-           - name: ubuntu1804
-             image-id: ami-082fd9a18128c9e8c
-             username: ubuntu
-           - name: ubuntu1804-by-filters
-             image-filters:
-               - name: name
-                 values:
-                  - named-ami
-             username: ubuntu
-           - name: my-custom-win2k3
-             connection-type: winrm
-             username: admin
-
-      Each entry is a dictionary with the following keys
-
-      .. attr:: name
-         :type: string
-         :required:
-
-         Identifier to refer this cloud-image from :attr:`providers.[aws].pools.labels` section.
-         Since this name appears elsewhere in the nodepool configuration file,
-         you may want to use your own descriptive name here and use
-         ``image-id`` to specify the cloud image so that if
-         the image id changes on the cloud, the impact to your Nodepool
-         configuration will be minimal. However, if ``image-id`` is not
-         provided, this is assumed to be the image id in the cloud.
-
-      .. attr:: image-id
-         :type: str
-
-         If this is provided, it is used to select the image from the cloud
-         provider by ID.
-
-      .. attr:: image-filters
-         :type: list
-
-         If provided, this is used to select an AMI by filters.  If the filters
-         provided match more than one image, the most recent will be returned.
-         `image-filters` are not valid if `image-id` is also specified.
-
-         Each entry is a dictionary with the following keys
-
-         .. attr:: name
-            :type: str
-            :required:
-
-            The filter name. See `Boto describe images`_ for a list of valid filters.
-
-         .. attr:: values
-            :type: list
-            :required:
-
-            A list of str values to filter on
-
-      .. attr:: username
-         :type: str
-
-         The username that a consumer should use when connecting to the node.
-
-      .. attr:: python-path
-         :type: str
-         :default: auto
-
-         The path of the default python interpreter.  Used by Zuul to set
-         ``ansible_python_interpreter``.  The special value ``auto`` will
-         direct Zuul to use inbuilt Ansible logic to select the
-         interpreter on Ansible >=2.8, and default to
-         ``/usr/bin/python2`` for earlier versions.
-
-      .. attr:: connection-type
-         :type: str
-
-         The connection type that a consumer should use when connecting to the
-         node. For most images this is not necessary. However when creating
-         Windows images this could be 'winrm' to enable access via ansible.
-
-      .. attr:: connection-port
-         :type: int
-         :default: 22/ 5986
-
-         The port that a consumer should use when connecting to the node. For
-         most diskimages this is not necessary. This defaults to 22 for ssh and
-         5986 for winrm.
-
-   .. attr:: pools
-      :type: list
-
-      A pool defines a group of resources from an AWS provider. Each pool has a
-      maximum number of nodes which can be launched from it, along with a number
-      of cloud-related attributes used when launching nodes.
-
-      .. attr:: name
-         :required:
-
-         A unique name within the provider for this pool of resources.
-
-      .. attr:: node-attributes
-         :type: dict
-
-         A dictionary of key-value pairs that will be stored with the node data
-         in ZooKeeper. The keys and values can be any arbitrary string.
-
-      .. attr:: subnet-id
-
-         If provided, specifies the subnet to assign to the primary network
-         interface of nodes.
-
-      .. attr:: security-group-id
-
-         If provided, specifies the security group ID to assign to the primary
-         network interface of nodes.
-
-      .. attr:: public-ip-address
-         :type: bool
-         :default: True
-
-         Specify if a public ip address shall be attached to nodes.
-
-      .. attr:: host-key-checking
-         :type: bool
-         :default: True
-
-         Specify custom behavior of validation of SSH host keys.  When set to
-         False, nodepool-launcher will not ssh-keyscan nodes after they are
-         booted. This might be needed if nodepool-launcher and the nodes it
-         launches are on different networks.  The default value is True.
-
-      .. attr:: labels
-         :type: list
-
-         Each entry in a pool's `labels` section indicates that the
-         corresponding label is available for use in this pool.  When creating
-         nodes for a label, the flavor-related attributes in that label's
-         section will be used.
-
-         .. code-block:: yaml
-
-            labels:
-              - name: bionic
-                instance-type: m5a.large
-
-         Each entry is a dictionary with the following keys
-
-           .. attr:: name
-              :type: str
-              :required:
-
-              Identifier to refer this label.
-              Nodepool will use this to set the name of the instance unless
-              the name is specified as a tag.
-
-           .. attr:: cloud-image
-              :type: str
-              :required:
-
-              Refers to the name of an externally managed image in the
-              cloud that already exists on the provider. The value of
-              ``cloud-image`` should match the ``name`` of a previously
-              configured entry from the ``cloud-images`` section of the
-              provider. See :attr:`providers.[aws].cloud-images`.
-
-           .. attr:: ebs-optimized
-              :type: bool
-              :default: False
-
-              Indicates whether EBS optimization
-              (additional, dedicated throughput between Amazon EC2 and Amazon EBS,)
-              has been enabled for the instance.
-
-           .. attr:: instance-type
-              :type: str
-              :required:
-
-              Name of the flavor to use.
-
-           .. attr:: iam-instance-profile
-              :type: dict
-
-              Used to attach an iam instance profile.
-              Useful for giving access to services without needing any secrets.
-
-              .. attr:: name
-
-                 Name of the instance profile.
-                 Mutually exclusive with :attr:`providers.[aws].pools.labels.iam-instance-profile.arn`
-
-              .. attr:: arn
-
-                 ARN identifier of the profile.
-                 Mutually exclusive with :attr:`providers.[aws].pools.labels.iam-instance-profile.name`
-
-           .. attr:: key-name
-              :type: string
-              :required:
-
-              The name of a keypair that will be used when
-              booting each server.
-
-           .. attr:: volume-type
-              :type: string
-
-              If given, the root `EBS volume type`_
-
-           .. attr:: volume-size
-              :type: int
-
-              If given, the size of the root EBS volume, in GiB.
-
-           .. attr:: userdata
-              :type: str
-              :default: None
-
-              A string of userdata for a node. Example usage is to install
-              cloud-init package on image which will apply the userdata.
-              Additional info about options in cloud-config:
-              https://cloudinit.readthedocs.io/en/latest/topics/examples.html
-
-           .. attr:: tags
-              :type: dict
-              :default: None
-
-              A dictionary of tags to add to the EC2 instances
-
-.. _`EBS volume type`: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html
-.. _`AWS region`: https://docs.aws.amazon.com/general/latest/gr/rande.html
-.. _`Boto configuration`: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html
-.. _`Boto describe images`: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.describe_images
-
-.. _gce_driver:
-
-Google Cloud Compute Engine (GCE) Driver
-----------------------------------------
-
-Selecting the gce driver adds the following options to the :attr:`providers`
-section of the configuration.
-
-.. attr-overview::
-   :prefix: providers.[gce]
-   :maxdepth: 3
-
-.. attr:: providers.[gce]
-   :type: list
-
-   An GCE provider's resources are partitioned into groups called `pool`
-   (see :attr:`providers.[gce].pools` for details), and within a pool,
-   the node types which are to be made available are listed
-   (see :attr:`providers.[gce].pools.labels` for details).
-
-   See `Application Default Credentials`_ for information on how to
-   configure credentials and other settings for GCE access in
-   Nodepool's runtime environment.
-
-   .. note:: For documentation purposes the option names are prefixed
-             ``providers.[gce]`` to disambiguate from other
-             drivers, but ``[gce]`` is not required in the
-             configuration (e.g. below
-             ``providers.[gce].pools`` refers to the ``pools``
-             key in the ``providers`` section when the ``gce``
-             driver is selected).
-
-   Example:
-
-   .. code-block:: yaml
-
-      - name: gce-uscentral1
-        driver: gce
-        project: nodepool-123456
-        region: us-central1
-        zone: us-central1-a
-        cloud-images:
-          - name: debian-stretch
-            image-project: debian-cloud
-            image-family: debian-9
-            username: zuul
-            key: ssh-rsa ...
-        pools:
-          - name: main
-            max-servers: 8
-            labels:
-              - name: debian-stretch
-                instance-type: f1-micro
-                cloud-image: debian-stretch
-                volume-type: standard
-                volume-size: 10
-
-   .. attr:: name
-      :required:
-
-      A unique name for this provider configuration.
-
-   .. attr:: region
-      :required:
-
-      Name of the region to use; see `GCE regions and zones`_.
-
-   .. attr:: zone
-      :required:
-
-      Name of the zone to use; see `GCE regions and zones`_.
-
-   .. attr:: boot-timeout
-      :type: int seconds
-      :default: 60
-
-      Once an instance is active, how long to try connecting to the
-      image via SSH.  If the timeout is exceeded, the node launch is
-      aborted and the instance deleted.
-
-   .. attr:: launch-retries
-      :default: 3
-
-      The number of times to retry launching a node before considering
-      the job failed.
-
-   .. attr:: cloud-images
-      :type: list
-
-      Each entry in this section must refer to an entry in the
-      :attr:`labels` section.
-
-      .. code-block:: yaml
-
-         cloud-images:
-           - name: debian-stretch
-             image-project: debian-cloud
-             image-family: debian-9
-             username: zuul
-             key: ssh-rsa ...
-
-      Each entry is a dictionary with the following keys:
-
-      .. attr:: name
-         :type: string
-         :required:
-
-         Identifier to refer this cloud-image from
-         :attr:`providers.[gce].pools.labels` section.
-
-      .. attr:: image-id
-         :type: str
-
-         If this is provided, it is used to select the image from the cloud
-         provider by ID.
-
-      .. attr:: image-project
-         :type: str
-
-         If :attr:`providers.[gce].cloud-images.image-id` is not
-         provided, this is used along with
-         :attr:`providers.[gce].cloud-images.image-family` to find an
-         image.
-
-      .. attr:: image-family
-         :type: str
-
-         If :attr:`providers.[gce].cloud-images.image-id` is not
-         provided, this is used along with
-         :attr:`providers.[gce].cloud-images.image-project` to find an
-         image.
-
-      .. attr:: username
-         :type: str
-
-         The username that a consumer should use when connecting to the node.
-
-      .. attr:: key
-         :type: str
-
-         An SSH public key to add to the instance (project global keys
-         are added automatically).
-
-      .. attr:: python-path
-         :type: str
-         :default: auto
-
-         The path of the default python interpreter.  Used by Zuul to set
-         ``ansible_python_interpreter``.  The special value ``auto`` will
-         direct Zuul to use inbuilt Ansible logic to select the
-         interpreter on Ansible >=2.8, and default to
-         ``/usr/bin/python2`` for earlier versions.
-
-      .. attr:: connection-type
-         :type: str
-
-         The connection type that a consumer should use when connecting to the
-         node. For most images this is not necessary. However when creating
-         Windows images this could be 'winrm' to enable access via ansible.
-
-      .. attr:: connection-port
-         :type: int
-         :default: 22/ 5986
-
-         The port that a consumer should use when connecting to the node. For
-         most diskimages this is not necessary. This defaults to 22 for ssh and
-         5986 for winrm.
-
-   .. attr:: pools
-      :type: list
-
-      A pool defines a group of resources from an GCE provider. Each pool has a
-      maximum number of nodes which can be launched from it, along with a number
-      of cloud-related attributes used when launching nodes.
-
-      .. attr:: name
-         :required:
-
-         A unique name within the provider for this pool of resources.
-
-      .. attr:: node-attributes
-         :type: dict
-
-         A dictionary of key-value pairs that will be stored with the node data
-         in ZooKeeper. The keys and values can be any arbitrary string.
-
-      .. attr:: host-key-checking
-         :type: bool
-         :default: True
-
-         Specify custom behavior of validation of SSH host keys.  When set to
-         False, nodepool-launcher will not ssh-keyscan nodes after they are
-         booted. This might be needed if nodepool-launcher and the nodes it
-         launches are on different networks.  The default value is True.
-
-      .. attr:: use-internal-ip
-         :default: False
-
-         Whether to access the instance with the internal or external IP
-         address.
-
-      .. attr:: labels
-         :type: list
-
-         Each entry in a pool's `labels` section indicates that the
-         corresponding label is available for use in this pool.  When creating
-         nodes for a label, the flavor-related attributes in that label's
-         section will be used.
-
-         .. code-block:: yaml
-
-            labels:
-              - name: debian
-                instance-type: f1-micro
-                cloud-image: debian-stretch
-
-         Each entry is a dictionary with the following keys
-
-           .. attr:: name
-              :type: str
-              :required:
-
-              Identifier to refer this label.
-
-           .. attr:: cloud-image
-              :type: str
-              :required:
-
-              Refers to the name of an externally managed image in the
-              cloud that already exists on the provider. The value of
-              ``cloud-image`` should match the ``name`` of a previously
-              configured entry from the ``cloud-images`` section of the
-              provider. See :attr:`providers.[gce].cloud-images`.
-
-           .. attr:: instance-type
-              :type: str
-              :required:
-
-              Name of the flavor to use.  See `GCE machine types`_.
-
-           .. attr:: volume-type
-              :type: string
-
-              If given, the root volume type (``pd-standard`` or
-              ``pd-ssd``).
-
-           .. attr:: volume-size
-              :type: int
-
-              If given, the size of the root volume, in GiB.
-
-
-.. _`Application Default Credentials`: https://cloud.google.com/docs/authentication/production
-.. _`GCE regions and zones`: https://cloud.google.com/compute/docs/regions-zones/
-.. _`GCE machine types`: https://cloud.google.com/compute/docs/machine-types
-
-Azure Compute Driver
---------------------
-
-Selecting the azure driver adds the following options to the :attr:`providers`
-section of the configuration.
-
-.. attr-overview::
-   :prefix: providers.[azure]
-   :maxdepth: 3
-
-.. attr:: providers.[azure]
-   :type: list
-
-   An Azure provider's resources are partitioned into groups called `pool`,
-   and within a pool, the node types which are to be made available are listed
-
-
-   .. note:: For documentation purposes the option names are prefixed
-             ``providers.[azure]`` to disambiguate from other
-             drivers, but ``[azure]`` is not required in the
-             configuration (e.g. below
-             ``providers.[azure].pools`` refers to the ``pools``
-             key in the ``providers`` section when the ``azure``
-             driver is selected).
-
-   Example:
-
-   .. code-block:: yaml
-
-     providers:
-        - name: azure-central-us
-          driver: azure
-          zuul-public-key: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAA...
-          resource-group-location: centralus
-          location: centralus
-          resource-group: ZuulCIDev
-          auth-path: /Users/grhayes/.azure/nodepoolCreds.json
-          subnet-id: /subscriptions/<subscription-id>/resourceGroups/ZuulCI/providers/Microsoft.Network/virtualNetworks/NodePool/subnets/default
-          cloud-images:
-            - name: bionic
-              username: zuul
-              image-reference:
-                sku: 18.04-LTS
-                publisher: Canonical
-                version: latest
-                offer: UbuntuServer
-          pools:
-            - name: main
-              max-servers: 10
-              labels:
-                - name: bionic
-                  cloud-image: bionic
-                  hardware-profile:
-                    vm-size: Standard_D1_v2
-                  tags:
-                    department: R&D
-                    purpose: CI/CD
-
-   .. attr:: name
-      :required:
-
-      A unique name for this provider configuration.
-
-   .. attr:: location
-      :required:
-
-      Name of the Azure region to interact with.
-
-   .. attr:: resource-group-location
-      :required:
-
-      Name of the Azure region to where the home Resource Group is or should be created.
-
-   .. attr:: auth-path
-      :required:
-
-      Path to the JSON file containing the service principal credentials.
-      Create with the `Azure CLI`_ and the ``--sdk-auth`` flag
-
-   .. attr:: subnet-id
-      :required:
-
-      Subnet to create VMs on
-
-  .. attr:: cloud-images
-     :type: list
-
-     Each entry in this section must refer to an entry in the
-     :attr:`labels` section.
-
-     .. code-block:: yaml
-
-        cloud-images:
-          - name: bionic
-            username: zuul
-            image-reference:
-              sku: 18.04-LTS
-              publisher: Canonical
-              version: latest
-              offer: UbuntuServer
-          - name: windows-server-2016
-            username: zuul
-            image-reference:
-               sku: 2016-Datacenter
-               publisher: MicrosoftWindowsServer
-               version: latest
-               offer: WindowsServer
-
-
-     Each entry is a dictionary with the following keys
-
-     .. attr:: name
-        :type: string
-        :required:
-
-        Identifier to refer this cloud-image from :attr:`labels`
-        section.  Since this name appears elsewhere in the nodepool
-        configuration file, you may want to use your own descriptive
-        name here.
-
-     .. attr:: username
-        :type: str
-
-        The username that a consumer should use when connecting to the
-        node.
-
-     .. attr:: image-reference
-        :type: dict
-        :required:
-
-        .. attr:: sku
-           :type: str
-           :required:
-
-           Image SKU
-
-        .. attr:: publisher
-           :type: str
-           :required:
-
-           Image Publisher
-
-        .. attr:: offer
-           :type: str
-           :required:
-
-           Image offers
-
-        .. attr:: version
-           :type: str
-           :required:
-
-           Image version
-
-
-  .. attr:: pools
-      :type: list
-
-      A pool defines a group of resources from an Azure provider. Each pool has a
-      maximum number of nodes which can be launched from it, along with a number
-      of cloud-related attributes used when launching nodes.
-
-      .. attr:: name
-         :required:
-
-         A unique name within the provider for this pool of resources.
-
-      .. attr:: labels
-         :type: list
-
-         Each entry in a pool's `labels` section indicates that the
-         corresponding label is available for use in this pool.  When creating
-         nodes for a label, the flavor-related attributes in that label's
-         section will be used.
-
-         .. code-block:: yaml
-
-            labels:
-              - name: bionic
-                cloud-image: bionic
-                hardware-profile:
-                  vm-size: Standard_D1_v2
-
-         Each entry is a dictionary with the following keys
-
-           .. attr:: name
-              :type: str
-              :required:
-
-              Identifier to refer this label.
-
-           .. attr:: cloud-image
-             :type: str
-             :required:
-
-             Refers to the name of an externally managed image in the
-             cloud that already exists on the provider. The value of
-             ``cloud-image`` should match the ``name`` of a previously
-             configured entry from the ``cloud-images`` section of the
-             provider.
-
-           .. attr:: hardware-profile
-             :required:
-
-             .. attr:: vm-size
-                :required:
-                :type: str
-
-                VM Size of the VMs to use in Azure. See the VM size list on `azure.microsoft.com`_
-                for the list of sizes availabile in each region.
-
-
-.. _`Azure CLI`: https://docs.microsoft.com/en-us/cli/azure/create-an-azure-service-principal-azure-cli?view=azure-cli-latest
-
-.. _azure.microsoft.com: https://azure.microsoft.com/en-us/global-infrastructure/services/?products=virtual-machines
+         For details on the extra options required and provided by the
+         static driver, see the separate section
+         :ref:`static-driver`
diff --git a/doc/source/gce.rst b/doc/source/gce.rst
new file mode 100644
index 000000000..8bdbd758d
--- /dev/null
+++ b/doc/source/gce.rst
@@ -0,0 +1,259 @@
+.. _gce-driver:
+
+.. default-domain:: zuul
+
+Google Cloud Compute Engine (GCE) Driver
+----------------------------------------
+
+Selecting the gce driver adds the following options to the :attr:`providers`
+section of the configuration.
+
+.. attr-overview::
+   :prefix: providers.[gce]
+   :maxdepth: 3
+
+.. attr:: providers.[gce]
+   :type: list
+
+   A GCE provider's resources are partitioned into groups called `pool`
+   (see :attr:`providers.[gce].pools` for details), and within a pool,
+   the node types which are to be made available are listed
+   (see :attr:`providers.[gce].pools.labels` for details).
+
+   See `Application Default Credentials`_ for information on how to
+   configure credentials and other settings for GCE access in
+   Nodepool's runtime environment.
+
+   .. note:: For documentation purposes the option names are prefixed
+             ``providers.[gce]`` to disambiguate from other
+             drivers, but ``[gce]`` is not required in the
+             configuration (e.g. below
+             ``providers.[gce].pools`` refers to the ``pools``
+             key in the ``providers`` section when the ``gce``
+             driver is selected).
+
+   Example:
+
+   .. code-block:: yaml
+
+      - name: gce-uscentral1
+        driver: gce
+        project: nodepool-123456
+        region: us-central1
+        zone: us-central1-a
+        cloud-images:
+          - name: debian-stretch
+            image-project: debian-cloud
+            image-family: debian-9
+            username: zuul
+            key: ssh-rsa ...
+        pools:
+          - name: main
+            max-servers: 8
+            labels:
+              - name: debian-stretch
+                instance-type: f1-micro
+                cloud-image: debian-stretch
+                volume-type: standard
+                volume-size: 10
+
+   .. attr:: name
+      :required:
+
+      A unique name for this provider configuration.
+
+   .. attr:: region
+      :required:
+
+      Name of the region to use; see `GCE regions and zones`_.
+
+   .. attr:: zone
+      :required:
+
+      Name of the zone to use; see `GCE regions and zones`_.
+
+   .. attr:: boot-timeout
+      :type: int seconds
+      :default: 60
+
+      Once an instance is active, how long to try connecting to the
+      image via SSH.  If the timeout is exceeded, the node launch is
+      aborted and the instance deleted.
+
+   .. attr:: launch-retries
+      :default: 3
+
+      The number of times to retry launching a node before considering
+      the job failed.
+
+   .. attr:: cloud-images
+      :type: list
+
+      Each entry in this section must refer to an entry in the
+      :attr:`labels` section.
+
+      .. code-block:: yaml
+
+         cloud-images:
+           - name: debian-stretch
+             image-project: debian-cloud
+             image-family: debian-9
+             username: zuul
+             key: ssh-rsa ...
+
+      Each entry is a dictionary with the following keys:
+
+      .. attr:: name
+         :type: string
+         :required:
+
+         Identifier to refer this cloud-image from
+         :attr:`providers.[gce].pools.labels` section.
+
+      .. attr:: image-id
+         :type: str
+
+         If this is provided, it is used to select the image from the cloud
+         provider by ID.
+
+      .. attr:: image-project
+         :type: str
+
+         If :attr:`providers.[gce].cloud-images.image-id` is not
+         provided, this is used along with
+         :attr:`providers.[gce].cloud-images.image-family` to find an
+         image.
+
+      .. attr:: image-family
+         :type: str
+
+         If :attr:`providers.[gce].cloud-images.image-id` is not
+         provided, this is used along with
+         :attr:`providers.[gce].cloud-images.image-project` to find an
+         image.
+
+      .. attr:: username
+         :type: str
+
+         The username that a consumer should use when connecting to the node.
+
+      .. attr:: key
+         :type: str
+
+         An SSH public key to add to the instance (project global keys
+         are added automatically).
+
+      .. attr:: python-path
+         :type: str
+         :default: auto
+
+         The path of the default python interpreter.  Used by Zuul to set
+         ``ansible_python_interpreter``.  The special value ``auto`` will
+         direct Zuul to use inbuilt Ansible logic to select the
+         interpreter on Ansible >=2.8, and default to
+         ``/usr/bin/python2`` for earlier versions.
+
+      .. attr:: connection-type
+         :type: str
+
+         The connection type that a consumer should use when connecting to the
+         node. For most images this is not necessary. However when creating
+         Windows images this could be 'winrm' to enable access via ansible.
+
+      .. attr:: connection-port
+         :type: int
+         :default: 22/ 5986
+
+         The port that a consumer should use when connecting to the node. For
+         most diskimages this is not necessary. This defaults to 22 for ssh and
+         5986 for winrm.
+
+   .. attr:: pools
+      :type: list
+
+      A pool defines a group of resources from an GCE provider. Each pool has a
+      maximum number of nodes which can be launched from it, along with a number
+      of cloud-related attributes used when launching nodes.
+
+      .. attr:: name
+         :required:
+
+         A unique name within the provider for this pool of resources.
+
+      .. attr:: node-attributes
+         :type: dict
+
+         A dictionary of key-value pairs that will be stored with the node data
+         in ZooKeeper. The keys and values can be any arbitrary string.
+
+      .. attr:: host-key-checking
+         :type: bool
+         :default: True
+
+         Specify custom behavior of validation of SSH host keys.  When set to
+         False, nodepool-launcher will not ssh-keyscan nodes after they are
+         booted. This might be needed if nodepool-launcher and the nodes it
+         launches are on different networks.  The default value is True.
+
+      .. attr:: use-internal-ip
+         :default: False
+
+         Whether to access the instance with the internal or external IP
+         address.
+
+      .. attr:: labels
+         :type: list
+
+         Each entry in a pool's `labels` section indicates that the
+         corresponding label is available for use in this pool.  When creating
+         nodes for a label, the flavor-related attributes in that label's
+         section will be used.
+
+         .. code-block:: yaml
+
+            labels:
+              - name: debian
+                instance-type: f1-micro
+                cloud-image: debian-stretch
+
+         Each entry is a dictionary with the following keys
+
+           .. attr:: name
+              :type: str
+              :required:
+
+              Identifier to refer this label.
+
+           .. attr:: cloud-image
+              :type: str
+              :required:
+
+              Refers to the name of an externally managed image in the
+              cloud that already exists on the provider. The value of
+              ``cloud-image`` should match the ``name`` of a previously
+              configured entry from the ``cloud-images`` section of the
+              provider. See :attr:`providers.[gce].cloud-images`.
+
+           .. attr:: instance-type
+              :type: str
+              :required:
+
+              Name of the flavor to use.  See `GCE machine types`_.
+
+           .. attr:: volume-type
+              :type: string
+
+              If given, the root volume type (``pd-standard`` or
+              ``pd-ssd``).
+
+           .. attr:: volume-size
+              :type: int
+
+              If given, the size of the root volume, in GiB.
+
+
+.. _`Application Default Credentials`: https://cloud.google.com/docs/authentication/production
+.. _`GCE regions and zones`: https://cloud.google.com/compute/docs/regions-zones/
+.. _`GCE machine types`: https://cloud.google.com/compute/docs/machine-types
+
+
diff --git a/doc/source/kubernetes.rst b/doc/source/kubernetes.rst
new file mode 100644
index 000000000..6dd585262
--- /dev/null
+++ b/doc/source/kubernetes.rst
@@ -0,0 +1,174 @@
+.. _kubernetes-driver:
+
+.. default-domain:: zuul
+
+Kubernetes Driver
+-----------------
+
+Selecting the kubernetes driver adds the following options to the
+:attr:`providers` section of the configuration.
+
+.. attr-overview::
+   :prefix: providers.[kubernetes]
+   :maxdepth: 3
+
+.. attr:: providers.[kubernetes]
+   :type: list
+
+   A Kubernetes provider's resources are partitioned into groups
+   called `pools` (see :attr:`providers.[kubernetes].pools` for
+   details), and within a pool, the node types which are to be made
+   available are listed (see :attr:`providers.[kubernetes].pools.labels` for
+   details).
+
+   .. note:: For documentation purposes the option names are prefixed
+             ``providers.[kubernetes]`` to disambiguate from other
+             drivers, but ``[kubernetes]`` is not required in the
+             configuration (e.g. below
+             ``providers.[kubernetes].pools`` refers to the ``pools``
+             key in the ``providers`` section when the ``kubernetes``
+             driver is selected).
+
+   Example:
+
+   .. code-block:: yaml
+
+     providers:
+       - name: kubespray
+         driver: kubernetes
+         context: admin-cluster.local
+         pools:
+           - name: main
+             labels:
+               - name: kubernetes-namespace
+                 type: namespace
+               - name: pod-fedora
+                 type: pod
+                 image: docker.io/fedora:28
+
+
+   .. attr:: context
+
+      Name of the context configured in ``kube/config``.
+
+      Before using the driver, Nodepool either needs a ``kube/config``
+      file installed with a cluster admin context, in which case this
+      setting is required, or if Nodepool is running inside
+      Kubernetes, this setting and the ``kube/config`` file may be
+      omitted and Nodepool will use a service account loaded from the
+      in-cluster configuration path.
+
+   .. attr:: launch-retries
+      :default: 3
+
+      The number of times to retry launching a node before considering
+      the job failed.
+
+
+   .. attr:: pools
+      :type: list
+
+      A pool defines a group of resources from a Kubernetes
+      provider.
+
+      .. attr:: name
+         :required:
+
+         Namespaces are prefixed with the pool's name.
+
+      .. attr:: node-attributes
+         :type: dict
+
+         A dictionary of key-value pairs that will be stored with the node data
+         in ZooKeeper. The keys and values can be any arbitrary string.
+
+      .. attr:: labels
+         :type: list
+
+         Each entry in a pool`s `labels` section indicates that the
+         corresponding label is available for use in this pool.
+
+         Each entry is a dictionary with the following keys
+
+         .. attr:: name
+            :required:
+
+            Identifier for this label; references an entry in the
+            :attr:`labels` section.
+
+         .. attr:: type
+
+            The Kubernetes provider supports two types of labels:
+
+            .. value:: namespace
+
+               Namespace labels provide an empty namespace configured
+               with a service account that can create pods, services,
+               configmaps, etc.
+
+            .. value:: pod
+
+               Pod labels provide a dedicated namespace with a single pod
+               created using the
+               :attr:`providers.[kubernetes].pools.labels.image` parameter and it
+               is configured with a service account that can exec and get
+               the logs of the pod.
+
+         .. attr:: image
+
+            Only used by the
+            :value:`providers.[kubernetes].pools.labels.type.pod` label type;
+            specifies the image name used by the pod.
+
+         .. attr:: python-path
+            :type: str
+            :default: auto
+
+           The path of the default python interpreter.  Used by Zuul to set
+           ``ansible_python_interpreter``.  The special value ``auto`` will
+           direct Zuul to use inbuilt Ansible logic to select the
+           interpreter on Ansible >=2.8, and default to
+           ``/usr/bin/python2`` for earlier versions.
+
+         .. attr:: cpu
+            :type: int
+
+            Only used by the
+            :value:`providers.[kubernetes].pools.labels.type.pod` label type;
+            specifies the number of cpu to request for the pod.
+
+         .. attr:: memory
+            :type: int
+
+            Only used by the
+            :value:`providers.[kubernetes].pools.labels.type.pod` label type;
+            specifies the amount of memory in MB to request for the pod.
+
+         .. attr:: env
+            :type: list
+            :default: []
+
+            Only used by the
+            :value:`providers.[kubernetes].pools.labels.type.pod` label type;
+            A list of environment variables to pass to the Pod.
+
+            .. attr:: name
+               :type: str
+               :required:
+
+               The name of the environment variable passed to the Pod.
+
+            .. attr:: value
+               :type: str
+               :required:
+
+               The value of the environment variable passed to the Pod.
+
+         .. attr:: node-selector
+            :type: dict
+
+            Only used by the
+            :value:`providers.[kubernetes].pools.labels.type.pod` label type;
+            A map of key-value pairs to ensure the Kubernetes scheduler
+            places the Pod on a node with specific node labels.
+
diff --git a/doc/source/openshift-pods.rst b/doc/source/openshift-pods.rst
new file mode 100644
index 000000000..4fbf5c72d
--- /dev/null
+++ b/doc/source/openshift-pods.rst
@@ -0,0 +1,140 @@
+.. _openshift-pods-driver:
+
+.. default-domain:: zuul
+
+Openshift Pods Driver
+---------------------
+
+Selecting the openshift pods driver adds the following options to the
+:attr:`providers` section of the configuration.
+
+.. attr:: providers.[openshiftpods]
+   :type: list
+
+   The Openshift Pods driver is similar to the Openshift driver, but it
+   only support pod label to be created in a single project. This enable
+   using an unprivileged service account that doesn't requires the
+   self-provisioner role.
+
+   Example:
+
+   .. code-block:: yaml
+
+     providers:
+       - name: cluster
+         driver: openshiftpods
+         context: unprivileged-context-name
+         pools:
+           - name: main
+             labels:
+               - name: openshift-pod
+                 image: docker.io/fedora:28
+
+   .. attr:: context
+      :required:
+
+      Name of the context configured in ``kube/config``.
+
+      Before using the driver, Nodepool services need a ``kube/config`` file
+      manually installed with self-provisioner (the service account needs to
+      be able to create projects) context.
+      Make sure the context is present in ``oc config get-contexts`` command
+      output.
+
+   .. attr:: launch-retries
+      :default: 3
+
+      The number of times to retry launching a pod before considering
+      the job failed.
+
+   .. attr:: max-pods
+      :default: infinite
+      :type: int
+
+      Maximum number of pods that can be used.
+
+   .. attr:: pools
+      :type: list
+
+      A pool defines a group of resources from an Openshift provider.
+
+      .. attr:: name
+         :required:
+
+         The project's name that will be used to create the pods.
+
+      .. attr:: node-attributes
+         :type: dict
+
+         A dictionary of key-value pairs that will be stored with the node data
+         in ZooKeeper. The keys and values can be any arbitrary string.
+
+   .. attr:: labels
+      :type: list
+
+      Each entry in a pool`s `labels` section indicates that the
+      corresponding label is available for use in this pool.
+
+      Each entry is a dictionary with the following keys
+
+      .. attr:: name
+         :required:
+
+         Identifier for this label; references an entry in the
+         :attr:`labels` section.
+
+      .. attr:: image
+
+         The image name.
+
+      .. attr:: image-pull
+         :default: IfNotPresent
+         :type: str
+
+         The ImagePullPolicy, can be IfNotPresent, Always or Never.
+
+      .. attr:: cpu
+         :type: int
+
+         The number of cpu to request for the pod.
+
+      .. attr:: memory
+         :type: int
+
+         The amount of memory in MB to request for the pod.
+
+      .. attr:: python-path
+         :type: str
+         :default: auto
+
+        The path of the default python interpreter.  Used by Zuul to set
+        ``ansible_python_interpreter``.  The special value ``auto`` will
+        direct Zuul to use inbuilt Ansible logic to select the
+        interpreter on Ansible >=2.8, and default to
+        ``/usr/bin/python2`` for earlier versions.
+
+      .. attr:: env
+         :type: list
+         :default: []
+
+         A list of environment variables to pass to the Pod.
+
+         .. attr:: name
+            :type: str
+            :required:
+
+            The name of the environment variable passed to the Pod.
+
+         .. attr:: value
+            :type: str
+            :required:
+
+            The value of the environment variable passed to the Pod.
+
+      .. attr:: node-selector
+         :type: dict
+
+         A map of key-value pairs to ensure the OpenShift scheduler
+         places the Pod on a node with specific node labels.
+
+
diff --git a/doc/source/openshift.rst b/doc/source/openshift.rst
new file mode 100644
index 000000000..28e5bf651
--- /dev/null
+++ b/doc/source/openshift.rst
@@ -0,0 +1,181 @@
+.. _openshift-driver:
+
+.. default-domain:: zuul
+
+Openshift Driver
+----------------
+
+Selecting the openshift driver adds the following options to the
+:attr:`providers` section of the configuration.
+
+.. attr-overview::
+   :prefix: providers.[openshift]
+   :maxdepth: 3
+
+.. attr:: providers.[openshift]
+   :type: list
+
+   An Openshift provider's resources are partitioned into groups called `pool`
+   (see :attr:`providers.[openshift].pools` for details), and within a pool,
+   the node types which are to be made available are listed
+   (see :attr:`providers.[openshift].labels` for details).
+
+   .. note:: For documentation purposes the option names are prefixed
+             ``providers.[openshift]`` to disambiguate from other
+             drivers, but ``[openshift]`` is not required in the
+             configuration (e.g. below
+             ``providers.[openshift].pools`` refers to the ``pools``
+             key in the ``providers`` section when the ``openshift``
+             driver is selected).
+
+   Example:
+
+   .. code-block:: yaml
+
+     providers:
+       - name: cluster
+         driver: openshift
+         context: context-name
+         pools:
+           - name: main
+             labels:
+               - name: openshift-project
+                 type: project
+               - name: openshift-pod
+                 type: pod
+                 image: docker.io/fedora:28
+
+   .. attr:: context
+      :required:
+
+      Name of the context configured in ``kube/config``.
+
+      Before using the driver, Nodepool services need a ``kube/config`` file
+      manually installed with self-provisioner (the service account needs to
+      be able to create projects) context.
+      Make sure the context is present in ``oc config get-contexts`` command
+      output.
+
+   .. attr:: launch-retries
+      :default: 3
+
+      The number of times to retry launching a node before considering
+      the job failed.
+
+   .. attr:: max-projects
+      :default: infinite
+      :type: int
+
+      Maximum number of projects that can be used.
+
+   .. attr:: pools
+      :type: list
+
+      A pool defines a group of resources from an Openshift provider.
+
+      .. attr:: name
+         :required:
+
+         Project's name are prefixed with the pool's name.
+
+      .. attr:: node-attributes
+         :type: dict
+
+         A dictionary of key-value pairs that will be stored with the node data
+         in ZooKeeper. The keys and values can be any arbitrary string.
+
+   .. attr:: labels
+      :type: list
+
+      Each entry in a pool`s `labels` section indicates that the
+      corresponding label is available for use in this pool.
+
+      Each entry is a dictionary with the following keys
+
+      .. attr:: name
+         :required:
+
+         Identifier for this label; references an entry in the
+         :attr:`labels` section.
+
+      .. attr:: type
+
+         The Openshift provider supports two types of labels:
+
+         .. value:: project
+
+            Project labels provide an empty project configured
+            with a service account that can create pods, services,
+            configmaps, etc.
+
+         .. value:: pod
+
+            Pod labels provide a new dedicated project with a single
+            pod created using the
+            :attr:`providers.[openshift].labels.image` parameter and it
+            is configured with a service account that can exec and get
+            the logs of the pod.
+
+      .. attr:: image
+
+         Only used by the
+         :value:`providers.[openshift].labels.type.pod` label type;
+         specifies the image name used by the pod.
+
+      .. attr:: image-pull
+         :default: IfNotPresent
+         :type: str
+
+         The ImagePullPolicy, can be IfNotPresent, Always or Never.
+
+      .. attr:: python-path
+         :type: str
+         :default: auto
+
+          The path of the default python interpreter.  Used by Zuul to set
+          ``ansible_python_interpreter``.  The special value ``auto`` will
+          direct Zuul to use inbuilt Ansible logic to select the
+          interpreter on Ansible >=2.8, and default to
+          ``/usr/bin/python2`` for earlier versions.
+
+      .. attr:: cpu
+         :type: int
+
+         Only used by the
+         :value:`providers.[openshift].labels.type.pod` label type;
+         specifies the number of cpu to request for the pod.
+
+      .. attr:: memory
+         :type: int
+
+         Only used by the
+         :value:`providers.[openshift].labels.type.pod` label type;
+         specifies the amount of memory in MB to request for the pod.
+
+      .. attr:: env
+         :type: list
+         :default: []
+
+         Only used by the
+         :value:`providers.[openshift].labels.type.pod` label type;
+         A list of environment variables to pass to the Pod.
+
+         .. attr:: name
+            :type: str
+            :required:
+
+            The name of the environment variable passed to the Pod.
+
+         .. attr:: value
+            :type: str
+            :required:
+
+            The value of the environment variable passed to the Pod.
+
+      .. attr:: node-selector
+         :type: dict
+
+         Only used by the
+         :value:`providers.[openshift].labels.type.pod` label type;
+         A map of key-value pairs to ensure the OpenShift scheduler
+         places the Pod on a node with specific node labels.
diff --git a/doc/source/openstack.rst b/doc/source/openstack.rst
new file mode 100644
index 000000000..e4cc984b8
--- /dev/null
+++ b/doc/source/openstack.rst
@@ -0,0 +1,635 @@
+.. _openstack-driver:
+
+.. default-domain:: zuul
+
+OpenStack Driver
+----------------
+
+Selecting the OpenStack driver adds the following options to the
+:attr:`providers` section of the configuration.
+
+.. attr-overview::
+   :prefix: providers.[openstack]
+   :maxdepth: 3
+
+.. attr:: providers.[openstack]
+
+   Specifying the ``openstack`` driver for a provider adds the
+   following keys to the :attr:`providers` configuration.
+
+   .. note:: For documentation purposes the option names are prefixed
+             ``providers.[openstack]`` to disambiguate from other
+             drivers, but ``[openstack]`` is not required in the
+             configuration (e.g. below ``providers.[openstack].cloud``
+             refers to the ``cloud`` key in the ``providers`` section
+             when the ``openstack`` driver is selected).
+
+   An OpenStack provider's resources are partitioned into groups
+   called "pools" (see :attr:`providers.[openstack].pools` for details),
+   and within a pool, the node types which are to be made available
+   are listed (see :attr:`providers.[openstack].pools.labels` for
+   details).
+
+   Within each OpenStack provider the available Nodepool image types
+   are defined (see :attr:`providers.[openstack].diskimages`).
+
+   .. code-block:: yaml
+
+      providers:
+        - name: provider1
+          driver: openstack
+          cloud: example
+          region-name: 'region1'
+          rate: 1.0
+          boot-timeout: 120
+          launch-timeout: 900
+          launch-retries: 3
+          image-name-format: '{image_name}-{timestamp}'
+          hostname-format: '{label.name}-{provider.name}-{node.id}'
+          post-upload-hook: /usr/bin/custom-hook
+          diskimages:
+            - name: trusty
+              meta:
+                  key: value
+                  key2: value
+            - name: precise
+            - name: devstack-trusty
+          pools:
+            - name: main
+              max-servers: 96
+              availability-zones:
+                - az1
+              networks:
+                - some-network-name
+              security-groups:
+                - zuul-security-group
+              labels:
+                - name: trusty
+                  min-ram: 8192
+                  diskimage: trusty
+                  console-log: True
+                - name: precise
+                  min-ram: 8192
+                  diskimage: precise
+                - name: devstack-trusty
+                  min-ram: 8192
+                  diskimage: devstack-trusty
+        - name: provider2
+          driver: openstack
+          cloud: example2
+          region-name: 'region1'
+          rate: 1.0
+          image-name-format: '{image_name}-{timestamp}'
+          hostname-format: '{label.name}-{provider.name}-{node.id}'
+          diskimages:
+            - name: precise
+              meta:
+                  key: value
+                  key2: value
+          pools:
+            - name: main
+              max-servers: 96
+              labels:
+                - name: trusty
+                  min-ram: 8192
+                  diskimage: trusty
+                - name: precise
+                  min-ram: 8192
+                  diskimage: precise
+                - name: devstack-trusty
+                  min-ram: 8192
+                  diskimage: devstack-trusty
+
+   .. attr:: cloud
+      :type: string
+      :required:
+
+      Name of a cloud configured in ``clouds.yaml``.
+
+      The instances spawned by nodepool will inherit the default
+      security group of the project specified in the cloud definition
+      in `clouds.yaml` (if other values not specified). This means
+      that when working with Zuul, for example, SSH traffic (TCP/22)
+      must be allowed in the project's default security group for Zuul
+      to be able to reach instances.
+
+      More information about the contents of `clouds.yaml` can be
+      found in `the openstacksdk documentation
+      <https://docs.openstack.org/openstacksdk/>`_.
+
+   .. attr:: boot-timeout
+      :type: int seconds
+      :default: 60
+
+      Once an instance is active, how long to try connecting to the
+      image via SSH.  If the timeout is exceeded, the node launch is
+      aborted and the instance deleted.
+
+   .. attr:: launch-timeout
+      :type: int seconds
+      :default: 3600
+
+      The time to wait from issuing the command to create a new instance
+      until that instance is reported as "active".  If the timeout is
+      exceeded, the node launch is aborted and the instance deleted.
+
+   .. attr:: nodepool-id
+      :type: string
+      :default: None
+
+      *Deprecated*
+
+      A unique string to identify which nodepool instances is using a
+      provider.  This is useful if you want to configure production
+      and development instances of nodepool but share the same
+      provider.
+
+  .. attr:: launch-retries
+     :type: int
+     :default: 3
+
+      The number of times to retry launching a server before
+      considering the job failed.
+
+  .. attr:: region-name
+     :type: string
+
+     The region name if the provider cloud has multiple regions.
+
+  .. attr:: hostname-format
+     :type: string
+     :default: {label.name}-{provider.name}-{node.id}
+
+     Hostname template to use for the spawned instance.
+
+  .. attr:: image-name-format
+     :type: string
+     :default: {image_name}-{timestamp}
+
+     Format for image names that are uploaded to providers.
+
+  .. attr:: post-upload-hook
+     :type: string
+     :default: None
+
+     Filename of an optional script that can be called after an image has
+     been uploaded to a provider but before it is taken into use. This is
+     useful to perform last minute validation tests before an image is
+     really used for build nodes. The script will be called as follows:
+
+     ``<SCRIPT> <PROVIDER> <EXTERNAL_IMAGE_ID> <LOCAL_IMAGE_FILENAME>``
+
+     If the script returns with result code 0 it is treated as successful
+     otherwise it is treated as failed and the image gets deleted.
+
+  .. attr:: rate
+     :type: int seconds
+     :default: 1
+
+     In seconds, amount to wait between operations on the provider.
+
+  .. attr:: clean-floating-ips
+     :type: bool
+     :default: True
+
+     If it is set to True, nodepool will assume it is the only user of
+     the OpenStack project and will attempt to clean unattached
+     floating ips that may have leaked around restarts.
+
+  .. attr:: port-cleanup-interval
+     :type: int seconds
+     :default: 600
+
+     If greater than 0, nodepool will assume it is the only user of the
+     OpenStack project and will attempt to clean ports in `DOWN` state after
+     the cleanup interval has elapsed. This value can be reduced if the
+     instance spawn time on the provider is reliably quicker.
+
+  .. attr:: diskimages
+     :type: list
+
+     Each entry in a provider's `diskimages` section must correspond
+     to an entry in :attr:`diskimages`.  Such an entry indicates that
+     the corresponding diskimage should be uploaded for use in this
+     provider.  Additionally, any nodes that are created using the
+     uploaded image will have the associated attributes (such as
+     flavor or metadata).
+
+     If an image is removed from this section, any previously uploaded
+     images will be deleted from the provider.
+
+     .. code-block:: yaml
+
+        diskimages:
+          - name: precise
+            pause: False
+            meta:
+                key: value
+                key2: value
+          - name: windows
+            connection-type: winrm
+            connection-port: 5986
+
+     Each entry is a dictionary with the following keys
+
+     .. attr:: name
+        :type: string
+        :required:
+
+        Identifier to refer this image from
+        :attr:`providers.[openstack].pools.labels` and
+        :attr:`diskimages` sections.
+
+     .. attr:: pause
+        :type: bool
+        :default: False
+
+        When set to True, nodepool-builder will not upload the image
+        to the provider.
+
+     .. attr:: config-drive
+        :type: bool
+        :default: unset
+
+        Whether config drive should be used for the image. Defaults to
+        unset which will use the cloud's default behavior.
+
+     .. attr:: meta
+        :type: dict
+
+        Arbitrary key/value metadata to store for this server using
+        the Nova metadata service. A maximum of five entries is
+        allowed, and both keys and values must be 255 characters or
+        less.
+
+     .. attr:: connection-type
+        :type: string
+
+        The connection type that a consumer should use when connecting
+        to the node. For most diskimages this is not
+        necessary. However when creating Windows images this could be
+        ``winrm`` to enable access via ansible.
+
+     .. attr:: connection-port
+        :type: int
+        :default: 22 / 5986
+
+        The port that a consumer should use when connecting to the
+        node. For most diskimages this is not necessary. This defaults
+        to 22 for ssh and 5986 for winrm.
+
+  .. attr:: cloud-images
+     :type: list
+
+     Each entry in this section must refer to an entry in the
+     :attr:`labels` section.
+
+     .. code-block:: yaml
+
+        cloud-images:
+          - name: trusty-external
+            config-drive: False
+          - name: windows-external
+            connection-type: winrm
+            connection-port: 5986
+
+     Each entry is a dictionary with the following keys
+
+     .. attr:: name
+        :type: string
+        :required:
+
+        Identifier to refer this cloud-image from :attr:`labels`
+        section.  Since this name appears elsewhere in the nodepool
+        configuration file, you may want to use your own descriptive
+        name here and use one of ``image-id`` or ``image-name`` to
+        specify the cloud image so that if the image name or id
+        changes on the cloud, the impact to your Nodepool
+        configuration will be minimal.  However, if neither of those
+        attributes are provided, this is also assumed to be the image
+        name or ID in the cloud.
+
+     .. attr:: config-drive
+        :type: bool
+        :default: unset
+
+        Whether config drive should be used for the cloud
+        image. Defaults to unset which will use the cloud's default
+        behavior.
+
+     .. attr:: image-id
+        :type: str
+
+        If this is provided, it is used to select the image from the
+        cloud provider by ID, rather than name.  Mutually exclusive
+        with :attr:`providers.[openstack].cloud-images.image-name`
+
+     .. attr:: image-name
+        :type: str
+
+        If this is provided, it is used to select the image from the
+        cloud provider by this name or ID.  Mutually exclusive with
+        :attr:`providers.[openstack].cloud-images.image-id`
+
+     .. attr:: username
+        :type: str
+
+        The username that a consumer should use when connecting to the
+        node.
+
+     .. attr:: python-path
+        :type: str
+        :default: auto
+
+        The path of the default python interpreter.  Used by Zuul to set
+        ``ansible_python_interpreter``.  The special value ``auto`` will
+        direct Zuul to use inbuilt Ansible logic to select the
+        interpreter on Ansible >=2.8, and default to
+        ``/usr/bin/python2`` for earlier versions.
+
+     .. attr:: connection-type
+        :type: str
+
+        The connection type that a consumer should use when connecting
+        to the node. For most diskimages this is not
+        necessary. However when creating Windows images this could be
+        'winrm' to enable access via ansible.
+
+     .. attr:: connection-port
+        :type: int
+        :default: 22/ 5986
+
+        The port that a consumer should use when connecting to the
+        node. For most diskimages this is not necessary. This defaults
+        to 22 for ssh and 5986 for winrm.
+
+  .. attr:: pools
+     :type: list
+
+     A pool defines a group of resources from an OpenStack
+     provider. Each pool has a maximum number of nodes which can be
+     launched from it, along with a number of cloud-related attributes
+     used when launching nodes.
+
+     .. code-block:: yaml
+
+        pools:
+          - name: main
+            max-servers: 96
+            availability-zones:
+              - az1
+            networks:
+              - some-network-name
+            security-groups:
+              - zuul-security-group
+            auto-floating-ip: False
+            host-key-checking: True
+            node-attributes:
+              key1: value1
+              key2: value2
+            labels:
+              - name: trusty
+                min-ram: 8192
+                diskimage: trusty
+                console-log: True
+              - name: precise
+                min-ram: 8192
+                diskimage: precise
+              - name: devstack-trusty
+                min-ram: 8192
+                diskimage: devstack-trusty
+
+     Each entry is a dictionary with the following keys
+
+     .. attr:: name
+        :type: string
+        :required:
+
+        Pool name
+
+     .. attr:: node-attributes
+        :type: dict
+
+        A dictionary of key-value pairs that will be stored with the node data
+        in ZooKeeper. The keys and values can be any arbitrary string.
+
+     .. attr:: max-cores
+        :type: int
+
+        Maximum number of cores usable from this pool. This can be used
+        to limit usage of the tenant. If not defined nodepool can use
+        all cores up to the quota of the tenant.
+
+     .. attr:: max-servers
+        :type: int
+
+        Maximum number of servers spawnable from this pool. This can
+        be used to limit the number of servers. If not defined
+        nodepool can create as many servers the tenant allows.
+
+     .. attr:: max-ram
+        :type: int
+
+        Maximum ram usable from this pool. This can be used to limit
+        the amount of ram allocated by nodepool. If not defined
+        nodepool can use as much ram as the tenant allows.
+
+     .. attr:: ignore-provider-quota
+        :type: bool
+        :default: False
+
+        Ignore the provider quota for this pool. Instead, only check
+        against the configured max values for this pool and the
+        current usage based on stored data. This may be useful in
+        circumstances where the provider is incorrectly calculating
+        quota.
+
+     .. attr:: availability-zones
+        :type: list
+
+        A list of availability zones to use.
+
+        If this setting is omitted, nodepool will fetch the list of
+        all availability zones from nova.  To restrict nodepool to a
+        subset of availability zones, supply a list of availability
+        zone names in this setting.
+
+        Nodepool chooses an availability zone from the list at random
+        when creating nodes but ensures that all nodes for a given
+        request are placed in the same availability zone.
+
+     .. attr:: networks
+        :type: list
+
+        Specify custom Neutron networks that get attached to each
+        node. Specify the name or id of the network as a string.
+
+     .. attr:: security-groups
+        :type: list
+
+        Specify custom Neutron security groups that get attached to
+        each node. Specify the name or id of the security_group as a
+        string.
+
+     .. attr:: auto-floating-ip
+        :type: bool
+        :default: True
+
+        Specify custom behavior of allocating floating ip for each
+        node.  When set to False, ``nodepool-launcher`` will not apply
+        floating ip for nodes. When zuul instances and nodes are
+        deployed in the same internal private network, set the option
+        to False to save floating ip for cloud provider.
+
+     .. attr:: host-key-checking
+        :type: bool
+        :default: True
+
+        Specify custom behavior of validation of SSH host keys.  When
+        set to False, nodepool-launcher will not ssh-keyscan nodes
+        after they are booted. This might be needed if
+        nodepool-launcher and the nodes it launches are on different
+        networks.  The default value is True.
+
+     .. attr:: labels
+        :type: list
+
+        Each entry in a pool`s `labels` section indicates that the
+        corresponding label is available for use in this pool.  When
+        creating nodes for a label, the flavor-related attributes in that
+        label's section will be used.
+
+        .. code-block:: yaml
+
+           labels:
+             - name: precise
+               min-ram: 8192
+               flavor-name: 'something to match'
+               console-log: True
+             - name: trusty
+               min-ram: 8192
+               networks:
+                 - public
+                 - private
+
+        Each entry is a dictionary with the following keys
+
+        .. attr:: name
+           :type: str
+           :required:
+
+           Identifier to refer this image; from :attr:`labels` and
+           :attr:`diskimages` sections.
+
+        .. attr:: diskimage
+           :type: str
+           :required:
+
+           Refers to provider's diskimages, see
+           :attr:`providers.[openstack].diskimages`.  Mutually exclusive
+           with :attr:`providers.[openstack].pools.labels.cloud-image`
+
+        .. attr:: cloud-image
+           :type: str
+           :required:
+
+           Refers to the name of an externally managed image in the
+           cloud that already exists on the provider. The value of
+           ``cloud-image`` should match the ``name`` of a previously
+           configured entry from the ``cloud-images`` section of the
+           provider. See :attr:`providers.[openstack].cloud-images`.
+           Mutually exclusive with
+           :attr:`providers.[openstack].pools.labels.diskimage`
+
+        .. attr:: flavor-name
+           :type: str
+
+           Name or id of the flavor to use. If
+           :attr:`providers.[openstack].pools.labels.min-ram` is
+           omitted, it must be an exact match. If
+           :attr:`providers.[openstack].pools.labels.min-ram` is given,
+           ``flavor-name`` will be used to find flavor names that meet
+           :attr:`providers.[openstack].pools.labels.min-ram` and also
+           contain ``flavor-name``.
+
+           One of :attr:`providers.[openstack].pools.labels.min-ram` or
+           :attr:`providers.[openstack].pools.labels.flavor-name` must
+           be specified.
+
+        .. attr:: min-ram
+           :type: int
+
+           Determine the flavor to use (e.g. ``m1.medium``,
+           ``m1.large``, etc).  The smallest flavor that meets the
+           ``min-ram`` requirements will be chosen.
+
+           One of :attr:`providers.[openstack].pools.labels.min-ram` or
+           :attr:`providers.[openstack].pools.labels.flavor-name` must
+           be specified.
+
+        .. attr:: boot-from-volume
+           :type: bool
+           :default: False
+
+            If given, the label for use in this pool will create a
+            volume from the image and boot the node from it.
+
+        .. attr:: host-key-checking
+           :type: bool
+           :default: True
+
+           Specify custom behavior of validation of SSH host keys.  When set to
+           False, nodepool-launcher will not ssh-keyscan nodes after they are
+           booted. This might be needed if nodepool-launcher and the nodes it
+           launches are on different networks.  The default value is True.
+
+           .. note:: This value will override the value for
+                     :attr:`providers.[openstack].pools.host-key-checking`.
+
+        .. attr:: networks
+           :type: list
+
+           Specify custom Neutron networks that get attached to each
+           node. Specify the name or id of the network as a string.
+
+           .. note:: This value will override the value for
+                     :attr:`providers.[openstack].pools.networks`.
+
+        .. attr:: key-name
+           :type: string
+
+           If given, is the name of a keypair that will be used when
+           booting each server.
+
+        .. attr:: console-log
+           :type: bool
+           :default: False
+
+           On the failure of the ssh ready check, download the server
+           console log to aid in debugging the problem.
+
+        .. attr:: volume-size
+           :type: int gigabytes
+           :default: 50
+
+           When booting an image from volume, how big should the
+           created volume be.
+
+        .. attr:: instance-properties
+           :type: dict
+           :default: None
+
+           A dictionary of key/value properties to set when booting
+           each server.  These properties become available via the
+           ``meta-data`` on the active server (e.g. within
+           ``config-drive:openstack/latest/meta_data.json``)
+
+        .. attr:: userdata
+           :type: str
+           :default: None
+
+           A string of userdata for a node. Example usage is to install
+           cloud-init package on image which will apply the userdata.
+           Additional info about options in cloud-config:
+           https://cloudinit.readthedocs.io/en/latest/topics/examples.html
+
diff --git a/doc/source/static.rst b/doc/source/static.rst
new file mode 100644
index 000000000..55c14f283
--- /dev/null
+++ b/doc/source/static.rst
@@ -0,0 +1,150 @@
+.. _static-driver:
+
+.. default-domain:: zuul
+
+Static Driver
+-------------
+
+Selecting the static driver adds the following options to the
+:attr:`providers` section of the configuration.
+
+.. attr-overview::
+   :prefix: providers.[static]
+   :maxdepth: 3
+
+.. attr:: providers.[static]
+   :type: list
+
+   The static provider driver is used to define static nodes.
+
+   .. note:: For documentation purposes the option names are prefixed
+             ``providers.[static]`` to disambiguate from other
+             drivers, but ``[static]`` is not required in the
+             configuration (e.g. below ``providers.[static].pools``
+             refers to the ``pools`` key in the ``providers`` section
+             when the ``static`` driver is selected).
+
+   Example:
+
+   .. code-block:: yaml
+
+      providers:
+        - name: static-rack
+          driver: static
+          pools:
+            - name: main
+              nodes:
+                - name: trusty.example.com
+                  labels: trusty-static
+                  timeout: 13
+                  connection-port: 22022
+                  host-key: fake-key
+                  username: zuul
+                  max-parallel-jobs: 1
+
+   .. attr:: pools
+      :type: list
+
+      A pool defines a group of statically declared nodes.
+
+      .. note::
+
+         When providing different labels, it is better to have one pool per
+         label to avoid requests being queued when one label is at capacity.
+
+      Each entry is a dictionary with entries as follows
+
+      .. attr:: name
+         :type: str
+         :required:
+
+         Pool name
+
+      .. attr:: node-attributes
+         :type: dict
+
+         A dictionary of key-value pairs that will be stored with the node data
+         in ZooKeeper. The keys and values can be any arbitrary string.
+
+      .. attr:: nodes
+         :type: list
+         :required:
+
+         Each entry indicates a static node and it's attributes.
+
+         .. attr:: name
+            :type: str
+            :required:
+
+            The hostname or ip address of the static node. This must be
+            unique across all nodes defined within the configuration file.
+
+         .. attr:: labels
+            :type: list
+            :required:
+
+            The list of labels associated with the node.
+
+         .. attr:: host-key-checking
+             :type: bool
+             :default: True
+
+             Specify custom behavior of validation of host connection.
+             When set to False, nodepool-launcher will not scan the nodes
+             before they are registered. This might be needed if
+             nodepool-launcher and the static nodes are on isolated
+             networks. The default value is True.
+
+         .. attr:: timeout
+            :type: int
+            :default: 5
+
+            The timeout in second before the ssh ping is considered failed.
+
+         .. attr:: connection-type
+            :type: string
+            :default: ssh
+
+            The connection type that a consumer should use when connecting
+            to the node.
+
+            .. value:: winrm
+
+            .. value:: ssh
+
+         .. attr:: connection-port
+            :type: int
+            :default: 22 / 5986
+
+            The port that a consumer should use when connecting to the node.
+            For most nodes this is not necessary. This defaults to 22 when
+            ``connection-type`` is 'ssh' and 5986 when it is 'winrm'.
+
+         .. attr:: host-key
+            :type: str
+
+            The ssh host key of the node.
+
+         .. attr:: username
+            :type: str
+            :default: zuul
+
+            The username nodepool will use to validate it can connect to the
+            node.
+
+         .. attr:: python-path
+            :type: str
+            :default: /usr/bin/python2
+
+            The path of the default python interpreter.  Used by Zuul to set
+            ``ansible_python_interpreter``.  The special value ``auto`` will
+            direct Zuul to use inbuilt Ansible logic to select the
+            interpreter on Ansible >=2.8, and default to
+            ``/usr/bin/python2`` for earlier versions.
+
+         .. attr:: max-parallel-jobs
+            :type: int
+            :default: 1
+
+            The number of jobs that can run in parallel on this node.
+