Nodepool reads its configuration from /etc/nodepool/nodepool.yaml by default. The configuration file follows the standard YAML syntax with a number of sections defined with top level keys. For example, a full configuration file may have the diskimages, labels, and providers sections:


The following drivers are available.

The following sections are available. All are required unless otherwise indicated.



Define the webapp endpoint port and listen address

Default: 8005
Type: int

The port to provide basic status information


Listen address for web app

Example: /path/to/elements/dir
Type: str

If an image is configured to use diskimage-builder and glance to locally create and upload images, then a collection of diskimage-builder elements must be present. The elements-dir parameter indicates a directory that holds one or more elements.

Example: /path/to/images/dir
Type: str

When we generate images using diskimage-builder they need to be written to somewhere. The images-dir parameter is the place to write them.


The builder daemon creates a UUID to uniquely identify itself and to mark image builds in ZooKeeper that it owns. This file will be named builder_id.txt and will live in the directory named by the images-dir option. If this file does not exist, it will be created on builder startup and a UUID will be created automatically.

Example: /path/to/log/dir
Type: str

The builder will store build logs in this directory. It will create one file for each build, named <image>-<build-id>.log; for example, fedora-0000000004.log. It defaults to /var/log/nodepool/builds.

Default: 7
Type: int

At the start of each build, the builder will remove old build logs if they exceed this value. This option specifies how many will be kept (usually you will see one more, as deletion happens before starting a new build). By default, the last 7 old build logs are kept. Set this to -1 to disable removal of logs.

zookeeper-servers (required)
Type: list

Lists the ZooKeeper servers uses for coordinating information between nodepool workers.

  - host:
    port: 2181
    chroot: /nodepool

Each entry is a dictionary with the following keys (required)
Type: str

A zookeeper host

Default: 2181
Type: int

Port to talk to zookeeper

Example: /nodepool
Type: str

The chroot key, used for interpreting ZooKeeper paths relative to the supplied root path, is also optional and has no default.

Type: dict

To use TLS connections with Zookeeper, provide this dictionary with the following keys:

zookeeper-tls.cert (required)
Type: string

The path to the PEM encoded certificate.

zookeeper-tls.key (required)
Type: string

The path to the PEM encoded key. (required)
Type: string

The path to the PEM encoded CA certificate.

Default: 10.0
Type: float

The ZooKeeper session timeout, in seconds.

Type: list

Defines the types of nodes that should be created. Jobs should be written to run on nodes of a certain label. Example

  - name: my-precise
    max-ready-age: 3600
    min-ready: 2
  - name: multi-precise
    min-ready: 2

Each entry is a dictionary with the following keys (required)
Type: string

Unique name used to tie jobs to those instances.

Default: 0
Type: int

Maximum number of seconds the node shall be in ready state. If this is exceeded the node will be deleted. A value of 0 disables this.

Default: 0
Type: int

Minimum number of instances that should be in a ready state. Nodepool 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. min-ready is best-effort based on available capacity and is not a guaranteed allocation. The default of 0 means that nodepool will only create nodes of this label when there is demand. Set to -1 to have the label considered disabled, so that no nodes will be created at all.

Default: 0
Type: int

Maximum number of seconds a node shall be in “hold” state. If this is exceeded the node will be deleted. A value of 0 disables this.

This setting is applied to all nodes, regardless of label or provider.

Type: list

This section lists the images to be built using diskimage-builder. The name of the diskimage is mapped to the providers.[openstack].diskimages section of the provider, to determine which providers should received uploads of each image. The diskimage will be built in every format required by the providers with which it is associated. Because Nodepool needs to know which formats to build, if the diskimage will only be built if it appears in at least one provider.

To remove a diskimage from the system entirely, remove all associated entries in providers.[openstack].diskimages and remove its entry from diskimages. All uploads will be deleted as well as the files on disk.

If multiple builders are used to build disjoint images, the diskimage stanza for every image must be present on every builder, however, each builder may have different providers configured, and a given builder will only build images used by its configured providers.

A sample configuration section is illustrated below.

  - name: base
    abstract: True
      - vm
      - simple-init
      - openstack-repos
      - nodepool-base
      - cache-devstack
      - cache-bindep
      - growroot
      - infra-package-needs
      TMPDIR: /opt/dib_tmp
      DIB_CHECKSUM: '1'
      DIB_IMAGE_CACHE: /opt/dib_cache

  - name: ubuntu-bionic
    parent: base
    pause: False
    rebuild-age: 86400
      - ubuntu-minimal
    release: bionic
    username: zuul
      FS_TYPE: ext3

  - name: ubuntu-focal
    base: ubuntu-bionic
    release: focal

  - name: centos-8
    parent: base
    pause: True
    rebuild-age: 86400
      - raw
      - tar
      - centos-minimal
      - epel
    release: '8'
    username: centos
      FS_TYPE: xfs

Each entry is a dictionary with the following keys (required)
Type: string

Identifier to reference the disk image in providers.[openstack].diskimages and labels.

Default: False
Type: bool

An abstract entry is used to group common configuration together, but will not create any actual image. A diskimage marked as abstract should be inherited from in another diskimage via its diskimages.parent attribute.

An abstract entry can have a diskimages.parent attribute as well; values will merge down.

Type: str

A parent diskimage entry to inherit from. Any values from the parent will be populated into this image. Setting any fields in the current image will override the parent values execept for the following:

  • diskimages.env-vars: new keys are additive, any existing keys from the parent will be overwritten by values in the current diskimage (i.e. Python update() semantics for a dictionary).

  • diskimages.elements: values are additive; the list of elements from the parent will be extended with any values in the current diskimage. Note that the element list passed to diskimage-builder is not ordered; elements specify their own dependencies and diskimage-builder builds a graph from that, not the command-line order.

Note that a parent diskimage may also have it’s own parent, creating a chain of inheritance. See also diskimages.abstract for defining common configuration that does not create a diskimage.

Type: list

The list of formats to build is normally automatically created based on the needs of the providers to which the image is uploaded. To build images even when no providers are configured or to build additional formats which you know you may need in the future, list those formats here.

In case the diskimage is not used by any provider and no formats are configured, the image won’t be built.

Default: 86400
Type: int

If the current diskimage is older than this value (in seconds), then nodepool will attempt to rebuild it. Defaults to 86400 (24 hours).

Type: string

Specifies the distro to be used as a base image to build the image using diskimage-builder.
Type: int

How long (in seconds) to wait for the diskimage build before giving up. The default is 8 hours.

Type: list

Enumerates all the elements that will be included when building the image, and will point to the elements-dir path referenced in the same config file.

Type: dict

Arbitrary environment variables that will be available in the spawned diskimage-builder child process.

Default: False
Type: bool

When set to True, nodepool-builder will not build the diskimage.

Default: zuul
Type: string

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

Default: auto
Type: string

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 on Ansible >=2.8, and default to /usr/bin/python2 for earlier versions.
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 not be used unless the default shell is a non-Bourne (sh) compatible shell, e.g. csh or fish. For a windows image with the experimental connection-type ssh, cmd or powershell should be set and reflect the node’s DefaultShell configuration.

Default: disk-image-create
Type: string

Configure the command called to create this disk image. By default this just disk-image-create; i.e. it will use the first match in $PATH. For example, you may want to override this with a fully qualified path to an alternative executable if a custom diskimage-builder is installed in another virutalenv.


Any wrapping scripts or similar should consider that the command-line or environment arguments to disk-image-create are not considered an API and may change.

Type: dict

This provides default values for the provider-specific metadata or tags values which can be set for diskimage uploads to specific providers. This is a dictionary of arbitrary key/value pairs. Avoid the use of nodepool_ as a key prefix since Nodepool uses this for internal values.

Type: list

Lists the providers Nodepool should use. Each provider is associated to a driver listed below.

Each entry is a dictionary with the following keys (required)
Type: string

Name of the provider

Default: 0
Type: int

Maximum number of node requests that this provider is allowed to handle concurrently. The default, if not specified, is to have no maximum. Since each node request is handled by a separate thread, this can be useful for limiting the number of threads used by the nodepool-launcher daemon.

Default: 100
Type: int

The priority of this provider (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 provides the default for each provider pool, but the value can be overidden in the pool configuration.

Default: openstack
Type: string

The driver type.


For details on the extra options required and provided by the AWS driver, see the separate section AWS Driver


For details on the extra options required and provided by the Azure driver, see the separate section Azure Compute Driver


For details on the extra options required and provided by the GCE driver, see the separate section Google Cloud Compute Engine (GCE) Driver


For details on the extra options required and provided by the kubernetes driver, see the separate section Kubernetes Driver


For details on the extra options required and provided by the openshift driver, see the separate section Openshift Driver


For details on the extra options required and provided by the openshiftpods driver, see the separate section Openshift Pods Driver


For details on the extra options required and provided by the OpenStack driver, see the separate section OpenStack Driver


For details on the extra options required and provided by the static driver, see the separate section Static Driver

Type: list

A list of global resource limits enforced per tenant (e.g. Zuul tenants).

These limits are calculated on a best-effort basis. Because of parallelism within launcher instances, and especially with multiple launcher instances, the limits are not guaranteed to be exact.

  - tenant-name: example-tenant
    max-servers: 10
    max-cores: 200
    max-ram: 16565
    'L-43DA4232': 224

Each entry is a dictionary with the following keys. Any other keys are interpreted as driver-specific resource limits (otherwise specified as max-resources in the provider configuration). The only driver that currently supports additional resource limits is AWS.

tenant-resource-limits.tenant-name (required)
Example: example-tenant
Type: str

A tenant name correspodinding, e.g., to a Zuul tenant.

Default: infinity
Type: int

The maximum number of servers a tenant can allocate.

Default: infinity
Type: int

The maximum number of CPU cores a tenant can allocate.

Default: infinity
Type: int

The maximum number of main memory (RAM) a tenant can allocate.