Nodepool - Static

The static driver allows you to use existing compute resources, such as real hardware or long-lived virtual machines, with nodepool.

Node Requirements

Any nodes you setup for nodepool (either real or virtual) must meet the following requirements:

Must be reachable by Zuul executors and have SSH access enabled.
Must have a user that Zuul can use for SSH.
Must have an Ansible supported Python installed
Must be reachable by Zuul executors over TCP port 19885 for console log streaming. See Log streaming

When setting up your nodepool.yaml file, you will need the host keys for each node for the host-key value. This can be obtained with the command:

ssh-keyscan -t ed25519 <HOST>

Nodepool Configuration

Below is a sample Nodepool configuration file that sets up static nodes. Place this file in /etc/nodepool/nodepool.yaml:

sudo bash -c "cat > /etc/nodepool/nodepool.yaml <<EOF
zookeeper-servers:
  - host: localhost

labels:
  - name: ubuntu-jammy

providers:
  - name: static-vms
    driver: static
    pools:
      - name: main
        nodes:
          - name: 192.168.1.10
            labels: ubuntu-jammy
            host-key: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGXqY02bdYqg1BcIf2x08zs60rS6XhlBSQ4qE47o5gb"
            username: zuul
          - name: 192.168.1.11
            labels: ubuntu-jammy
            host-key: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGXqY02bdYqg1BcIf2x08zs60rS6XhlBSQ5sE47o5gc"
            username: zuul
EOF"

Make sure that username, host-key, IP addresses and label names are customized for your environment.

Log streaming

The log streaming service enables Zuul to show the live status of long-running shell or command tasks. The server side is setup by the zuul_console: task built-in to Zuul’s Ansible installation. The executor requires the ability to communicate with this server on the job nodes via port 19885 for this to work.

The log streaming service spools command output via files on the job node in the format /tmp/console-<uuid>-<task_id>-<host>.log. By default, it will clean these files up automatically.

Occasionally, a streaming file may be left if a job is interrupted. These may be safely removed after a short period of inactivity with a command such as

find /tmp -maxdepth 1 -name 'console-*-*-<host>.log' -mtime +2 -delete

If the executor is unable to reach port 19885 (for example due to firewall rules), or the zuul_console daemon can not be run for some other reason, the command to clean these spool files will not be processed and they may be left behind; on an ephemeral node this is not usually a problem, but on a static node these files will persist.

In this situation, , Zuul can be instructed to not to create any spool files for shell and command tasks via setting zuul_console_disabled: True (usually via a global host variable in inventory). Live streaming of shell and command calls will of course be unavailable in this case, but no spool files will be created.