OpenStack Driver

Selecting the OpenStack driver adds the following options to the providers section of the configuration.

providers.[openstack]
providers.[openstack].cloud
providers.[openstack].boot-timeout
providers.[openstack].launch-timeout
providers.[openstack].nodepool-id
providers.[openstack].launch-retries
providers.[openstack].region-name
providers.[openstack].hostname-format
providers.[openstack].image-name-format
providers.[openstack].post-upload-hook
providers.[openstack].rate
providers.[openstack].clean-floating-ips
providers.[openstack].port-cleanup-interval
providers.[openstack].diskimages
providers.[openstack].cloud-images
providers.[openstack].pools

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. below providers.[openstack].cloud refers to the cloud key in the providers section when the openstack 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 for this server using the Nova metadata service. A maximum of five entries is allowed, and both keys and values must be 255 characters or less.

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].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 or image-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 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.

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 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

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].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.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.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: Specify custom behavior of validation of SSH host keys. When set to False, nodepool-launcher will not ssh-keyscan nodes after they are booted. This might be needed if nodepool-launcher and the nodes it launches are on different networks. 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 the name of a previously configured entry from the cloud-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 contain flavor-name.

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 the min-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: Specify custom behavior of validation of SSH host keys. When set to False, nodepool-launcher will not ssh-keyscan nodes after they are booted. This might be needed if nodepool-launcher and the nodes it launches are on different networks. 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. within config-drive:openstack/latest/meta_data.json)

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