General Purpose Roles

add-authorized-keys

Install SSH public key(s) on all hosts

This role is intended to be run at the end of a failed job for which the build node set will be held with zuul’s autohold command.

It copies the public key(s) into the authorized_keys file of every host in the inventory, allowing privileged users to access the node set for debugging or post-mortem analysis.

Add this stanza at the end of your project’s base post playbook to activate this functionality:

- hosts: all
  roles:
    - role: add-authorized-keys
      public_keys:
        - public_key: ssh-rsa AAAAB... venkman@parapsy.columbia.edu
        - public_key: ssh-rsa AAAAB... spengler@parapsy.columbia.edu
      when: not zuul_success | bool

Caution

Including this role earlier in any playbook may allow the keys’ owners to tamper with the execution of the jobs. It is strongly advised against doing so.

Role Variables

ssh_public_keys

A list of keys to inject.

ssh_public_keys.public_key

A public key to inject into authorized_keys, or a URL to a public key.

add-build-sshkey

Generate and install a build-local SSH key on all hosts

This role is intended to be run on the Zuul Executor at the start of every job. It generates an SSH keypair and installs the public key in the authorized_keys file of every host in the inventory. It then removes the Zuul master key from this job’s SSH agent so that the original key used to log into all of the hosts is no longer accessible (any per-project keys, if present, remain available), then adds the newly generated private key.

Role Variables

zuul_temp_ssh_key
Default: ``{{ zuul.executor.work_root }}/{{ zuul.build }}_id_rsa``

Where to put the newly-generated SSH private key.

zuul_ssh_key_dest
Default: ``id_{{ zuul_ssh_key_algorithm }}``

File name for the the newly-generated SSH private key.

zuul_build_sshkey_cleanup
Default: false

Remove previous build sshkey. Set it to true for single use static node. Do not set it to true for multi-slot static nodes as it removes the build key configured by other jobs.

zuul_ssh_key_algorithm
Default: rsa

The digital signature algorithm to be used to generate the key.

zuul_ssh_key_size
Default: 3072

Specifies the number of bits in the key to create.

add-build-winrm-cert

Generate and install a build-local WinRM certificate on all Windows hosts

This role is intended to be run on the Zuul Executor at the start of every job. It generates a self-signed certificate and installs the certificate on every Windows host in the inventory.

It then updates the host vars for each such host to use the new certificate. The original certificate used to initially connect to the host still remains on disk, but once the build-local certificate is in place, later untrusted playbooks no longer need it to be provided.

Role Variables

build_winrm_cert_credentials

A complex argument expected to be supplied from a Zuul secret. These are the Windows login credentials for the account to associate with the certificate.

build_winrm_cert_credentials.username

The username of the account.

build_winrm_cert_credentials.password

The password of the account.

build_winrm_cert_change_password
Default: ``False``

If this is true, then change the password for the user to the value supplied before adding the certificate. This is useful if the initial account password is automatically generated and otherwise unknown.

zuul_temp_winrm_name
Default: ``{{ zuul.build }}_winrm``

The base name of the certificate file.

zuul_temp_winrm_cert
Default: ``{{ zuul.executor.work_root }}/{{ zuul_temp_winrm_name }}.crt``

File name for the the newly-generated certificate.

zuul_temp_winrm_key
Default: ``{{ zuul.executor.work_root }}/{{ zuul_temp_winrm_name }}.key``

File name for the the newly-generated private key.

zuul_temp_winrm_pfx
Default: ``{{ zuul.executor.work_root }}/{{ zuul_temp_winrm_name }}.pfx``

Executor-local file name for the the exported certificate.

zuul_temp_winrm_remote_tempfile
Default: ``~/appdata/local/temp/{{ zuul_temp_winrm_name }}.pfx``

Remote temporary location for the certificate during import.

add-gpgkey

Install a GPG private key onto a host.

Role Variables

gpg_key

Complex argument which contains the GPG private key. It is expected that this argument comes from a Secret.

gpg_key.private

The ascii-armored contents of the GPG private key.

add-sshkey

Add an ssh key to the host so that non-ansible ssh connections can be made.

Role Variables

ssh_key

Complex argument which contains the ssh key information. It is expected that this argument comes from a Secret.

ssh_key.ssh_known_hosts

String containing known host signature for the remote host.

ssh_key.ssh_private_key

Contents of the ssh private key to use.

ssh_key.fqdn

The FQDN of the remote host.

bindep

Installs distro packages using bindep tool

Looks for a bindep.txt in a project’s source directory, or failing that a other-requirements.txt. If one exists, run bindep on the file to produce a list of required distro packages that do not exist and then install the missing packages.

Role Variables

bindep_dir
Default: {{ zuul.project.src_dir }}

The directory to look for bindep files in.

bindep_profile
Default: test

A specific bindep profile to request.

bindep_file

Path or list of paths to a specific bindep file(s) to read from.

bindep_command

Path to the bindep command. Defaults to unset which will look for a system installed bindep. If bindep_command is not found, bindep will be installed into a temporary virtualenv.

bindep_fallback

Path to a bindep fallback file to be used if no bindep file can be found in bindep.bindep_dir.

buildset-artifacts-location

Return the location of buildset logs

When a ‘buildset’ directory exists in the job logs, then use zuul_return to set buildset_artifacts_url for children jobs.

rpm-build job:

• Create a repository

• Fetch the repository to “{{ zuul.executor.log_root }}/buildset”

• Use the buildset-artifacts-location role

rpm-test jobs:

• Install “{{ buildset_artficats_url }}” yum repository

• Run integration tests

layout:
  jobs:
    - rpm-build
    - rpm-test1:
        dependencies:
          - rpm-build
    - rpm-test2:
        dependencies:
          - rpm-build

Role Variables

zuul_log_url

Base URL where logs are to be found.

zuul_log_path

Path of the logs. This optional when the role is used after ‘upload-logs’.

clear-firewall

Clear firewall rules from test nodes

Some test workloads manage all of their own firewall rules, and pre-existing firewall rules can pollute the system. This role clears out firewall rules for both ipv4 and ipv6.

You may want to consult your Zuul system’s system administrator prior to using this role as the preexisting firewall configuration may provide necessary functionality.

configure-mirrors

An ansible role to configure services to use mirrors.

Role Variables

mirror_fqdn
Default: {{ zuul_site_mirror_fqdn }}

The base host for mirror servers.

mirror_use_ssl
Default: False

Use ssl to communicate to mirror endpoints. Note if the platform cannot use ssl (for example Ubuntu Xenial apt needs additional packages) this will still use http instead of https when set for that platform.

pypi_fqdn
Default: {{ mirror_fqdn }}

The base host for PyPi mirror server.

pypi_mirror

URL to override the generated pypi mirror url based on configure-mirrors.pypi_fqdn.

set_apt_mirrors_trusted
Default: False

Set to True in order to tag APT mirrors as trusted, needed when accessing unsigned mirrors with newer releases like Ubuntu Bionic.

enable_deb_src_repos
Default: False

Set this to True in order to enable deb-src entries in sources.list configs for apt. Note this option currently only works on Debian (not Ubuntu) installations.

configure_mirrors_extra_repos
Default: True

Set to False to opt-out of installing extra repositories such as PowerTools and HighAvailability on centos-8-stream and backports for Debian/Ubuntu. The intent is to match the upstream distro state when this variable is set to False. Note that this role is not necessarily consistent with the repos that are enabled by default between distribution versions (centos stream 8 vs. 9 for example).

configure_mirrors_components_9_stream
Default: See `vars/CentOS-9.yaml`

A list of the components that should be redirected to the mirror_fqdn when setting up a CentOS 9-stream host. For example, your mirror may only mirror some components, or not the debug/source components, etc.

copy-build-sshkey

Copy a build-local SSH key to a defined user on all hosts

This role is intended to be run on the Zuul Executor. It copies a generated build specific ssh key to a user and adds it to the authorized_keys file of every host in the inventory.

Role Variables

zuul_temp_ssh_key
Default: "{{ zuul.executor.work_root }}/{{ zuul.build }}_id_rsa"

Where to source the build private key

copy_sshkey_target_user
Default: root

The user to copy the sshkey to.

download-artifact

Download artifacts from a completed build of a Zuul job

Given a change, downloads artifacts from a previous build (by default of the current change) into the work directory. This will download as many artifacts as match the selection criteria.

Role Variables

download_artifact_api

The Zuul API endpoint to use. Example: https://zuul.example.org/api/tenant/{{ zuul.tenant }}

download_artifact_pipeline

The pipeline in which the previous build ran.

download_artifact_job

The job of the previous build.

download_artifact_type

The artifact type. This is the value of the type field in the artifact metadata. This can be a string or a list of strings.

download_artifact_query
Default: change={{ zuul.change }}&patchset={{ zuul.patchset }}&pipeline={{ download_artifact_pipeline }}&job_name={{ download_artifact_job }}

The query to use to find the build. Normally the default is used.

download_artifact_directory
Default: {{ zuul.executor.work_root }}

The directory in which to place the downloaded artifacts.

dstat-graph

Run dstat_graph

This requires that the run-dstat role be previously used.

Add this to a post-run playbook to run dstat_graph to graph data from dstat.

Use the ensure-dstat-graph in a pre-run playbook to make sure that dstat_graph is available (since it is not currently packaged in any operating system).

The output will appear in dstat.html in the zuul-output/logs directory.

Role Variables

dstat_graph_cache_path
Default: /opt/cache/dstat_graph

The role will check this location to see if a cached copy of dstat_graph is available.

dstat_graph_download_path
Default: /tmp/dstat_graph

If a cached copy is not available, the role will check if dstat_graph was previously downloaded to this location.

dstat_data_path
Default: "{{ ansible_user_dir }}/zuul-output/logs/dstat.csv"

The path to the dstat data file.

emit-job-header

Log a few lines about the job.

Role Variables

zuul_log_url

Base URL where logs are to be found.

zuul_log_path_shard_build
Default: False

This var is consumed by set-zuul-log-path-fact which emit-job-header calls into. If you set this you will get log paths prefixed with the first three characters of the build uuid. This will improve log file sharding.

More details can be found at set-zuul-log-path-fact.zuul_log_path_shard_build

enable-fips

Enable FIPS on a node.

Set a node into FIPS mode, to test functionality when crypto policies are set to FIPS in RHEL/Centos >=8 or Ubuntu.

For Ubuntu nodes, the node is assumed to already have an Ubuntu Advantage subscription activated, as this is required to enable FIPS mode. The enable-ua-subscription role in this repo can be used to activate the subscription.

The role will set the node into FIPS mode, reboot the node, and then call the post-reboot-tasks role. This role requires a role parameter - nslookup_target.

enable-netconsole

Enable netconsole for host

This enables the netconsole on a host to send kernel/dmesg logs to a remote host. This can be very useful if a node is experiencing a kernel oops or another form of unexpected disconnect where you can not retrieve information via standard logging methods.

The netconsole_remote_ip and netconsole_remote_port variables must be set. This host can capture the logs with a command like:

$ nc -v -u -l -p 6666 | tee console-output.log

or:

$ socat udp-recv:6666 - | tee console-output.log

One further trick is to send interesting data to /dev/kmsg, this should make it across the netconsole even if the main interface has been disabled, etc. e.g.:

$ ip addr | sudo tee /dev/kmsg

Role Variables

netconsole_remote_ip

The IP address of the remote host to send to.

netconsole_remote_port

The port listening on the remote host.

enable-ua-subscription

Enable UA Subscription on a node.

For Ubuntu nodes, this role activates an Ubuntu advantage subscription using a passed in token (ubuntu_ua_token.token).

Role Variables

ubuntu_ua_token
Default: None
Type: dict

Dict used to specify Ubuntu advantage subscription information. ubuntu_ua_token.token is a subscription key.

encrypt-file

encrypt-file

Import GPG keys and encrypt a file

Role Variables

encrypt_file
Default: *undefined*

A string with the full path to a log file to encrypt, or a list of string values of full paths to encrypt. Must be defined. Resulting file(s) will have .gpg added.

encrypt_file_recipients
Default: []

List of recipients who will be able to decrypt the file(s). This should be a list of name keys that exist in encrypt_file_keys.

encrypt_file_keys
Default: []

Keys available to encrypt the file with. Each entry is a dictionary with keys

• name : a freeform string identifier

• key_id: the GPG key ID

• gpg_asc: the GPG ASCII-armored public key. If the public-key is not already available, it will be imported to GPG.

It is intended that this is a global-variable, and specific files to be encrypted then choose a subset of keys in this variable for encryption.

ensure-bazelisk

Ensure that bazelisk is present.

If bazelisk is already installed, this role does nothing. Otherwise, it downloads bazelisk from GitHub and installs it in the user’s home directory by default.

Role Variables

bazelisk_version
Default: v1.3.0

Version of bazelisk to install.

bazelisk_arch
Default: linux-amd64

Architecture to install.

bazelisk_url
Default: https://github.com/bazelbuild/bazelisk/releases/download/{{ bazelisk_version }}/bazelisk-{{ bazelisk_arch }}

The URL from which to download bazelisk.

bazelisk_target
Default: "{{ ansible_user_dir }}/.local/bin/bazelisk"

Where to install bazelisk. If the role downloads bazelisk, it will set ensure-bazelisk.bazelisk_executable to this value as well.

Output Variables

bazelisk_executable
Default: bazelisk

The bazelisk executable. If this already exists, the role will not perform any further actions. It will be made available for other roles running after role.

ensure-dhall

Ensure dhall is installed

Installs the specified version of the haskell implementation.

Role Variables

dhall_version
Default: 1.31.1

The dhall version.

ensure-dstat-graph

Install dstat_graph

This downloads dstat_graph if it is not already present on the remote host.

Add this to a pre-run playbook to ensure it is available for roles such as dstat-graph.

Role Variables

dstat_graph_cache_path
Default: /opt/cache/dstat_graph

The role will check this location to see if a cached copy of dstat_graph is available.

dstat_graph_download_path
Default: /tmp/dstat_graph

If a cached copy is not available, the role will download dstat_graph to this location.

ensure-markdownlint

Ensure markdownlint-cli from NPM is installed.

ensure-shake

Ensure shake is installed

Installs the shake tool using the distro package.

fetch-markdownlint

Collect output from a markdownlint run. Assumes you will only run one repo, and one node.

Role Variables

zuul_work_dir
Default: {{ zuul.project.src_dir }}

The location of the main working directory of the job.

git-prepare-nodecache

Prepare an archive containing all repositories that are part of the job. This can be used to prepare the repos archive suitable for caching in the node image to be used by prepare-workspace-git.

The path to the resulting archive file will be stored in the git_cache_file variable. That variable can be used to push the archive to a place where it will be picked up to be baked into the node image.

Role variables

git_cache_root
Default: {{ansible_user_dir }}/git-cache"

Directory where the git cache should be prepared. Usually this should not be changed.

intercept-job

If a special SSH key is placed in the right place, stops and waits for user to SSH in to the node.

This role is intended to be used in pre/post playbooks to allow a smoother self-service experience than autoholds can offer, at the expense that one can only access the node for the length of the job timeout.

Role Variables

intercept_job_pub_key_path
Default: ``{{ zuul.project.src_dir }}/intercept_job.pub``

If a public key is found here, the intercept-job role will install it, print details for SSH’ing into this machine, and wait until the intercept_job_stop_path exists.

intercept_job_stop_path
Default: ``{{ zuul.project.src_dir }}/intercept_job.stop``

If this file exists, the intercept-job role will stop waiting and allow the playbook to continue.

log-inventory

Log the inventory used to run the job to the job’s log dir.

This will result in the log collection roles logging the job inventory.

Role Variables

zuul_info_dir
Default: {{ zuul.executor.log_root }}/zuul-info

The directory path to store the inventory file.

markdownlint

Run markdownlint against all markdown files in the given project.

Role Variables

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to search for markdown files in.

multi-node-bridge

Configures a VXLAN virtual network overlay through an openvswitch network bridge between a ‘switch’ node and ‘peer’ nodes.

This allows members of the bridge to communicate with each other through the virtual network.

By default, this role will:

• Install and start openvswitch

• Set up a br-infra bridge on all nodes

• Set up the connectivity between the switch and the peer with a virtual port

• Set up an ip address on the bridge interface:

172.24.4.1/23 # switch node
172.41.4.2/23 # first peer
172.41.4.3/23 # second peer
...

Role requirements

This role requires and expects two groups to be set up in the Ansible host inventory in order to work:

• switch (the node acting as the switch)

• peers (nodes connected to the virtual switch ports)

Role variables

bridge_vni_offset
Default: 1000000

VXLAN Network Identifier offset (openvswitch key).

bridge_mtu
Default: Smallest mtu less 50 bytes for vxlan overhead

Bridge interface MTU. By default we determine this value by checking all interfaces on host, taking the smallest MTU and subtracting by 50 for vxlan overhead. Can be overridden explicitly if this does not work.

bridge_name
Default: br-infra

Name of the bridge interface.

bridge_configure_address
Default: true

Whether or not to configure an IP address on the bridge interface.

bridge_authorize_internal_traffic
Default: false

When bridge_configure_address is true, whether or not to set up firewall rules to allow traffic freely within the bridge subnet (bridge_address_prefix.0/bridge_address_subnet).

bridge_address_prefix
Default: 172.24.4

The IP address range prefix.

bridge_address_offset
Default: 1

The IP address offset, used with bridge_address_prefix to provide the full IP address. The initial offset defines the IP address of the switch node in the virtual network.

bridge_address_subnet
Default: 23

The IP address range CIDR/subnet.

install_ovs
Default: true

Whether or not to install openvswitch. It can be set to false when ovs installation is taken care outside of the role.

multi-node-firewall

Multinode firewall is configured.

This role is intended to install iptables and configure firewall.

Role Variables

iptables_package
Default: iptables

Install the distribution package for Iptables.

multi-node-hosts-file

Configures the inventory hostnames in a multi-node job resolve to their respective private ipv4 addresses through the /etc/hosts file on each node.

multi-node-known-hosts

Configures the file /etc/ssh/ssh_known_hosts on each node in a multi-node job to contain all known host names.

persistent-firewall

Saves current iptables rules for both ipv4 and ipv6 and makes them persistent so that they are available if iptables or the instance is restarted.

This role can be re-used more than once in order to persist new rules.

prepare-workspace

Prepare remote workspaces

This role is intended to run before any other role in a Zuul job.

It starts the Zuul console streamer on every host in the inventory, and then copies the prepared source repos to the working directory on every host.

Role Variables

zuul_workspace_root
Default: .

The directory into which the source repositories are copied.

prepare-workspace-git

Mirror the local git repos to remote nodes

This role uses git operations (unlike prepare-workspace which uses rsync) to mirror the locally prepared git repos to the remote nodes while taking advantage of cached repos on the node if they exist. This role works generically regardless of the existence of a cached repo on the node.

The cached repos need to be placed using the canonical name under the cached_repos_root directory.

Role Variables

cached_repos_root
Default: /opt/git

The root of the cached repos.

prepare_workspace_sync_required_projects_only
Default: False
Type: bool

A flag which if set to true, filters the to be synchronized project list to only use projects which are required by the job.

mirror_workspace_quiet

This value is ignored; it should be removed from job configuration.

zuul_workspace_root
Default: "{{ ansible_user_dir }}"

The root of the workspace in which the repos are mirrored.

prepare-workspace-openshift

Prepare remote workspaces in OpenShift

This role can be used instead of the prepare-workspace role when the synchronize module doesn’t work with kubectl connection. It copies the prepared source repos to the pods’ cwd using the oc rsync command.

This role is intended to run once before any other role in a Zuul job. This role requires the origin-clients to be installed.

Role Variables

openshift_pods
Default: {{ zuul.resources }}

The dictionary of pod name, pod information to copy the sources to.

post-reboot-tasks

Ensure that processes are running after a node reboot.

Some roles (like the enable-fips role) need to reboot the node in order to complete their operations.

This role can be invoked to ensure that the node is sufficiently up again before continuing by doing some basic checks for connectivity (ssh), restarting the zuul-console and making sure DNS is up.

A role parameter nslookup_target is required to specify the DNS name to ensure DNS is working.

Role Variables

nslookup_target
Default: None
Type: str

DNS name to query to confirm that DNS is working. If working in a mirrored environment, it is a good idea to use $zuul_site_mirror_fqdn, because this is what will be needed for package installs in any case.

remove-build-sshkey

Remove the per-build SSH key from all hosts

The complement to add-build-sshkey. It removes the build’s SSH key from the authorized_keys files of all remote hosts.

Role Variables

zuul_temp_ssh_key

Where the per-build SSH private key was stored.

zuul_ssh_key_algorithm
Default: rsa

The digital signature algorithm which was used to generate the key.

remove-build-winrm-cert

Remove the per-build WinRM certificate from all hosts

The complement to add-build-winrm-cert. It removes the build’s WinRM certificate from WSMan registry of all Windows hosts.

remove-gpgkey

Remove an added GPG key from the host.

remove-sshkey

Remove an added ssh key from the host.

Role Variables

ssh_key

Complex argument which contains the ssh key information. It is expected that this argument comes from a Secret.

ssh_key.ssh_known_hosts

String containing known host signature for the remote host.

ssh_key.fqdn

The FQDN of the remote host.

render-diff

Run render command and ensure there are no resulting differences.

Ensure that generated configuration files are idempotent.

Role Variables

render_command
Default: make

The command that render the configuration files.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to run the render command in.

remove-zuul-sshkey

Remove the zuul ssh key

This role is intended to be run on the Zuul Executor at the start of every job to prevent access to public Zuul ssh connection.

revoke-sudo

Remove sudo access for the Zuul user.

If the file /etc/sudoers.d/zuul exists, then it will be removed. This is to facilitate systems which may use the same image for tests which require sudo and those which do not.

This role also asserts that sudo access has been removed and will fail if it has not.

run-dstat

Run dstat

Add this to a pre-run playbook to run dstat.

The role dstat-graph may optionally be used to graph the resulting data.

Role Variables

dstat_data_path
Default: "{{ ansible_user_dir }}/zuul-output/logs/dstat.csv"

The path to the dstat data file.

shake-build

Run the shake build system command.

Role Variables

shake_report_name
Default: shake.html

The name of the report.

shake_target

The name of the target to build.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to run the shake command in.

sign-artifacts

Sign artifacts

Role Variables

gpg_key

Complex argument which contains the GPG private key for signing the artifacts. It is expected that this argument comes from a Secret.

gpg_key.private

The ascii-armored contents of the GPG private key.

gpg_artifact_path
Default: "{{ zuul.executor.work_root }}/artifacts/"

Path to a directory containing artifacts to sign.

stage-output

Stage job output on the remote node

Takes as input a dictionary of files/folders named ‘zuul_copy_output’. Copies contents into {{ stage_dir }} on the remote node and is intended to be used before output fetching in a base job’s post-playbook. If you plan to pair this role with the ‘fetch-output’ role you should ensure {{ stage-dir }] is set to match {{ zuul_output_dir }}.

Role Variables

zuul_copy_output
Default: None

Dictionary of files and folders to be staged.

The input is a dictionary so that it can accumulated via zuul variable merging. Keys of the dictionary will be things to copy. Valid values describe the type of output to copy:

• logs

• artifacts

• docs

• null # ansible null, not the string null

null overrides the will of a parent job to copy something instructing not to copy.

If the type is suffixed with _txt, then the item will have .txt appended to its name. For example:

zuul_copy_output:
  /var/log/syslog: logs_txt

Will copy /var/log/syslog to logs/syslog.txt.

stage_dir
Default: {{ ansible_user_dir }}

The stage directory on the remote node.

extensions_to_txt
Default: null

A dict of file extensions to be replaced with .txt when staging. This can be useful to ensure that text files with an extension not registered in the web server may be viewed via browser when uploaded to a file server.

Note that this is only used for files listed directly in zuul_copy_output and it won’t be applied to files contained in folders listed in zuul_copy_output.

Example:

extensions_to_txt:
  conf: True
  log: True
  txt: False

zuul.conf --(staged as)--> zuul_conf.txt

stage_compress_logs
Default: False

When True, files staged as logs will be compressed individually. Note this option is deprecated as final log storage should control whether or not contents are compressed. The reason for this is certain services like swift may serve compressed files like .tar.gz tarballs uncompressed when you want them to be compressed when served in this way.

start-zuul-console

Start Zuul console logger

It starts the Zuul console streamer on every host in the inventory.

test-setup

Perform project test setup tasks.

This role assumes that Zuul has checked out a change for a project at {{ zuul_work_dir }} and looks for a file named tools/test-setup.sh. If that file exists and is executable, it will be run.

This allows projects to specify test-setup steps (such as creating or initializing a database) in a form that can be easily run by both an automated testing system and developers.

Role Variables

test_setup_environment

Environment variables to pass in to the test-setup script.

test_setup_args

String of optional command line options passed to the test-setup script.

test_setup_skip
Default: false

Set this to true to skip running the test-setup script even if it exists.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

The directory in which to look for the setup script.

trigger-readthedocs

Trigger readthedocs build for a project

Role Variables

rtd_project_name
Default: ``{{ zuul.project.short_name }}``

The readthedocs project name

rtd_webhook_id

The readthedocs webhook API ID. This needs to be taken from the project’s “Integrations” dashboard page in RTD. The URL will look like readthedocs.org/api/v2/webhook/<project-name>/<id>/.

This may come from a secret, however it can not be triggered without authentication.

rtd_credentials

Complex argument which contains the RTD authentication credentials. This is expected to come from a secret.

rtd_credentials.integration_token

The webhook integration token. You’ll find this value on the project’s “Integrations” dashboard page in RTD. This can be used instead of username/password combo.

rtd_credentials.username

The readthedocs username. If set, this will be used to authenticate in preference to any token set via rtd_integration_token.

rtd_credentials.password

Password for username. Must be set if username is set.

update-json-file

Update JSON file

This role reads a JSON file, merges it with supplied values using Ansible’s combine filter and writes it back out. It is useful for updating configuration files. Note this role is not currently idempotent and will write the file each time.

Role Variables

update_json_file_name
Type: path

The path to the file to edit.

update_json_file_combine
Type: object

The data to be combined with the existing file data. This uses the Jinja combine filter.

update_json_file_debug
Default: false
Type: bool

If enabled, output the combined result in a debug task.

update_json_file_default
Default: {}

The default value if the given file does not exist.

update_json_file_become
Default: false
Type: bool

The become: status when writing out the new file.

update_json_file_mode

The mode for the combined file.

update_json_file_user

The user for the combined file.

update_json_file_group

The group for the combined file.

update_json_dir_mode

The mode for the directory if that does not already exists.

upload-artifactory

Upload artifacts specified from the executor to artifactory.

Note

This role uses the src function of the uri module introduced in Ansible 2.7 therefore any ansible version lower than that is not supported.

Role Variables

upload_artifactory_instances

Complex argument that contains the information about credentials, fqdn and name. This argument is expected to come from a secret.

upload_artifactory_instances.upload_artifactory_instances.<name>.user

User for authenticating.

upload_artifactory_instances.upload_artifactory_instances.<name>.password

Password for authenticating. Has a lower precedense than api_key.

upload_artifactory_instances.upload_artifactory_instances.<name>.api_key

API key for authenticating. Has a higher precedense than password.

upload_artifactory_instances.upload_artifactory_instances.<name>.fqdn

Fully qualified domain name to the instance.

upload_artifactory_instances.upload_artifactory_instances.<name>.transport
Default: https

Set to http if the instance does not support https.

upload_artifactory_instances.force_basic_auth
Default: false

Set to true if the instance requires basic auth to be used.

upload_artifactory_manifest

Dictionary of types of items to upload. Currently only supports artifacts.

upload_artifactory_manifest.artifacts

Variable that contains a manifest of the artifacts that should be uploaded to a specific instance of artifactory. This is expected to be set during the build as a cached fact.

artifacts:
  - name: tarball
    src: artifact.tar.gz
    dest: /destination/to/put/artifact/artifact.tar.gz
    instance: artifact-server1
    headers:
      Content-Type: application/gzip

The attributes available on an artifact are the following.

upload_artifactory_manifest.artifacts.name

Name of the artifact. This will be displayed in the build page.

upload_artifactory_manifest.artifacts.src

Path relative to {{ zuul.executor.work_root }}/artifacts/.

upload_artifactory_manifest.artifacts.dest

Destination where the artifact should be put in.

upload_artifactory_manifest.artifacts.instance

Artifactory instance to place the artiface in, this is to choose which entry in upload-artifactory.upload_artifactory_instances to upload the artifact to.

upload_artifactory_manifest.artifacts.headers

Any headers that should be passed to ansibles uri module when uploading.

upload_artifactory_manifest.artifacts.properties

Properties to set in artifactory.

Properties can be either strings or lists of strings.

properties:
  property1: value1
  property2:
    - value2
    - value3

upload_artifactory_manifest.artifacts.metadata

Any metadata that should be returned to Zuul together with the artifact link.

upload-git-mirror

Mirrors a git repository to a remote git server

Meant to be used after a change was successfully merged, this role mirrors a tested git repository to a remote git server over SSH.

The role assumes that git has been previously installed and does not require superuser privileges to run.

Role Variables

git_mirror_credentials

Dictionary that provides the remote git repository credentials

git_mirror_credentials.user

SSH user for the remote git repository

git_mirror_credentials.host

SSH host for the remote git repository

git_mirror_credentials.ssh_key

Literal private key contents. Should start with something like -----BEGIN RSA PRIVATE KEY-----.

git_mirror_credentials.host_key

SSH host key of the remote git server. Can be obtained with ssh-keyscan -H <host>.

git_mirror_repository

Path of the remote git repository

validate-dco-license

Validate all commits have Signed-off-by header

Role Variables

dco_license_failure

Message to display when Signed-off-by header is missing.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to DCO license check in.

validate-host

Log information about the build node

Role Variables

zuul_site_ipv4_route_required
Default: false

If true, fail when no IPv4 route to zuul_site_traceroute_host is available. When false (default) a missing IPv4 route is acceptable so long as there is still a viable IPv6 route.

zuul_site_ipv6_route_required
Default: false

If true, fail when no IPv6 route to zuul_site_traceroute_host is available. When false (default) a missing IPv6 route is acceptable so long as there is still a viable IPv4 route.

zuul_site_traceroute_host

If defined, a host to run a traceroute against to verify build node network connectivity.

zuul_site_image_manifest_files
Default: ['/etc/dib-builddate.txt', '/etc/image-hostname.txt']

A list of files to read from the filesystem of the build node and whose contents will be logged. The default files are files written to nodes by diskimage-builder.

validate-zone-db

Validate bind zone.db files

This role uses named-checkzone to validate Bind zone.db files.

Role Variables

zone_files
Default: zuul.project.src_dir

Look for zone.db files recursively in this directory. The layout should be domain.xyz/zone.db where a parent directory is named for the zone the child zone.db file describes. This populates the zone_db_files variable. Will not be used if zone_db_files is explicitly set per below.

zone_db_files
Default: []

A list of zone.db files to check. Each entry is a list with the first element the domain, and the second element the path to the zone.db file. If this variable is set, automatic searching described by zone_files will not be performed.

version-from-git

Sets three facts based on information in a git repo.

scm_sha

The short sha found in the repository.

project_ver

A string describing the project’s version. It will either be the value of {{ zuul.tag }} or {{ scm_tag }}.{{ commits_since_tag }}.{{ scm_sha }} otherwise where scm_tag is either the most recent tag or the value of scm_sha if there are no commits in the repo.

commits_since_tag

Number of commits since the most recent tag.

Role Variables

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to run git in.

write-inventory

Write an abbreviated version of the Zuul inventory to a file

This writes the minimal information about hosts from the current Zuul inventory to a file. It may be used to subsequently invoke Ansible with the inventory for the job.

Role Variables

write_inventory_dest

The path of the inventory file to write.

write_inventory_include_hostvars
Type: list

A list of facts about the host to include. By default this parameter is omitted and all variables about a host will be included. To only include certain variables, list them here. The empty list will cause no variables to be included.

write_inventory_exclude_hostvars
Type: list

A list of facts about the host to exclude. By default, all variables about a host will be included. To exclude certain variables, list them here.

write_inventory_additional_hostvars
Type: dict

Additional hostvars to include. This can be used to map information from nodepool into the inventory if used as follows:

write_inventory_additional_hostvars:
  public_v4: nodepool.public_ipv4
  public_v6: nodepool.public_ipv6

This will map hostvars[hostname][‘nodepool’][‘public_ipv4’] to hostvars[hostname][‘public_v4’].

write_inventory_per_host_hostvars
Type: dict

An additional dictionary added on a per-host basis. The keys of this dictionary should be hostnames, if the host name matches, the value (also a dictionary) is merged into the hostvars for that host. For example below, hosta.com will have foo with value bar, while hostb.com will have foo with value baz.

write_inventory_per_host_hostvars:
   hosta.com:
     foo: bar
   hostb.com:
     foo: baz

zuul-tenant-conf-check

Run the zuul-admin tenant-conf-check command.

This requires a partial zuul.conf (it only needs the connection entries, and those without any credential information) and a tenant config file. It will validate the syntax of the tenant config file (but not the job configuration of any projects in the tenants).

Role Variables

zuul_tenant_conf_check_zuul_conf_path

The path to the partial zuul.conf to use. This must contain the connection entries, but no credentials are required. Any other sections are ignored.

zuul_tenant_conf_check_tenant_config_path

The path to the tenant config file to check.

zuul_tenant_conf_check_image
Default: quay.io/zuul-ci/zuul-scheduler:latest

The Zuul scheduler container image which contains the zuul-admin command to run.

zuul_tenant_conf_check_registry_credentials

An optional value, expected in the form of a secret, that supplies credential information if zuul_tenant_conf_check_image is in a registry that requires authentication. The format is a dictionary keyed by the registry name. Example:

zuul_tenant_conf_check_registry_credentials:
  docker.io:
    username: 'username'
    password: 'password'

zuul_tenant_conf_check_registry_credentials.[registry_name]

The dictionary key should be the name of the registry

zuul_tenant_conf_check_registry_credentials.[registry_name].username

The registry username.

zuul_tenant_conf_check_registry_credentials.[registry_name].password

The registry password.