.. attr:: provider[openstack]
   :type: dict

   The attributes available for configuring an OpenStack provider
   are below.

   .. attr:: abstract
      :type: bool
      :default: False

      Whether a section is intended to be inherited by
      another :attr:`section` or a :attr:`provider`.  This
      setting is currently unused (but may be used in the
      future).  If a section is used to provide common
      values to other sections, set this to `true`.
      Otherwise, the default of `false` indicates that the
      section should be referenced directly by providers.

   .. attr:: connection
      :type: str

      The name of the :ref:`connection <connections>` to
      use.  This attribute is only used by :attr:`section`
      objects.

   .. attr:: flavor-defaults
      :type: dict

      Attributes to be set as default values for any flavor
      used with this provider.  Many attributes which may be
      set on an individual flavor may be set once in this
      section and used for all the flavors in this provider.
      Values set on individual flavors may still override the
      values set here.

      .. attr:: final
         :default: False

         Whether the configuration of the flavor may be updated
         by values in flavor-defaults or overidden with a new definition
         by sections or providers lower in the hierarchy than the point
         at which the final attribute is applied.

         .. value:: True

            The flavor may not be updated or overidden.

         .. value:: False

            The flavor may be updated or overidden.

         .. value:: allow-override

            The flavor may not be updated by flavor-defaults
            but may be explicitly overidden by redefining
            it in a new 'flavor' entry.

      .. attr:: public-ipv4
         :type: bool
         :default: False

         Whether a public IPv4 address should be attached to nodes.

      .. attr:: public-ipv6
         :type: bool
         :default: False

         Whether a public IPv6 address should be attached to nodes.

      .. attr:: userdata
         :type: str

         A string of userdata for a node.  Systems such as "cloud-init"
         may use this to configure the node on boot.

      .. attr:: volume-size
         :type: int

         When booting an image from volume, this indicates the
         size of the created volume, in GB.

   .. attr:: flavors
      :type: dict

      A list of flavors associated with this provider.

      .. attr:: description
         :type: str

         A textual description of the image for reference purposes.

      .. attr:: final
         :default: False

         Whether the configuration of the flavor may be updated
         by values in flavor-defaults or overidden with a new definition
         by sections or providers lower in the hierarchy than the point
         at which the final attribute is applied.

         .. value:: True

            The flavor may not be updated or overidden.

         .. value:: False

            The flavor may be updated or overidden.

         .. value:: allow-override

            The flavor may not be updated by flavor-defaults
            but may be explicitly overidden by redefining
            it in a new 'flavor' entry.

      .. attr:: flavor-name
         :type: str

         Name or id of the OpenStack flavor to use.

      .. attr:: name
         :type: str

         The name of the flavor.  Used to refer to the flavor in Zuul
         configuration.

      .. attr:: public-ipv4
         :type: bool
         :default: False

         Whether a public IPv4 address should be attached to nodes.

      .. attr:: public-ipv6
         :type: bool
         :default: False

         Whether a public IPv6 address should be attached to nodes.

      .. attr:: userdata
         :type: str

         A string of userdata for a node.  Systems such as "cloud-init"
         may use this to configure the node on boot.

      .. attr:: volume-size
         :type: int

         When booting an image from volume, this indicates the
         size of the created volume, in GB.

   .. attr:: floating-ip-cleanup
      :type: bool
      :default: False

      If set to ``true``, Zuul will behave as if it is the
      only user of the OpenStack project and will attempt to
      clean unattached floating IPs that may have leaked.

   .. attr:: image-defaults
      :type: dict

      Attributes to be set as default values for any image
      used with this provider.  Many attributes which may be
      set on an individual image may be set once in this
      section and used for all the images in this provider.
      Values set on individual images may still override the
      values set here.

      .. attr:: config-drive
         :type: bool
         :default: True

         Whether config drive should be used for the cloud
         image.

      .. attr:: connection-port
         :type: int

         The port that Zuul 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:: connection-type

         The connection type that a consumer should use when connecting
         to the node.

         .. value:: winrm

            A winrm connection.

         .. value:: ssh

            An ssh connection.

      .. attr:: final
         :default: False

         Whether the configuration of the label may be updated
         by values in label-defaults or overidden with a new definition
         by sections or providers lower in the hierarchy than the point
         at which the final attribute is applied.

         .. value:: True

            The label may not be updated or overidden.

         .. value:: False

            The label may be updated or overidden.

         .. value:: allow-override

            The label may not be updated by label-defaults
            but may be explicitly overidden by redefining
            it in a new 'label' entry.

      .. attr:: import-timeout
         :type: int
         :default: 300

         The limit on the amount of time a successful image import can
         take.

      .. attr:: python-path
         :type: str

         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.

      .. attr:: shell-type
         :type: str

         The shell type of the node's default shell executable. Used by Zuul
         to set ``ansible_shell_type``. This setting should only be used

         - For a windows image with the experimental `connection-type` ``ssh``
           in which case ``cmd`` or ``powershell`` should be set
           and reflect the node's ``DefaultShell`` configuration.
         - If the default shell is not Bourne compatible (sh), but instead
           e.g. ``csh`` or ``fish``, and the user is aware that there is a
           long-standing issue with ``ansible_shell_type`` in combination
           with ``become``.

      .. attr:: tags
         :type: dict

         A dictionary of tags to add to uploaded images, and to nodes
         created from them.  Avoid the use of `zuul_` as a key prefix since
         Zuul uses this for internal values.

      .. attr:: upload-methods
         :type: list
         :default: ['copy', 'import', 'upload']

         An ordered list of methods to use when creating an image in
         the provider.

         .. value:: copy

            Copy the image from another provider if available.

         .. value:: import

            Import the image directly from its storage location.

         .. value:: upload

            Download the image from its storage location and
            upload it to the provider.

      .. attr:: userdata
         :type: str

         A string of userdata for a node.  Systems such as "cloud-init"
         may use this to configure the node on boot.

      .. attr:: username
         :type: str

         The username Zuul should use when connecting to the node.

      .. attr:: volume-size
         :type: int

         When booting an image from volume, this indicates the
         size of the created volume, in GB.

   .. attr:: images
      :type: list

      A list of images associated with this provider.

   .. attr:: images[cloud]
      :type: dict

      These are the attributes available for a cloud image.

      .. attr:: config-drive
         :type: bool
         :default: True

         Whether config drive should be used for the cloud
         image.

      .. attr:: connection-port
         :type: int

         The port that Zuul 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:: connection-type

         The connection type that a consumer should use when connecting
         to the node.

         .. value:: winrm

            A winrm connection.

         .. value:: ssh

            An ssh connection.

      .. attr:: description
         :type: str

         A textual description of the image for reference purposes.

      .. attr:: final
         :default: False

         Whether the configuration of the label may be updated
         by values in label-defaults or overidden with a new definition
         by sections or providers lower in the hierarchy than the point
         at which the final attribute is applied.

         .. value:: True

            The label may not be updated or overidden.

         .. value:: False

            The label may be updated or overidden.

         .. value:: allow-override

            The label may not be updated by label-defaults
            but may be explicitly overidden by redefining
            it in a new 'label' entry.

      .. attr:: image-id
         :type: str

         The ID of the cloud provider's image.

      .. attr:: import-timeout
         :type: int
         :default: 300

         The limit on the amount of time a successful image import can
         take.

      .. attr:: name
         :type: str

         The name of the image.  Used to refer to the image in Zuul
         configuration.

      .. attr:: python-path
         :type: str

         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.

      .. attr:: shell-type
         :type: str

         The shell type of the node's default shell executable. Used by Zuul
         to set ``ansible_shell_type``. This setting should only be used

         - For a windows image with the experimental `connection-type` ``ssh``
           in which case ``cmd`` or ``powershell`` should be set
           and reflect the node's ``DefaultShell`` configuration.
         - If the default shell is not Bourne compatible (sh), but instead
           e.g. ``csh`` or ``fish``, and the user is aware that there is a
           long-standing issue with ``ansible_shell_type`` in combination
           with ``become``.

      .. attr:: type

         The type of image.

         .. value:: cloud

            An existing image available in the cloud.

      .. attr:: userdata
         :type: str

         A string of userdata for a node.  Systems such as "cloud-init"
         may use this to configure the node on boot.

      .. attr:: username
         :type: str

         The username Zuul should use when connecting to the node.

      .. attr:: volume-size
         :type: int

         When booting an image from volume, this indicates the
         size of the created volume, in GB.

   .. attr:: images[zuul]
      :type: dict

      These are the attributes available for a Zuul image.

      .. attr:: config-drive
         :type: bool
         :default: True

         Whether config drive should be used for the cloud
         image.

      .. attr:: connection-port
         :type: int

         The port that Zuul 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:: connection-type

         The connection type that a consumer should use when connecting
         to the node.

         .. value:: winrm

            A winrm connection.

         .. value:: ssh

            An ssh connection.

      .. attr:: description
         :type: str

         A textual description of the image for reference purposes.

      .. attr:: final
         :default: False

         Whether the configuration of the label may be updated
         by values in label-defaults or overidden with a new definition
         by sections or providers lower in the hierarchy than the point
         at which the final attribute is applied.

         .. value:: True

            The label may not be updated or overidden.

         .. value:: False

            The label may be updated or overidden.

         .. value:: allow-override

            The label may not be updated by label-defaults
            but may be explicitly overidden by redefining
            it in a new 'label' entry.

      .. attr:: import-timeout
         :type: int
         :default: 300

         The limit on the amount of time a successful image import can
         take.

      .. attr:: name
         :type: str

         The name of the image.  Used to refer to the image in Zuul
         configuration.

      .. attr:: python-path
         :type: str

         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.

      .. attr:: shell-type
         :type: str

         The shell type of the node's default shell executable. Used by Zuul
         to set ``ansible_shell_type``. This setting should only be used

         - For a windows image with the experimental `connection-type` ``ssh``
           in which case ``cmd`` or ``powershell`` should be set
           and reflect the node's ``DefaultShell`` configuration.
         - If the default shell is not Bourne compatible (sh), but instead
           e.g. ``csh`` or ``fish``, and the user is aware that there is a
           long-standing issue with ``ansible_shell_type`` in combination
           with ``become``.

      .. attr:: tags
         :type: dict

         A dictionary of tags to add to uploaded images, and to nodes
         created from them.  Avoid the use of `zuul_` as a key prefix since
         Zuul uses this for internal values.

      .. attr:: type

         The type of image.

         .. value:: zuul

            An image managed by Zuul.

      .. attr:: upload-methods
         :type: list
         :default: ['copy', 'import', 'upload']

         An ordered list of methods to use when creating an image in
         the provider.

         .. value:: copy

            Copy the image from another provider if available.

         .. value:: import

            Import the image directly from its storage location.

         .. value:: upload

            Download the image from its storage location and
            upload it to the provider.

      .. attr:: userdata
         :type: str

         A string of userdata for a node.  Systems such as "cloud-init"
         may use this to configure the node on boot.

      .. attr:: username
         :type: str

         The username Zuul should use when connecting to the node.

      .. attr:: volume-size
         :type: int

         When booting an image from volume, this indicates the
         size of the created volume, in GB.

   .. attr:: label-defaults
      :type: dict

      Attributes to be set as default values for any label
      used with this provider.  Many attributes which may be
      set on an individual label may be set once in this
      section and used for all the labels in this provider.
      Values set on individual labels may still override the
      values set here.

      .. attr:: auto-floating-ip
         :type: bool
         :default: True

         Whether to automatically allocate and assign a floating IP
         for each node.

      .. attr:: az
         :type: str

         Servers will be assigned to the specified availibility
         zone.  If omitted, one will be chosen at random.

      .. attr:: boot-from-volume
         :type: bool
         :default: False

         Whether to create a volume from the image and boot the
         node from it.

      .. attr:: boot-timeout
         :type: int
         :default: 300

         The time (in seconds) to wait for a node to boot.

      .. attr:: executor-zone
         :type: str

         Specify that a Zuul executor in the specified zone is
         used to run jobs with nodes from this label.

      .. attr:: final
         :default: False

         Whether the configuration of the label may be updated
         by values in label-defaults or overidden with a new definition
         by sections or providers lower in the hierarchy than the point
         at which the final attribute is applied.

         .. value:: True

            The label may not be updated or overidden.

         .. value:: False

            The label may be updated or overidden.

         .. value:: allow-override

            The label may not be updated by label-defaults
            but may be explicitly overidden by redefining
            it in a new 'label' entry.

      .. attr:: host-key-checking
         :type: bool
         :default: True

         Whether to validate SSH host keys.  When true, this helps
         ensure that nodes are ready to receive SSH connections before
         they are used.  When set to false, Zuul will not attempt to
         ssh-keyscan nodes after they are booted.  Disable this if the
         zuul-launcher and the nodes it launches are on different
         networks, where the launcher is unable to reach the nodes
         directly.

      .. attr:: key-name
         :type: str

         The name of a keypair that will be used when
         booting the node.

      .. attr:: max-age
         :type: int
         :default: 0

         The time (in seconds) since creation that a node may be
         available for use.  Ready nodes older than this time will be
         deleted.

      .. attr:: max-ready-age
         :type: int
         :default: 0

         The time (in seconds) an unassigned node should stay in ready state.

      .. attr:: min-retention-time
         :type: int
         :default: 0

         The time (in seconds) since an instance was launched, during
         which a node will not be deleted. For node resources with
         minimum billing times, this can be used to ensure that the
         instance is retained for at least the minimum billing interval.

         This setting takes precedence over `max-[ready-]age`.

      .. attr:: networks
         :type: str

         The OpenStack networks to associate with the node.

      .. attr:: reuse
         :type: bool
         :default: False

         Should the node be reused (True) or deleted (False) after use.

      .. attr:: security-groups
         :type: str

         Specify custom networks to be attached to each
         node.  Specify the name or id of the network as a string.

      .. attr:: slots
         :type: int
         :default: 1

         How many jobs are permitted run on the same node simultaneously.

      .. attr:: snapshot-expiration
         :type: int
         :default: 604800

         The time (in seconds) until a snapshot expires.

      .. attr:: snapshot-timeout
         :type: int
         :default: 3600

         The time (in seconds) to wait for a snapshot to complete.

      .. attr:: tags
         :type: dict

         A dictionary of tags to add to nodes.  Avoid the use of
         `zuul_` as a key prefix since Zuul uses this for internal
         values.

      .. attr:: userdata
         :type: str

         A string of userdata for a node.  Systems such as "cloud-init"
         may use this to configure the node on boot.

      .. attr:: volume-size
         :type: int

         When booting an image from volume, this indicates the
         size of the created volume, in GB.

   .. attr:: labels
      :type: dict

      A list of labels associated with this provider.

      .. attr:: auto-floating-ip
         :type: bool
         :default: True

         Whether to automatically allocate and assign a floating IP
         for each node.

      .. attr:: az
         :type: str

         Servers will be assigned to the specified availibility
         zone.  If omitted, one will be chosen at random.

      .. attr:: boot-from-volume
         :type: bool
         :default: False

         Whether to create a volume from the image and boot the
         node from it.

      .. attr:: boot-timeout
         :type: int
         :default: 300

         The time (in seconds) to wait for a node to boot.

      .. attr:: description
         :type: str

         A textual description of the label for reference purposes.

      .. attr:: executor-zone
         :type: str

         Specify that a Zuul executor in the specified zone is
         used to run jobs with nodes from this label.

      .. attr:: final
         :default: False

         Whether the configuration of the label may be updated
         by values in label-defaults or overidden with a new definition
         by sections or providers lower in the hierarchy than the point
         at which the final attribute is applied.

         .. value:: True

            The label may not be updated or overidden.

         .. value:: False

            The label may be updated or overidden.

         .. value:: allow-override

            The label may not be updated by label-defaults
            but may be explicitly overidden by redefining
            it in a new 'label' entry.

      .. attr:: flavor
         :type: str

         The flavor to use with this label.

      .. attr:: host-key-checking
         :type: bool
         :default: True

         Whether to validate SSH host keys.  When true, this helps
         ensure that nodes are ready to receive SSH connections before
         they are used.  When set to false, Zuul will not attempt to
         ssh-keyscan nodes after they are booted.  Disable this if the
         zuul-launcher and the nodes it launches are on different
         networks, where the launcher is unable to reach the nodes
         directly.

      .. attr:: image
         :type: str

         The image to use with this label.

      .. attr:: key-name
         :type: str

         The name of a keypair that will be used when
         booting the node.

      .. attr:: max-age
         :type: int
         :default: 0

         The time (in seconds) since creation that a node may be
         available for use.  Ready nodes older than this time will be
         deleted.

      .. attr:: max-ready-age
         :type: int
         :default: 0

         The time (in seconds) an unassigned node should stay in ready state.

      .. attr:: min-ready
         :type: int
         :default: 0

         Minimum number of instances that should be in a ready
         state. Zuul always creates more nodes as necessary in
         response to demand, but setting ``min-ready`` can speed
         processing by attempting to keep nodes on-hand and ready for
         immedate use.  This is best-effort based on available
         capacity and is not a guaranteed allocation.  The default of 0
         means that Zuul will only create nodes of this label when
         there is demand.

      .. attr:: min-retention-time
         :type: int
         :default: 0

         The time (in seconds) since an instance was launched, during
         which a node will not be deleted. For node resources with
         minimum billing times, this can be used to ensure that the
         instance is retained for at least the minimum billing interval.

         This setting takes precedence over `max-[ready-]age`.

      .. attr:: name
         :type: str

         The name of the label.  Used to refer to the label in Zuul
         configuration.

      .. attr:: networks
         :type: str

         The OpenStack networks to associate with the node.

      .. attr:: reuse
         :type: bool
         :default: False

         Should the node be reused (True) or deleted (False) after use.

      .. attr:: security-groups
         :type: str

         Specify custom networks to be attached to each
         node.  Specify the name or id of the network as a string.

      .. attr:: slots
         :type: int
         :default: 1

         How many jobs are permitted run on the same node simultaneously.

      .. attr:: snapshot-expiration
         :type: int
         :default: 604800

         The time (in seconds) until a snapshot expires.

      .. attr:: snapshot-timeout
         :type: int
         :default: 3600

         The time (in seconds) to wait for a snapshot to complete.

      .. attr:: tags
         :type: dict

         A dictionary of tags to add to nodes.  Avoid the use of
         `zuul_` as a key prefix since Zuul uses this for internal
         values.

      .. attr:: userdata
         :type: str

         A string of userdata for a node.  Systems such as "cloud-init"
         may use this to configure the node on boot.

      .. attr:: volume-size
         :type: int

         When booting an image from volume, this indicates the
         size of the created volume, in GB.

   .. attr:: launch-attempts
      :type: int
      :default: 3

      The number of times to attempt launching a node before
      considering the request failed.

   .. attr:: launch-timeout
      :type: int

      The time to wait from issuing the command to create a
      new node until the node is reporting as running.  If
      the timeout is exceeded, the node launch is aborted
      and the node deleted.

   .. attr:: name
      :type: str

      The name of the provider.  Used to refer to the
      provider in Zuul configuration.

   .. attr:: parent
      :type: str

      The name of the parent section from which to inherit.
      This attribute is only used by :attr:`section`
      objects.  To indicate which section a provider should
      be attached to, use
      :attr:`provider[openstack].section`

   .. attr:: port-cleanup-interval
      :type: int
      :default: 600

      If greater than 0, Zuul will behave as if 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 may be reduced if
      the instance spawn time on the provider is reliably
      quicker.

   .. attr:: region
      :type: str

      The region name if the provider cloud has multiple
      regions.

   .. attr:: resource-limits
      :type: dict

      Resource limits for this provider.  Configure these
      values to cause Zuul to attempt to limit the resource
      usage.  This can be used to limit Zuul's usage to a
      level below the cloud quota.

      .. attr:: cores
         :type: int

         The number of cores.

      .. attr:: instances
         :type: int

         The number of instances.

      .. attr:: ram
         :type: int

         The amount of ram, in MiB.

      .. attr:: volume-gb
         :type: int

         The amount of volume storage in GB.

      .. attr:: volumes
         :type: int

         The number of volumes.

   .. attr:: section
      :type: str

      The name of the :attr:`section` from which to inherit.


