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

   The attributes available for configuring an AWS 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:: imds-http-tokens

         Specify whether IMDSv2 is required.  If this is omitted,
         then AWS defaults are used (usually equivalent to
         ``optional`` but may be influenced by the image used).

         .. value:: optional

            Allows usage of IMDSv2 but do not require it.  This
            sets the following metadata options:

            * `HttpTokens` is `optional`
            * `HttpEndpoint` is `enabled`

         .. value:: required

            Require IMDSv2.  This sets the following metadata
            options:

            * `HttpTokens` is `required`
            * `HttpEndpoint` is `enabled`

      .. attr:: iops
         :type: int

         The number of I/O operations per second to be provisioned for
         the volume.  The default varies based on the volume type; see
         the documentation under `EBS volume type`_ for the specific
         volume type for details.

      .. 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:: throughput
         :type: int

         The throughput of the volume in MiB/s.  This is only valid for
         ``gp3`` volumes.

      .. 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

         The size of the root EBS volume, in GiB, for the
         image.  If omitted, the volume size reported for the
         imported snapshot will be used.  Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

      .. attr:: volume-type
         :type: str
         :default: gp3

         The root `EBS volume type`_ for the image.
         Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

         .. _`EBS volume type`: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html

   .. attr:: flavors
      :type: dict

      A list of flavors associated with this provider.

      .. attr:: dedicated-host
         :type: bool
         :default: False

         If set to ``true``, an AWS dedicated host will be
         allocated for the instance.  The host may be used for one
         or more nodes depending on the settings of
         :attr:`provider[aws].labels.slots` and
         :attr:`provider[aws].labels.reuse`.

         If this option is set, the
         :value:`provider[aws].flavors.market-type.spot` option is
         not available, and :attr:`provider[aws].labels.az` option is
         required.

      .. attr:: description
         :type: str

         A textual description of the image for reference purposes.

      .. attr:: ebs-optimized
         :type: bool
         :default: False

         Indicates whether EBS optimization (additional, dedicated
         throughput between Amazon EC2 and Amazon EBS) should be
         enabled for the instance.

      .. 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:: fleet
         :type: dict

         If specified, the EC2 Fleet API will be used for launching
         the instance.  In this case, quota is not checked before
         launching the instance, but is taken into account after
         the instance is launched.  Mutually exclusive with
         :attr:`provider[aws].flavors.instance-type`.

         .. attr:: allocation-strategy

            The allocation strategy to use when launching the instance.

            .. value:: prioritized

               The prioritized allocation strategy.  Available for
               on-demand instances

            .. value:: price-capacity-optimized

               The price-capacity-optimized allocation strategy.
               Available for spot instances

            .. value:: capacity-optimized

               The capacity-optimized allocation strategy.  Available
               for spot instances

            .. value:: diversified

               The diversified allocation strategy.  Available for
               spot instances

            .. value:: lowest-price

               The lowest-price allocation strategy.  Available for
               spot or on-demand instances

         .. attr:: instance-types
            :type: str

            A list of instance types from which AWS may select when
            launching the instance.

      .. attr:: imds-http-tokens

         Specify whether IMDSv2 is required.  If this is omitted,
         then AWS defaults are used (usually equivalent to
         ``optional`` but may be influenced by the image used).

         .. value:: optional

            Allows usage of IMDSv2 but do not require it.  This
            sets the following metadata options:

            * `HttpTokens` is `optional`
            * `HttpEndpoint` is `enabled`

         .. value:: required

            Require IMDSv2.  This sets the following metadata
            options:

            * `HttpTokens` is `required`
            * `HttpEndpoint` is `enabled`

      .. attr:: instance-type
         :type: str

         Name of the AWS instance type to use..
         Mutually exclusive with :attr:`provider[aws].flavors.fleet`.

      .. attr:: iops
         :type: int

         The number of I/O operations per second to be provisioned for
         the volume.  The default varies based on the volume type; see
         the documentation under `EBS volume type`_ for the specific
         volume type for details.

      .. attr:: market-type
         :default: on-demand

         Whether to request an on-demand or spot instance.

         .. value:: on-demand

            This is the typical EC2 instance where continued
            availability is guaranteed after allocation.

         .. value:: spot

            Request an Amazon EC2 Spot instance instead of an
            On-Demand instance.  Spot instances take advantage of
            unused EC2 capacity at a discount, but if demand is
            high, instances may be unavailable.  In addition,
            Amazon EC2 may interrupt Spot instances and reclaim
            them.  Alternative nodesets with On-Demand instances
            configured as a fallback may be configured in order to
            mitigate this.

      .. 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:: throughput
         :type: int

         The throughput of the volume in MiB/s.  This is only valid for
         ``gp3`` volumes.

      .. 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

         The size of the root EBS volume, in GiB, for the
         image.  If omitted, the volume size reported for the
         imported snapshot will be used.  Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

      .. attr:: volume-type
         :type: str
         :default: gp3

         The root `EBS volume type`_ for the image.
         Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

         .. _`EBS volume type`: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html

   .. 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:: architecture
         :type: str
         :default: x86_64

         The architecture of the image.  See the `AWS RegisterImage API
         documentation`_ for valid values.

         .. _`AWS RegisterImage API documentation`: https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RegisterImage.html

      .. 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:: ena-support
         :type: bool
         :default: True

         Whether the image has support for the AWS Enhanced Networking
         Adapter (ENA).  Many newer operating systems include driver
         support as standard and some AWS instance types require it.

      .. 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-format
         :default: raw

         The image format that should be used when building and
         uploading or importing the image.

         .. value:: ova

            The OVA image format.

         .. value:: vhd

            The VHD image format.

         .. value:: vhdx

            The VHDX image format.

         .. value:: vmdk

            The VMDK image format.

         .. value:: raw

            A raw image.

         .. value:: snapshot

            Rather than producing an image artifact and
            uploading or importing it, this image is created by
            snapshotting a running instance.

      .. attr:: imds-http-tokens

         Specify whether IMDSv2 is required.  If this is omitted,
         then AWS defaults are used (usually equivalent to
         ``optional`` but may be influenced by the image used).

         .. value:: optional

            Allows usage of IMDSv2 but do not require it.  This
            sets the following metadata options:

            * `HttpTokens` is `optional`
            * `HttpEndpoint` is `enabled`

         .. value:: required

            Require IMDSv2.  This sets the following metadata
            options:

            * `HttpTokens` is `required`
            * `HttpEndpoint` is `enabled`

      .. attr:: imds-support
         :default: None

         Controls the usage of IMDSv2 on instances created from the
         image, This is only supported using the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

         .. value:: v2.0

            Enforces usage of IMDSv2 by default on instances
            created from the image.

         .. value:: null

            IMDSv2 is optional.

      .. attr:: import-method
         :default: snapshot

         The method to use when importing the image.

         .. value:: snapshot

            This method uploads the image file to AWS as a snapshot
            and then registers an AMI directly from the snapshot.
            This is faster compared to the `image` method and may be
            used with operating systems and versions that AWS does not
            otherwise support.  However, it is incompatible with some
            operating systems which require special licensing or other
            metadata in AWS.

         .. value:: image

            This method uploads the image file to AWS and performs
            an "image import" on the file.  This causes AWS to
            boot the image in a temporary VM and then take a
            snapshot of that VM which is then used as the basis of
            the AMI.  This is slower compared to the `snapshot`
            method and may only be used with operating systems and
            versions which AWS already supports.  This may be
            necessary in order to use Windows images.

         .. value:: ebs-direct

            This is similar to the `snapshot` method, but uses the
            `EBS direct API`_ instead of S3.  This may be faster and
            more efficient, but it may incur additional costs.

            .. _`EBS direct API`: https://docs.aws.amazon.com/ebs/latest/userguide/ebs-accessing-snapshot.html

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

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

      .. attr:: iops
         :type: int

         The number of I/O operations per second to be provisioned for
         the volume.  The default varies based on the volume type; see
         the documentation under `EBS volume type`_ for the specific
         volume type for details.

      .. 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:: throughput
         :type: int

         The throughput of the volume in MiB/s.  This is only valid for
         ``gp3`` volumes.

      .. 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

         The size of the root EBS volume, in GiB, for the
         image.  If omitted, the volume size reported for the
         imported snapshot will be used.  Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

      .. attr:: volume-type
         :type: str
         :default: gp3

         The root `EBS volume type`_ for the image.
         Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

         .. _`EBS volume type`: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html

   .. 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:: 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-filters
         :type: dict

         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.  Either this field or
         :attr:`provider[aws].images[cloud].image-id` must be
         provided.

         This field may be provided as a dictionary, or a list
         of dictionaries with the following keys:

         .. attr:: name
            :type: str

            The filter name. See `Boto describe images`_ for a list of
            valid filters.

            .. _`Boto describe images`: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.describe_images

         .. attr:: values
            :type: str

            A list of string values on which to filter.

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

         If this is provided, it is used to select the AMI
         from AWS by ID.  Either this field or
         :attr:`provider[aws].images[cloud].image-filters`
         must be provided.

      .. attr:: imds-http-tokens

         Specify whether IMDSv2 is required.  If this is omitted,
         then AWS defaults are used (usually equivalent to
         ``optional`` but may be influenced by the image used).

         .. value:: optional

            Allows usage of IMDSv2 but do not require it.  This
            sets the following metadata options:

            * `HttpTokens` is `optional`
            * `HttpEndpoint` is `enabled`

         .. value:: required

            Require IMDSv2.  This sets the following metadata
            options:

            * `HttpTokens` is `required`
            * `HttpEndpoint` is `enabled`

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

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

      .. attr:: iops
         :type: int

         The number of I/O operations per second to be provisioned for
         the volume.  The default varies based on the volume type; see
         the documentation under `EBS volume type`_ for the specific
         volume type for details.

      .. 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:: throughput
         :type: int

         The throughput of the volume in MiB/s.  This is only valid for
         ``gp3`` volumes.

      .. 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

         The size of the root EBS volume, in GiB, for the
         image.  If omitted, the volume size reported for the
         imported snapshot will be used.  Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

      .. attr:: volume-type
         :type: str
         :default: gp3

         The root `EBS volume type`_ for the image.
         Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

         .. _`EBS volume type`: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html

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

      These are the attributes available for a Zuul image.

      .. attr:: architecture
         :type: str
         :default: x86_64

         The architecture of the image.  See the `AWS RegisterImage API
         documentation`_ for valid values.

         .. _`AWS RegisterImage API documentation`: https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RegisterImage.html

      .. 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:: ena-support
         :type: bool
         :default: True

         Whether the image has support for the AWS Enhanced Networking
         Adapter (ENA).  Many newer operating systems include driver
         support as standard and some AWS instance types require it.

      .. 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-format
         :default: raw

         The image format that should be used when building and
         uploading or importing the image.

         .. value:: ova

            The OVA image format.

         .. value:: vhd

            The VHD image format.

         .. value:: vhdx

            The VHDX image format.

         .. value:: vmdk

            The VMDK image format.

         .. value:: raw

            A raw image.

         .. value:: snapshot

            Rather than producing an image artifact and
            uploading or importing it, this image is created by
            snapshotting a running instance.

      .. attr:: imds-http-tokens

         Specify whether IMDSv2 is required.  If this is omitted,
         then AWS defaults are used (usually equivalent to
         ``optional`` but may be influenced by the image used).

         .. value:: optional

            Allows usage of IMDSv2 but do not require it.  This
            sets the following metadata options:

            * `HttpTokens` is `optional`
            * `HttpEndpoint` is `enabled`

         .. value:: required

            Require IMDSv2.  This sets the following metadata
            options:

            * `HttpTokens` is `required`
            * `HttpEndpoint` is `enabled`

      .. attr:: imds-support
         :default: None

         Controls the usage of IMDSv2 on instances created from the
         image, This is only supported using the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

         .. value:: v2.0

            Enforces usage of IMDSv2 by default on instances
            created from the image.

         .. value:: null

            IMDSv2 is optional.

      .. attr:: import-method
         :default: snapshot

         The method to use when importing the image.

         .. value:: snapshot

            This method uploads the image file to AWS as a snapshot
            and then registers an AMI directly from the snapshot.
            This is faster compared to the `image` method and may be
            used with operating systems and versions that AWS does not
            otherwise support.  However, it is incompatible with some
            operating systems which require special licensing or other
            metadata in AWS.

         .. value:: image

            This method uploads the image file to AWS and performs
            an "image import" on the file.  This causes AWS to
            boot the image in a temporary VM and then take a
            snapshot of that VM which is then used as the basis of
            the AMI.  This is slower compared to the `snapshot`
            method and may only be used with operating systems and
            versions which AWS already supports.  This may be
            necessary in order to use Windows images.

         .. value:: ebs-direct

            This is similar to the `snapshot` method, but uses the
            `EBS direct API`_ instead of S3.  This may be faster and
            more efficient, but it may incur additional costs.

            .. _`EBS direct API`: https://docs.aws.amazon.com/ebs/latest/userguide/ebs-accessing-snapshot.html

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

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

      .. attr:: iops
         :type: int

         The number of I/O operations per second to be provisioned for
         the volume.  The default varies based on the volume type; see
         the documentation under `EBS volume type`_ for the specific
         volume type for details.

      .. 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:: throughput
         :type: int

         The throughput of the volume in MiB/s.  This is only valid for
         ``gp3`` volumes.

      .. 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

         The size of the root EBS volume, in GiB, for the
         image.  If omitted, the volume size reported for the
         imported snapshot will be used.  Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

      .. attr:: volume-type
         :type: str
         :default: gp3

         The root `EBS volume type`_ for the image.
         Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

         .. _`EBS volume type`: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html

   .. 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:: az
         :type: str

         Instances will be assigned to the specified availibility
         zone.  If omitted, AWS will select from the available
         zones.

      .. 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:: iam-instance-profile
         :type: dict

         Used to attach an IAM instance profile.
         Useful for giving access to services without needing any secrets.

         .. attr:: arn
            :type: str

            ARN identifier of the profile.  Mutually exclusive
            with
            :attr:`provider[aws].labels.iam-instance-profile.name`

         .. attr:: name
            :type: str

            Name of the instance profile.  Mutually exclusive with
            :attr:`provider[aws].labels.iam-instance-profile.arn`

      .. attr:: imds-http-tokens

         Specify whether IMDSv2 is required.  If this is omitted,
         then AWS defaults are used (usually equivalent to
         ``optional`` but may be influenced by the image used).

         .. value:: optional

            Allows usage of IMDSv2 but do not require it.  This
            sets the following metadata options:

            * `HttpTokens` is `optional`
            * `HttpEndpoint` is `enabled`

         .. value:: required

            Require IMDSv2.  This sets the following metadata
            options:

            * `HttpTokens` is `required`
            * `HttpEndpoint` is `enabled`

      .. attr:: iops
         :type: int

         The number of I/O operations per second to be provisioned for
         the volume.  The default varies based on the volume type; see
         the documentation under `EBS volume type`_ for the specific
         volume type for details.

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

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

      .. attr:: kms-key-id
         :type: str

         The KMS key id to use when launching instances from an
         encrypted image.  Typically only necessary when using
         images shared from a different AWS account.

      .. 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:: reuse
         :type: bool
         :default: False

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

      .. attr:: security-group-ids
         :type: str

         Specifies the security group IDs to assign to the node's
         network interfaces.

      .. 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:: subnet-ids
         :type: str

         Specifies the subnets to assign to the node's network interfaces.

      .. 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:: throughput
         :type: int

         The throughput of the volume in MiB/s.  This is only valid for
         ``gp3`` volumes.

      .. 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

         The size of the root EBS volume, in GiB, for the
         image.  If omitted, the volume size reported for the
         imported snapshot will be used.  Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

      .. attr:: volume-type
         :type: str
         :default: gp3

         The root `EBS volume type`_ for the image.
         Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

         .. _`EBS volume type`: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html

   .. attr:: labels
      :type: dict

      A list of labels associated with this provider.

      .. attr:: az
         :type: str

         Instances will be assigned to the specified availibility
         zone.  If omitted, AWS will select from the available
         zones.

      .. 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:: iam-instance-profile
         :type: dict

         Used to attach an IAM instance profile.
         Useful for giving access to services without needing any secrets.

         .. attr:: arn
            :type: str

            ARN identifier of the profile.  Mutually exclusive
            with
            :attr:`provider[aws].labels.iam-instance-profile.name`

         .. attr:: name
            :type: str

            Name of the instance profile.  Mutually exclusive with
            :attr:`provider[aws].labels.iam-instance-profile.arn`

      .. attr:: image
         :type: str

         The image to use with this label.

      .. attr:: imds-http-tokens

         Specify whether IMDSv2 is required.  If this is omitted,
         then AWS defaults are used (usually equivalent to
         ``optional`` but may be influenced by the image used).

         .. value:: optional

            Allows usage of IMDSv2 but do not require it.  This
            sets the following metadata options:

            * `HttpTokens` is `optional`
            * `HttpEndpoint` is `enabled`

         .. value:: required

            Require IMDSv2.  This sets the following metadata
            options:

            * `HttpTokens` is `required`
            * `HttpEndpoint` is `enabled`

      .. attr:: iops
         :type: int

         The number of I/O operations per second to be provisioned for
         the volume.  The default varies based on the volume type; see
         the documentation under `EBS volume type`_ for the specific
         volume type for details.

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

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

      .. attr:: kms-key-id
         :type: str

         The KMS key id to use when launching instances from an
         encrypted image.  Typically only necessary when using
         images shared from a different AWS account.

      .. 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:: reuse
         :type: bool
         :default: False

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

      .. attr:: security-group-ids
         :type: str

         Specifies the security group IDs to assign to the node's
         network interfaces.

      .. 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:: subnet-ids
         :type: str

         Specifies the subnets to assign to the node's network interfaces.

      .. 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:: throughput
         :type: int

         The throughput of the volume in MiB/s.  This is only valid for
         ``gp3`` volumes.

      .. 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

         The size of the root EBS volume, in GiB, for the
         image.  If omitted, the volume size reported for the
         imported snapshot will be used.  Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

      .. attr:: volume-type
         :type: str
         :default: gp3

         The root `EBS volume type`_ for the image.
         Only used with the
         :value:`provider[aws].images[zuul].import-method.snapshot` or
         :value:`provider[aws].images[zuul].import-method.ebs-direct`
         import methods.

         .. _`EBS volume type`: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html

   .. 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:: object-storage
      :type: dict

      Configuration options related to object storage used
      for image management.

      .. attr:: bucket-name
         :type: str

         The name of the S3 bucket that should be used when
         importing Zuul images.

   .. 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[aws].section`

   .. attr:: region
      :type: str

      The name of the `AWS region`_ to interact with.

      .. _`AWS region`: https://docs.aws.amazon.com/general/latest/gr/rande.html

   .. 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.

      In addition to the options listed below, it is
      possible to configure a limit for any of the quota
      codes supported by AWS.  

      .. 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:: section
      :type: str

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


