Configuration¶
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:
diskimages:
...
labels:
...
providers:
...
The following drivers are available.
The following sections are available. All are required unless otherwise indicated.
Options¶
-
webapp¶
Define the webapp endpoint port and listen address
-
webapp.port¶
Default:8005
Type: int The port to provide basic status information
-
webapp.listen_address¶
Default:0.0.0.0
Listen address for web app
-
webapp.port¶
-
elements-dir¶
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.
-
images-dir¶
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.Note
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.
-
build-log-dir¶
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
.
-
build-log-retention¶
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.
zookeeper-servers: - host: zk1.example.com port: 2181 chroot: /nodepool
Each entry is a dictionary with the following keys
-
zookeeper-servers.host (required)¶
Example:zk1.example.com
Type: str A zookeeper host
-
zookeeper-servers.port¶
Default:2181
Type: int Port to talk to zookeeper
-
zookeeper-servers.chroot¶
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.
-
zookeeper-servers.host (required)¶
-
zookeeper-tls¶
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.
-
zookeeper-tls.ca (required)¶
Type: string The path to the PEM encoded CA certificate.
-
zookeeper-tls.cert (required)¶
-
labels¶
Type: list Defines the types of nodes that should be created. Jobs should be written to run on nodes of a certain label. Example
labels: - 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
-
labels.name (required)¶
Type: string Unique name used to tie jobs to those instances.
-
labels.max-ready-age¶
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.
-
labels.min-ready¶
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.
-
labels.name (required)¶
-
max-hold-age¶
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.
-
diskimages¶
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.A sample configuration section is illustrated below.
diskimages: - name: base abstract: True elements: - vm - simple-init - openstack-repos - nodepool-base - cache-devstack - cache-bindep - growroot - infra-package-needs env-vars: TMPDIR: /opt/dib_tmp DIB_CHECKSUM: '1' DIB_IMAGE_CACHE: /opt/dib_cache - name: ubuntu-bionic parent: base pause: False rebuild-age: 86400 elements: - ubuntu-minimal release: bionic username: zuul env-vars: DIB_APT_LOCAL_CACHE: '0' DIB_DISABLE_APT_CLEANUP: '1' FS_TYPE: ext3 - name: ubuntu-focal base: ubuntu-bionic release: focal env-vars: DIB_DISABLE_APT_CLEANUP: '0' - name: centos-8 parent: base pause: True rebuild-age: 86400 formats: - raw - tar elements: - centos-minimal - epel release: '8' username: centos env-vars: FS_TYPE: xfs
Each entry is a dictionary with the following keys
-
diskimages.name (required)¶
Type: string Identifier to reference the disk image in providers.[openstack].diskimages and labels.
-
diskimages.abstract¶
Default:False
Type: bool An
abstract
entry is used to group common configuration together, but will not create any actual image. Adiskimage
marked asabstract
should be inherited from in anotherdiskimage
via its diskimages.parent attribute.An abstract entry can have a diskimages.parent attribute as well; values will merge down.
-
diskimages.parent¶
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.
-
diskimages.formats¶
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.
-
diskimages.rebuild-age¶
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).
-
diskimages.release¶
Type: string Specifies the distro to be used as a base image to build the image using diskimage-builder.
-
diskimages.build-timeout¶
Type: int How long (in seconds) to wait for the diskimage build before giving up. The default is 8 hours.
-
diskimages.elements¶
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.
-
diskimages.env-vars¶
Type: dict Arbitrary environment variables that will be available in the spawned diskimage-builder child process.
-
diskimages.pause¶
Default:False
Type: bool When set to True,
nodepool-builder
will not build the diskimage.
-
diskimages.username¶
Default:zuul
Type: string The username that a consumer should use when connecting to the node.
-
diskimages.python-path¶
Default:auto
Type: string 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.
-
diskimages.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 not be used unless the default shell is a non-Bourne (sh) compatible shell, e.g.csh
orfish
. For a windows image with the experimental connection-typessh
,cmd
orpowershell
should be set and reflect the node’sDefaultShell
configuration.
-
diskimages.dib-cmd¶
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 customdiskimage-builder
is installed in another virutalenv.Note
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.
-
diskimages.name (required)¶
-
providers¶
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
-
providers.name (required)¶
Type: string Name of the provider
-
providers.max-concurrency¶
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.
-
providers.driver¶
Default:openstack
Type: string The driver type.
- aws¶
For details on the extra options required and provided by the AWS driver, see the separate section AWS EC2 Driver
- azure¶
For details on the extra options required and provided by the Azure driver, see the separate section Azure Compute Driver
- gce¶
For details on the extra options required and provided by the GCE driver, see the separate section Google Cloud Compute Engine (GCE) Driver
- kubernetes¶
For details on the extra options required and provided by the kubernetes driver, see the separate section Kubernetes Driver
- openshift¶
For details on the extra options required and provided by the openshift driver, see the separate section Openshift Driver
- openshiftpods¶
For details on the extra options required and provided by the openshiftpods driver, see the separate section Openshift Pods Driver
- openstack¶
For details on the extra options required and provided by the OpenStack driver, see the separate section OpenStack Driver
- static¶
For details on the extra options required and provided by the static driver, see the separate section Static Driver
-
providers.name (required)¶