OpenStack

Zuul can use OpenStack clouds as a source for build nodes.

Information about OpenStack clouds, including authentication information, may be provided via a configuration file (e.g., clouds.yaml) or environment variables. See the OpenStack SDK for more information.

Connection Configuration

The supported options in zuul.conf connections are:

<openstack connection>

<openstack connection>.driver (required)

openstack: The connection must set driver=openstack for OpenStack connections.

<openstack connection>.client_config_file: A path to a configuration file (e.g., clouds.yaml) with connection information for one or more OpenStack clouds.

<openstack connection>.cloud (required): The name of the OpenStack cloud (as it appears in the client config file).

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

Provider Configuration

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

provider[openstack] Type: dict

The attributes available for configuring an OpenStack provider are below.

provider[openstack].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[openstack].connection Type: str: The name of the connection to use. This attribute is only used by section objects.

provider[openstack].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[openstack].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[openstack].flavor-defaults.public-ipv4 Default: False Type: bool: Whether a public IPv4 address should be attached to nodes.

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

provider[openstack].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[openstack].flavor-defaults.volume-size Type: int: When booting an image from volume, this indicates the size of the created volume, in GB.

provider[openstack].flavors Type: dict

A list of flavors associated with this provider.

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

provider[openstack].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[openstack].flavors.flavor-name Type: str: Name or id of the OpenStack flavor to use.

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

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

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

provider[openstack].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[openstack].flavors.volume-size Type: int: When booting an image from volume, this indicates the size of the created volume, in GB.

provider[openstack].floating-ip-cleanup Default: False Type: bool: 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.

provider[openstack].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[openstack].image-defaults.config-drive Default: True Type: bool: Whether config drive should be used for the cloud image.

provider[openstack].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[openstack].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[openstack].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[openstack].image-defaults.import-timeout Default: 300 Type: int: The limit on the amount of time a successful image import can take.

provider[openstack].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[openstack].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[openstack].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[openstack].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[openstack].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[openstack].image-defaults.username Type: str: The username Zuul should use when connecting to the node.

provider[openstack].image-defaults.volume-size Type: int: When booting an image from volume, this indicates the size of the created volume, in GB.

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

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

These are the attributes available for a cloud image.

provider[openstack].images[cloud].config-drive Default: True Type: bool: Whether config drive should be used for the cloud image.

provider[openstack].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[openstack].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[openstack].images[cloud].description Type: str: A textual description of the image for reference purposes.

provider[openstack].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[openstack].images[cloud].image-id Type: str: The ID of the cloud provider’s image.

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

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

provider[openstack].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[openstack].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[openstack].images[cloud].type

The type of image.

cloud: An existing image available in the cloud.

provider[openstack].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[openstack].images[cloud].username Type: str: The username Zuul should use when connecting to the node.

provider[openstack].images[cloud].volume-size Type: int: When booting an image from volume, this indicates the size of the created volume, in GB.

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

These are the attributes available for a Zuul image.

provider[openstack].images[zuul].config-drive Default: True Type: bool: Whether config drive should be used for the cloud image.

provider[openstack].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[openstack].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[openstack].images[zuul].description Type: str: A textual description of the image for reference purposes.

provider[openstack].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[openstack].images[zuul].import-timeout Default: 300 Type: int: The limit on the amount of time a successful image import can take.

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

provider[openstack].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[openstack].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[openstack].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[openstack].images[zuul].type

The type of image.

zuul: An image managed by Zuul.

provider[openstack].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[openstack].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[openstack].images[zuul].username Type: str: The username Zuul should use when connecting to the node.

provider[openstack].images[zuul].volume-size Type: int: When booting an image from volume, this indicates the size of the created volume, in GB.

provider[openstack].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[openstack].label-defaults.auto-floating-ip Default: True Type: bool: Whether to automatically allocate and assign a floating IP for each node.

provider[openstack].label-defaults.az Type: str: Servers will be assigned to the specified availibility zone. If omitted, one will be chosen at random.

provider[openstack].label-defaults.boot-from-volume Default: False Type: bool: Whether to create a volume from the image and boot the node from it.

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

provider[openstack].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[openstack].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[openstack].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[openstack].label-defaults.key-name Type: str: The name of a keypair that will be used when booting the node.

provider[openstack].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[openstack].label-defaults.max-ready-age Default: 0 Type: int: The time (in seconds) an unassigned node should stay in ready state.

provider[openstack].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[openstack].label-defaults.networks Type: str: The OpenStack networks to associate with the node.

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

provider[openstack].label-defaults.security-groups Type: str: Specify custom networks to be attached to each node. Specify the name or id of the network as a string.

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

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

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

provider[openstack].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[openstack].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[openstack].label-defaults.volume-size Type: int: When booting an image from volume, this indicates the size of the created volume, in GB.

provider[openstack].labels Type: dict

A list of labels associated with this provider.

provider[openstack].labels.auto-floating-ip Default: True Type: bool: Whether to automatically allocate and assign a floating IP for each node.

provider[openstack].labels.az Type: str: Servers will be assigned to the specified availibility zone. If omitted, one will be chosen at random.

provider[openstack].labels.boot-from-volume Default: False Type: bool: Whether to create a volume from the image and boot the node from it.

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

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

provider[openstack].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[openstack].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[openstack].labels.flavor Type: str: The flavor to use with this label.

provider[openstack].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[openstack].labels.image Type: str: The image to use with this label.

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

provider[openstack].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[openstack].labels.max-ready-age Default: 0 Type: int: The time (in seconds) an unassigned node should stay in ready state.

provider[openstack].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[openstack].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[openstack].labels.name Type: str: The name of the label. Used to refer to the label in Zuul configuration.

provider[openstack].labels.networks Type: str: The OpenStack networks to associate with the node.

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

provider[openstack].labels.security-groups Type: str: Specify custom networks to be attached to each node. Specify the name or id of the network as a string.

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

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

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

provider[openstack].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[openstack].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[openstack].labels.volume-size Type: int: When booting an image from volume, this indicates the size of the created volume, in GB.

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

provider[openstack].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[openstack].name Type: str: The name of the provider. Used to refer to the provider in Zuul configuration.

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

provider[openstack].port-cleanup-interval Default: 600 Type: int: 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.

provider[openstack].region Type: str: The region name if the provider cloud has multiple regions.

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

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

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

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

provider[openstack].resource-limits.volume-gb Type: int: The amount of volume storage in GB.

provider[openstack].resource-limits.volumes Type: int: The number of volumes.

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