AWS

Zuul can use AWS as a source for build nodes.

If using the AWS driver to upload images, see VM Import/Export service role for information on configuring the required permissions in AWS. You must also create an S3 Bucket for use by Zuul if uploading images (except when using the ebs-direct upload method).

A number of methods for configuration authentication are available:

Supplying values directly in zuul.conf
A shared credential file
Environment variables

Zuul will try to obtain credential information from those sources in that order.

Connection Configuration

The supported options in zuul.conf connections are:

<aws connection>

<aws connection>.driver (required)

aws: The connection must set driver=aws for AWS connections.

<aws connection>.shared_credentials_file: A path to a configuration file with shared access credentials. If this is supplied, no other credential settings need to be present.

<aws connection>.access_key_id: The AWS access key id.

<aws connection>.secret_access_key: The AWS secret access key.

<aws connection>.profile: The AWS profile.

<aws connection>.rate Default: 2: The API rate limit (in requests per second) to use when performing API calls with AWS.

Provider Configuration

The aws driver adds the following options to the provider and section configurations:

provider[aws] Type: dict

The attributes available for configuring an AWS provider are below.

provider[aws].abstract Default: False Type: bool: Whether a section is intended to be inherited by another section or a 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.

provider[aws].connection Type: str: The name of the connection to use. This attribute is only used by section objects.

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

provider[aws].flavor-defaults.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.

True: The flavor may not be updated or overidden.

False: The flavor may be updated or overidden.

allow-override: The flavor may not be updated by flavor-defaults but may be explicitly overidden by redefining it in a new ‘flavor’ entry.

provider[aws].flavor-defaults.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).

optional

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

HttpTokens is optional
HttpEndpoint is enabled

required

Require IMDSv2. This sets the following metadata options:

HttpTokens is required
HttpEndpoint is enabled

provider[aws].flavor-defaults.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.

provider[aws].flavor-defaults.public-ipv4 Default: False Type: bool: Whether a public IPv4 address should be attached to nodes.

provider[aws].flavor-defaults.public-ipv6 Default: False Type: bool: Whether a public IPv6 address should be attached to nodes.

provider[aws].flavor-defaults.throughput Type: int: The throughput of the volume in MiB/s. This is only valid for gp3 volumes.

provider[aws].flavor-defaults.userdata Type: str: A string of userdata for a node. Systems such as “cloud-init” may use this to configure the node on boot.

provider[aws].flavor-defaults.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 snapshot or ebs-direct import methods.

provider[aws].flavor-defaults.volume-type Default: gp3 Type: str: The root EBS volume type for the image. Only used with the snapshot or ebs-direct import methods.

provider[aws].flavors Type: dict

A list of flavors associated with this provider.

provider[aws].flavors.dedicated-host Default: False Type: bool

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 provider[aws].labels.slots and provider[aws].labels.reuse.

If this option is set, the spot option is not available, and provider[aws].labels.az option is required.

provider[aws].flavors.description Type: str: A textual description of the image for reference purposes.

provider[aws].flavors.ebs-optimized Default: False Type: bool: Indicates whether EBS optimization (additional, dedicated throughput between Amazon EC2 and Amazon EBS) should be enabled for the instance.

provider[aws].flavors.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.

True: The flavor may not be updated or overidden.

False: The flavor may be updated or overidden.

allow-override: The flavor may not be updated by flavor-defaults but may be explicitly overidden by redefining it in a new ‘flavor’ entry.

provider[aws].flavors.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 provider[aws].flavors.instance-type.

provider[aws].flavors.fleet.allocation-strategy

The allocation strategy to use when launching the instance.

prioritized: The prioritized allocation strategy. Available for on-demand instances

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

capacity-optimized: The capacity-optimized allocation strategy. Available for spot instances

diversified: The diversified allocation strategy. Available for spot instances

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

provider[aws].flavors.fleet.instance-types Type: str: A list of instance types from which AWS may select when launching the instance.

provider[aws].flavors.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).

optional

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

HttpTokens is optional
HttpEndpoint is enabled

required

Require IMDSv2. This sets the following metadata options:

HttpTokens is required
HttpEndpoint is enabled

provider[aws].flavors.instance-type Type: str: Name of the AWS instance type to use.. Mutually exclusive with provider[aws].flavors.fleet.

provider[aws].flavors.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.

provider[aws].flavors.market-type Default: on-demand

Whether to request an on-demand or spot instance.

on-demand: This is the typical EC2 instance where continued availability is guaranteed after allocation.

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.

provider[aws].flavors.name Type: str: The name of the flavor. Used to refer to the flavor in Zuul configuration.

provider[aws].flavors.public-ipv4 Default: False Type: bool: Whether a public IPv4 address should be attached to nodes.

provider[aws].flavors.public-ipv6 Default: False Type: bool: Whether a public IPv6 address should be attached to nodes.

provider[aws].flavors.throughput Type: int: The throughput of the volume in MiB/s. This is only valid for gp3 volumes.

provider[aws].flavors.userdata Type: str: A string of userdata for a node. Systems such as “cloud-init” may use this to configure the node on boot.

provider[aws].flavors.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 snapshot or ebs-direct import methods.

provider[aws].flavors.volume-type Default: gp3 Type: str: The root EBS volume type for the image. Only used with the snapshot or ebs-direct import methods.

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

provider[aws].image-defaults.architecture Default: x86_64 Type: str: The architecture of the image. See the AWS RegisterImage API documentation for valid values.

provider[aws].image-defaults.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’.

provider[aws].image-defaults.connection-type

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

winrm: A winrm connection.

ssh: An ssh connection.

provider[aws].image-defaults.ena-support Default: True Type: bool: 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.

provider[aws].image-defaults.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.

True: The label may not be updated or overidden.

False: The label may be updated or overidden.

allow-override: The label may not be updated by label-defaults but may be explicitly overidden by redefining it in a new ‘label’ entry.

provider[aws].image-defaults.image-format Default: raw

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

ova: The OVA image format.

vhd: The VHD image format.

vhdx: The VHDX image format.

vmdk: The VMDK image format.

raw: A raw image.

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

provider[aws].image-defaults.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).

optional

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

HttpTokens is optional
HttpEndpoint is enabled

required

Require IMDSv2. This sets the following metadata options:

HttpTokens is required
HttpEndpoint is enabled

provider[aws].image-defaults.imds-support Default: None

Controls the usage of IMDSv2 on instances created from the image, This is only supported using the snapshot or ebs-direct import methods.

v2.0: Enforces usage of IMDSv2 by default on instances created from the image.

null: IMDSv2 is optional.

provider[aws].image-defaults.import-method Default: snapshot

The method to use when importing the image.

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.

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.

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.

provider[aws].image-defaults.import-timeout Default: 300 Type: int: The limit on the amount of time a successful image import can take.

provider[aws].image-defaults.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.

provider[aws].image-defaults.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.

provider[aws].image-defaults.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.

provider[aws].image-defaults.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.

provider[aws].image-defaults.throughput Type: int: The throughput of the volume in MiB/s. This is only valid for gp3 volumes.

provider[aws].image-defaults.upload-methods Default: ['copy', 'import', 'upload'] Type: list

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

copy: Copy the image from another provider if available.

import: Import the image directly from its storage location.

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

provider[aws].image-defaults.userdata Type: str: A string of userdata for a node. Systems such as “cloud-init” may use this to configure the node on boot.

provider[aws].image-defaults.username Type: str: The username Zuul should use when connecting to the node.

provider[aws].image-defaults.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 snapshot or ebs-direct import methods.

provider[aws].image-defaults.volume-type Default: gp3 Type: str: The root EBS volume type for the image. Only used with the snapshot or ebs-direct import methods.

provider[aws].images Type: list: A list of images associated with this provider.

provider[aws].images[cloud] Type: dict

These are the attributes available for a cloud image.

provider[aws].images[cloud].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’.

provider[aws].images[cloud].connection-type

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

winrm: A winrm connection.

ssh: An ssh connection.

provider[aws].images[cloud].description Type: str: A textual description of the image for reference purposes.

provider[aws].images[cloud].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.

True: The label may not be updated or overidden.

False: The label may be updated or overidden.

allow-override: The label may not be updated by label-defaults but may be explicitly overidden by redefining it in a new ‘label’ entry.

provider[aws].images[cloud].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 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:

provider[aws].images[cloud].image-filters.name Type: str: The filter name. See Boto describe images for a list of valid filters.

provider[aws].images[cloud].image-filters.values Type: str: A list of string values on which to filter.

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

provider[aws].images[cloud].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).

optional

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

HttpTokens is optional
HttpEndpoint is enabled

required

Require IMDSv2. This sets the following metadata options:

HttpTokens is required
HttpEndpoint is enabled

provider[aws].images[cloud].import-timeout Default: 300 Type: int: The limit on the amount of time a successful image import can take.

provider[aws].images[cloud].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.

provider[aws].images[cloud].name Type: str: The name of the image. Used to refer to the image in Zuul configuration.

provider[aws].images[cloud].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.

provider[aws].images[cloud].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.

provider[aws].images[cloud].throughput Type: int: The throughput of the volume in MiB/s. This is only valid for gp3 volumes.

provider[aws].images[cloud].type

The type of image.

cloud: An existing image available in the cloud.

provider[aws].images[cloud].userdata Type: str: A string of userdata for a node. Systems such as “cloud-init” may use this to configure the node on boot.

provider[aws].images[cloud].username Type: str: The username Zuul should use when connecting to the node.

provider[aws].images[cloud].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 snapshot or ebs-direct import methods.

provider[aws].images[cloud].volume-type Default: gp3 Type: str: The root EBS volume type for the image. Only used with the snapshot or ebs-direct import methods.

provider[aws].images[zuul] Type: dict

These are the attributes available for a Zuul image.

provider[aws].images[zuul].architecture Default: x86_64 Type: str: The architecture of the image. See the AWS RegisterImage API documentation for valid values.

provider[aws].images[zuul].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’.

provider[aws].images[zuul].connection-type

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

winrm: A winrm connection.

ssh: An ssh connection.

provider[aws].images[zuul].description Type: str: A textual description of the image for reference purposes.

provider[aws].images[zuul].ena-support Default: True Type: bool: 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.

provider[aws].images[zuul].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.

True: The label may not be updated or overidden.

False: The label may be updated or overidden.

allow-override: The label may not be updated by label-defaults but may be explicitly overidden by redefining it in a new ‘label’ entry.

provider[aws].images[zuul].image-format Default: raw

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

ova: The OVA image format.

vhd: The VHD image format.

vhdx: The VHDX image format.

vmdk: The VMDK image format.

raw: A raw image.

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

provider[aws].images[zuul].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).

optional

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

HttpTokens is optional
HttpEndpoint is enabled

required

Require IMDSv2. This sets the following metadata options:

HttpTokens is required
HttpEndpoint is enabled

provider[aws].images[zuul].imds-support Default: None

Controls the usage of IMDSv2 on instances created from the image, This is only supported using the snapshot or ebs-direct import methods.

v2.0: Enforces usage of IMDSv2 by default on instances created from the image.

null: IMDSv2 is optional.

provider[aws].images[zuul].import-method Default: snapshot

The method to use when importing the image.

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.

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.

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.

provider[aws].images[zuul].import-timeout Default: 300 Type: int: The limit on the amount of time a successful image import can take.

provider[aws].images[zuul].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.

provider[aws].images[zuul].name Type: str: The name of the image. Used to refer to the image in Zuul configuration.

provider[aws].images[zuul].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.

provider[aws].images[zuul].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.

provider[aws].images[zuul].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.

provider[aws].images[zuul].throughput Type: int: The throughput of the volume in MiB/s. This is only valid for gp3 volumes.

provider[aws].images[zuul].type

The type of image.

zuul: An image managed by Zuul.

provider[aws].images[zuul].upload-methods Default: ['copy', 'import', 'upload'] Type: list

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

copy: Copy the image from another provider if available.

import: Import the image directly from its storage location.

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

provider[aws].images[zuul].userdata Type: str: A string of userdata for a node. Systems such as “cloud-init” may use this to configure the node on boot.

provider[aws].images[zuul].username Type: str: The username Zuul should use when connecting to the node.

provider[aws].images[zuul].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 snapshot or ebs-direct import methods.

provider[aws].images[zuul].volume-type Default: gp3 Type: str: The root EBS volume type for the image. Only used with the snapshot or ebs-direct import methods.

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

provider[aws].label-defaults.az Type: str: Instances will be assigned to the specified availibility zone. If omitted, AWS will select from the available zones.

provider[aws].label-defaults.boot-timeout Default: 300 Type: int: The time (in seconds) to wait for a node to boot.

provider[aws].label-defaults.executor-zone Type: str: Specify that a Zuul executor in the specified zone is used to run jobs with nodes from this label.

provider[aws].label-defaults.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.

True: The label may not be updated or overidden.

False: The label may be updated or overidden.

allow-override: The label may not be updated by label-defaults but may be explicitly overidden by redefining it in a new ‘label’ entry.

provider[aws].label-defaults.host-key-checking Default: True Type: bool: 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.

provider[aws].label-defaults.iam-instance-profile Type: dict

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

provider[aws].label-defaults.iam-instance-profile.arn Type: str: ARN identifier of the profile. Mutually exclusive with provider[aws].labels.iam-instance-profile.name

provider[aws].label-defaults.iam-instance-profile.name Type: str: Name of the instance profile. Mutually exclusive with provider[aws].labels.iam-instance-profile.arn

provider[aws].label-defaults.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).

optional

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

HttpTokens is optional
HttpEndpoint is enabled

required

Require IMDSv2. This sets the following metadata options:

HttpTokens is required
HttpEndpoint is enabled

provider[aws].label-defaults.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.

provider[aws].label-defaults.key-name Type: str: The name of a keypair that will be used when booting the node.

provider[aws].label-defaults.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.

provider[aws].label-defaults.max-age Default: 0 Type: int: The time (in seconds) since creation that a node may be available for use. Ready nodes older than this time will be deleted.

provider[aws].label-defaults.max-ready-age Default: 0 Type: int: The time (in seconds) an unassigned node should stay in ready state.

provider[aws].label-defaults.min-retention-time Default: 0 Type: int

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.

provider[aws].label-defaults.reuse Default: False Type: bool: Should the node be reused (True) or deleted (False) after use.

provider[aws].label-defaults.security-group-ids Type: str: Specifies the security group IDs to assign to the node’s network interfaces.

provider[aws].label-defaults.slots Default: 1 Type: int: How many jobs are permitted run on the same node simultaneously.

provider[aws].label-defaults.snapshot-expiration Default: 604800 Type: int: The time (in seconds) until a snapshot expires.

provider[aws].label-defaults.snapshot-timeout Default: 3600 Type: int: The time (in seconds) to wait for a snapshot to complete.

provider[aws].label-defaults.subnet-ids Type: str: Specifies the subnets to assign to the node’s network interfaces.

provider[aws].label-defaults.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.

provider[aws].label-defaults.throughput Type: int: The throughput of the volume in MiB/s. This is only valid for gp3 volumes.

provider[aws].label-defaults.userdata Type: str: A string of userdata for a node. Systems such as “cloud-init” may use this to configure the node on boot.

provider[aws].label-defaults.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 snapshot or ebs-direct import methods.

provider[aws].label-defaults.volume-type Default: gp3 Type: str: The root EBS volume type for the image. Only used with the snapshot or ebs-direct import methods.

provider[aws].labels Type: dict

A list of labels associated with this provider.

provider[aws].labels.az Type: str: Instances will be assigned to the specified availibility zone. If omitted, AWS will select from the available zones.

provider[aws].labels.boot-timeout Default: 300 Type: int: The time (in seconds) to wait for a node to boot.

provider[aws].labels.description Type: str: A textual description of the label for reference purposes.

provider[aws].labels.executor-zone Type: str: Specify that a Zuul executor in the specified zone is used to run jobs with nodes from this label.

provider[aws].labels.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.

True: The label may not be updated or overidden.

False: The label may be updated or overidden.

allow-override: The label may not be updated by label-defaults but may be explicitly overidden by redefining it in a new ‘label’ entry.

provider[aws].labels.flavor Type: str: The flavor to use with this label.

provider[aws].labels.host-key-checking Default: True Type: bool: 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.

provider[aws].labels.iam-instance-profile Type: dict

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

provider[aws].labels.iam-instance-profile.arn Type: str: ARN identifier of the profile. Mutually exclusive with provider[aws].labels.iam-instance-profile.name

provider[aws].labels.iam-instance-profile.name Type: str: Name of the instance profile. Mutually exclusive with provider[aws].labels.iam-instance-profile.arn

provider[aws].labels.image Type: str: The image to use with this label.

provider[aws].labels.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).

optional

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

HttpTokens is optional
HttpEndpoint is enabled

required

Require IMDSv2. This sets the following metadata options:

HttpTokens is required
HttpEndpoint is enabled

provider[aws].labels.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.

provider[aws].labels.key-name Type: str: The name of a keypair that will be used when booting the node.

provider[aws].labels.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.

provider[aws].labels.max-age Default: 0 Type: int: The time (in seconds) since creation that a node may be available for use. Ready nodes older than this time will be deleted.

provider[aws].labels.max-ready-age Default: 0 Type: int: The time (in seconds) an unassigned node should stay in ready state.

provider[aws].labels.min-ready Default: 0 Type: int: 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.

provider[aws].labels.min-retention-time Default: 0 Type: int

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.

provider[aws].labels.name Type: str: The name of the label. Used to refer to the label in Zuul configuration.

provider[aws].labels.reuse Default: False Type: bool: Should the node be reused (True) or deleted (False) after use.

provider[aws].labels.security-group-ids Type: str: Specifies the security group IDs to assign to the node’s network interfaces.

provider[aws].labels.slots Default: 1 Type: int: How many jobs are permitted run on the same node simultaneously.

provider[aws].labels.snapshot-expiration Default: 604800 Type: int: The time (in seconds) until a snapshot expires.

provider[aws].labels.snapshot-timeout Default: 3600 Type: int: The time (in seconds) to wait for a snapshot to complete.

provider[aws].labels.subnet-ids Type: str: Specifies the subnets to assign to the node’s network interfaces.

provider[aws].labels.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.

provider[aws].labels.throughput Type: int: The throughput of the volume in MiB/s. This is only valid for gp3 volumes.

provider[aws].labels.userdata Type: str: A string of userdata for a node. Systems such as “cloud-init” may use this to configure the node on boot.

provider[aws].labels.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 snapshot or ebs-direct import methods.

provider[aws].labels.volume-type Default: gp3 Type: str: The root EBS volume type for the image. Only used with the snapshot or ebs-direct import methods.

provider[aws].launch-attempts Default: 3 Type: int: The number of times to attempt launching a node before considering the request failed.

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

provider[aws].name Type: str: The name of the provider. Used to refer to the provider in Zuul configuration.

provider[aws].object-storage Type: dict

Configuration options related to object storage used for image management.

provider[aws].object-storage.bucket-name Type: str: The name of the S3 bucket that should be used when importing Zuul images.

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

provider[aws].region Type: str: The name of the AWS region to interact with.

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

provider[aws].resource-limits.cores Type: int: The number of cores.

provider[aws].resource-limits.instances Type: int: The number of instances.

provider[aws].resource-limits.ram Type: int: The amount of ram, in MiB.

provider[aws].section Type: str: The name of the section from which to inherit.