OpenStack Driver
Selecting the OpenStack driver adds the following options to the providers section of the configuration.
-
providers.[openstack]
Specifying the
openstack
driver for a provider adds the following keys to the providers configuration.Note
For documentation purposes the option names are prefixed
providers.[openstack]
to disambiguate from other drivers, but[openstack]
is not required in the configuration (e.g. belowproviders.[openstack].cloud
refers to thecloud
key in theproviders
section when theopenstack
driver is selected).An OpenStack provider’s resources are partitioned into groups called “pools” (see providers.[openstack].pools for details), and within a pool, the node types which are to be made available are listed (see providers.[openstack].pools.labels for details).
Within each OpenStack provider the available Nodepool image types are defined (see providers.[openstack].diskimages).
providers: - name: provider1 driver: openstack cloud: example region-name: 'region1' rate: 1.0 boot-timeout: 120 launch-timeout: 900 launch-retries: 3 image-name-format: '{image_name}-{timestamp}' hostname-format: '{label.name}-{provider.name}-{node.id}' post-upload-hook: /usr/bin/custom-hook diskimages: - name: trusty meta: key: value key2: value - name: precise - name: devstack-trusty pools: - name: main max-servers: 96 availability-zones: - az1 networks: - some-network-name security-groups: - zuul-security-group labels: - name: trusty min-ram: 8192 diskimage: trusty console-log: True - name: precise min-ram: 8192 diskimage: precise - name: devstack-trusty min-ram: 8192 diskimage: devstack-trusty - name: provider2 driver: openstack cloud: example2 region-name: 'region1' rate: 1.0 image-name-format: '{image_name}-{timestamp}' hostname-format: '{label.name}-{provider.name}-{node.id}' diskimages: - name: precise meta: key: value key2: value pools: - name: main max-servers: 96 labels: - name: trusty min-ram: 8192 diskimage: trusty - name: precise min-ram: 8192 diskimage: precise - name: devstack-trusty min-ram: 8192 diskimage: devstack-trusty
-
providers.[openstack].cloud (required)
Type: string Name of a cloud configured in
clouds.yaml
.The instances spawned by nodepool will inherit the default security group of the project specified in the cloud definition in clouds.yaml (if other values not specified). This means that when working with Zuul, for example, SSH traffic (TCP/22) must be allowed in the project’s default security group for Zuul to be able to reach instances.
More information about the contents of clouds.yaml can be found in the openstacksdk documentation.
-
providers.[openstack].boot-timeout
Default:60
Type: int seconds Once an instance is active, how long to try connecting to the image via SSH. If the timeout is exceeded, the node launch is aborted and the instance deleted.
-
providers.[openstack].launch-timeout
Default:3600
Type: int seconds The time to wait from issuing the command to create a new instance until that instance is reported as “active”. If the timeout is exceeded, the node launch is aborted and the instance deleted.
-
providers.[openstack].nodepool-id
Default:None
Type: string Deprecated
A unique string to identify which nodepool instances is using a provider. This is useful if you want to configure production and development instances of nodepool but share the same provider.
-
providers.[openstack].launch-retries
Default:3
Type: int The number of times to retry launching a server before considering the job failed.
-
providers.[openstack].region-name
Type: string The region name if the provider cloud has multiple regions.
-
providers.[openstack].hostname-format
Default:{label.name}-{provider.name}-{node.id}
Type: string Hostname template to use for the spawned instance.
-
providers.[openstack].image-name-format
Default:{image_name}-{timestamp}
Type: string Format for image names that are uploaded to providers.
-
providers.[openstack].post-upload-hook
Default:None
Type: string Filename of an optional script that can be called after an image has been uploaded to a provider but before it is taken into use. This is useful to perform last minute validation tests before an image is really used for build nodes. The script will be called as follows:
<SCRIPT> <PROVIDER> <EXTERNAL_IMAGE_ID> <LOCAL_IMAGE_FILENAME>
If the script returns with result code 0 it is treated as successful otherwise it is treated as failed and the image gets deleted.
-
providers.[openstack].rate
Default:1
Type: int seconds In seconds, amount to wait between operations on the provider.
-
providers.[openstack].clean-floating-ips
Default:True
Type: bool If it is set to True, nodepool will assume it is the only user of the OpenStack project and will attempt to clean unattached floating ips that may have leaked around restarts.
-
providers.[openstack].port-cleanup-interval
Default:600
Type: int seconds If greater than 0, nodepool will assume it is the only user of the OpenStack project and will attempt to clean ports in DOWN state after the cleanup interval has elapsed. This value can be reduced if the instance spawn time on the provider is reliably quicker.
-
providers.[openstack].diskimages
Type: list Each entry in a provider’s diskimages section must correspond to an entry in diskimages. Such an entry indicates that the corresponding diskimage should be uploaded for use in this provider. Additionally, any nodes that are created using the uploaded image will have the associated attributes (such as flavor or metadata).
If an image is removed from this section, any previously uploaded images will be deleted from the provider.
diskimages: - name: precise pause: False meta: key: value key2: value - name: windows connection-type: winrm connection-port: 5986
Each entry is a dictionary with the following keys
-
providers.[openstack].diskimages.name (required)
Type: string Identifier to refer this image from providers.[openstack].pools.labels and diskimages sections.
-
providers.[openstack].diskimages.pause
Default:False
Type: bool When set to True, nodepool-builder will not upload the image to the provider.
-
providers.[openstack].diskimages.config-drive
Default:unset
Type: bool Whether config drive should be used for the image. Defaults to unset which will use the cloud’s default behavior.
-
providers.[openstack].diskimages.meta
Type: dict Arbitrary key/value metadata to store as glance image properties.
-
providers.[openstack].diskimages.connection-type
Type: string The connection type that a consumer should use when connecting to the node. For most diskimages this is not necessary. However when creating Windows images this could be
winrm
to enable access via ansible.
-
providers.[openstack].diskimages.connection-port
Default:22 / 5986
Type: int The port that a consumer should use when connecting to the node. For most diskimages this is not necessary. This defaults to 22 for ssh and 5986 for winrm.
-
providers.[openstack].diskimages.name (required)
-
providers.[openstack].cloud-images
Type: list Each entry in this section must refer to an entry in the labels section.
cloud-images: - name: trusty-external config-drive: False - name: windows-external connection-type: winrm connection-port: 5986
Each entry is a dictionary with the following keys
-
providers.[openstack].cloud-images.name (required)
Type: string Identifier to refer this cloud-image from labels section. Since this name appears elsewhere in the nodepool configuration file, you may want to use your own descriptive name here and use one of
image-id
orimage-name
to specify the cloud image so that if the image name or id changes on the cloud, the impact to your Nodepool configuration will be minimal. However, if neither of those attributes are provided, this is also assumed to be the image name or ID in the cloud.
-
providers.[openstack].cloud-images.config-drive
Default:unset
Type: bool Whether config drive should be used for the cloud image. Defaults to unset which will use the cloud’s default behavior.
-
providers.[openstack].cloud-images.image-id
Type: str If this is provided, it is used to select the image from the cloud provider by ID, rather than name. Mutually exclusive with providers.[openstack].cloud-images.image-name
-
providers.[openstack].cloud-images.image-name
Type: str If this is provided, it is used to select the image from the cloud provider by this name or ID. Mutually exclusive with providers.[openstack].cloud-images.image-id
-
providers.[openstack].cloud-images.username
Type: str The username that a consumer should use when connecting to the node.
-
providers.[openstack].cloud-images.python-path
Default:auto
Type: str The path of the default python interpreter. Used by Zuul to set
ansible_python_interpreter
. The special valueauto
will direct Zuul to use inbuilt Ansible logic to select the interpreter on Ansible >=2.8, and default to/usr/bin/python2
for earlier versions.
-
providers.[openstack].cloud-images.shell-type
Default:sh
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 usedFor a windows image with the experimental connection-type
ssh
, in which casecmd
orpowershell
should be set and reflect the node’sDefaultShell
configuration.If the default shell is not Bourne compatible (sh), but instead e.g.
csh
orfish
, and the user is aware that there is a long-standing issue withansible_shell_type
in combination withbecome
-
providers.[openstack].cloud-images.connection-type
Type: str The connection type that a consumer should use when connecting to the node. For most diskimages this is not necessary. However when creating Windows images this could be ‘winrm’ to enable access via ansible.
-
providers.[openstack].cloud-images.connection-port
Default:22/ 5986
Type: int The port that a consumer should use when connecting to the node. For most diskimages this is not necessary. This defaults to 22 for ssh and 5986 for winrm.
-
providers.[openstack].cloud-images.name (required)
-
providers.[openstack].pools
Type: list A pool defines a group of resources from an OpenStack provider. Each pool has a maximum number of nodes which can be launched from it, along with a number of cloud-related attributes used when launching nodes.
pools: - name: main max-servers: 96 availability-zones: - az1 networks: - some-network-name security-groups: - zuul-security-group auto-floating-ip: False host-key-checking: True node-attributes: key1: value1 key2: value2 labels: - name: trusty min-ram: 8192 diskimage: trusty console-log: True - name: precise min-ram: 8192 diskimage: precise - name: devstack-trusty min-ram: 8192 diskimage: devstack-trusty
Each entry is a dictionary with the following keys
-
providers.[openstack].pools.name (required)
Type: string Pool name
-
providers.[openstack].pools.priority
Default:100
Type: int The priority of this provider pool (a lesser number is a higher priority). Nodepool launchers will yield requests to other provider pools with a higher priority as long as they are not paused. This means that in general, higher priority pools will reach quota first before lower priority pools begin to be used.
This setting may be specified at the provider level in order to apply to all pools within that provider, or it can be overridden here for a specific pool.
-
providers.[openstack].pools.node-attributes
Type: dict A dictionary of key-value pairs that will be stored with the node data in ZooKeeper. The keys and values can be any arbitrary string.
-
providers.[openstack].pools.max-cores
Type: int Maximum number of cores usable from this pool. This can be used to limit usage of the tenant. If not defined nodepool can use all cores up to the quota of the tenant.
-
providers.[openstack].pools.max-servers
Type: int Maximum number of servers spawnable from this pool. This can be used to limit the number of servers. If not defined nodepool can create as many servers the tenant allows.
-
providers.[openstack].pools.max-ram
Type: int Maximum ram usable from this pool. This can be used to limit the amount of ram allocated by nodepool. If not defined nodepool can use as much ram as the tenant allows.
-
providers.[openstack].pools.max-volumes
Type: int Maximum number of volumes usable from this pool. This can be used to limit the number of volumes allocated by nodepool. If not defined, nodepool can use as many volumes as the tenant allows.
-
providers.[openstack].pools.max-volume-gb
Type: int Maximum total size in gigabytes of volumes usable from this pool. This can be used to limit the volume storage allocated by nodepool. If not defined, nodepool can use as much space as the tenant allows.
-
providers.[openstack].pools.ignore-provider-quota
Default:False
Type: bool Ignore the provider quota for this pool. Instead, only check against the configured max values for this pool and the current usage based on stored data. This may be useful in circumstances where the provider is incorrectly calculating quota.
-
providers.[openstack].pools.availability-zones
Type: list A list of availability zones to use.
If this setting is omitted, nodepool will fetch the list of all availability zones from nova. To restrict nodepool to a subset of availability zones, supply a list of availability zone names in this setting.
Nodepool chooses an availability zone from the list at random when creating nodes but ensures that all nodes for a given request are placed in the same availability zone.
-
providers.[openstack].pools.networks
Type: list Specify custom Neutron networks that get attached to each node. Specify the name or id of the network as a string.
-
providers.[openstack].pools.security-groups
Type: list Specify custom Neutron security groups that get attached to each node. Specify the name or id of the security_group as a string.
-
providers.[openstack].pools.auto-floating-ip
Default:True
Type: bool Specify custom behavior of allocating floating ip for each node. When set to False,
nodepool-launcher
will not apply floating ip for nodes. When zuul instances and nodes are deployed in the same internal private network, set the option to False to save floating ip for cloud provider.
-
providers.[openstack].pools.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 supplied to the requestor. When set to false, nodepool-launcher will not attempt to ssh-keyscan nodes after they are booted. Disable this if nodepool-launcher and the nodes it launches are on different networks, where the launcher is unable to reach the nodes directly, or when using Nodepool with non-SSH node platforms. The default value is true.
-
providers.[openstack].pools.labels
Type: list Each entry in a pool`s labels section indicates that the corresponding label is available for use in this pool. When creating nodes for a label, the flavor-related attributes in that label’s section will be used.
labels: - name: precise min-ram: 8192 flavor-name: 'something to match' console-log: True - name: trusty min-ram: 8192 networks: - public - private
Each entry is a dictionary with the following keys
-
providers.[openstack].pools.labels.name (required)
Type: str Identifier to refer this image; from labels and diskimages sections.
-
providers.[openstack].pools.labels.diskimage (required)
Type: str Refers to provider’s diskimages, see providers.[openstack].diskimages. Mutually exclusive with providers.[openstack].pools.labels.cloud-image
-
providers.[openstack].pools.labels.cloud-image (required)
Type: str Refers to the name of an externally managed image in the cloud that already exists on the provider. The value of
cloud-image
should match thename
of a previously configured entry from thecloud-images
section of the provider. See providers.[openstack].cloud-images. Mutually exclusive with providers.[openstack].pools.labels.diskimage
-
providers.[openstack].pools.labels.flavor-name
Type: str Name or id of the flavor to use. If providers.[openstack].pools.labels.min-ram is omitted, it must be an exact match.
If providers.[openstack].pools.labels.min-ram is given,
flavor-name
will be used to find flavor names that meet providers.[openstack].pools.labels.min-ram and also containflavor-name
. Flavors that match the RAM requirements will be examined in standard alphabetical order; the first to contain theflavor-name
string will be chosen.One of providers.[openstack].pools.labels.min-ram or providers.[openstack].pools.labels.flavor-name must be specified.
-
providers.[openstack].pools.labels.min-ram
Type: int Determine the flavor to use (e.g.
m1.medium
,m1.large
, etc). The smallest flavor that meets themin-ram
requirements will be chosen.One of providers.[openstack].pools.labels.min-ram or providers.[openstack].pools.labels.flavor-name must be specified.
-
providers.[openstack].pools.labels.boot-from-volume
Default:False
Type: bool If given, the label for use in this pool will create a volume from the image and boot the node from it.
-
providers.[openstack].pools.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 supplied to the requestor. When set to false, nodepool-launcher will not attempt to ssh-keyscan nodes after they are booted. Disable this if nodepool-launcher and the nodes it launches are on different networks, where the launcher is unable to reach the nodes directly, or when using Nodepool with non-SSH node platforms. The default value is true.
Note
This value will override the value for providers.[openstack].pools.host-key-checking.
-
providers.[openstack].pools.labels.networks
Type: list Specify custom Neutron networks that get attached to each node. Specify the name or id of the network as a string.
Note
This value will override the value for providers.[openstack].pools.networks.
-
providers.[openstack].pools.labels.key-name
Type: string If given, is the name of a keypair that will be used when booting each server.
-
providers.[openstack].pools.labels.console-log
Default:False
Type: bool On the failure of the ssh ready check, download the server console log to aid in debugging the problem.
-
providers.[openstack].pools.labels.volume-size
Default:50
Type: int gigabytes When booting an image from volume, how big should the created volume be.
-
providers.[openstack].pools.labels.instance-properties
Default:None
Type: dict A dictionary of key/value properties to set when booting each server. These properties become available via the
meta-data
on the active server (e.g. withinconfig-drive:openstack/latest/meta_data.json
)
-
providers.[openstack].pools.labels.dynamic-instance-properties
Default:None
Type: dict Similar to providers.[openstack].pools.labels.instance-properties, but is interpreted as a format string with the following values available:
request: Information about the request which prompted the creation of this node (note that the node may ultimately be used for a different request and in that case this information will not be updated).
id: The request ID.
labels: The list of labels in the request.
requestor: The name of the requestor.
requestor_data: Key/value information from the requestor.
relative_priority: The relative priority of the request.
event_id: The external event ID of the request.
created_time: The creation time of the request.
tenant_name: The name of the tenant associated with the request.
For example:
labels: - name: precise dynamic-instance-properties: request_info: "Created for request {request.id}"
-
providers.[openstack].pools.labels.userdata
Default:None
Type: str A string of userdata for a node. Example usage is to install cloud-init package on image which will apply the userdata. Additional info about options in cloud-config: https://cloudinit.readthedocs.io/en/latest/topics/examples.html
-
providers.[openstack].pools.labels.name (required)
-
providers.[openstack].pools.name (required)
-
providers.[openstack].cloud (required)