CINXE.COM

<!DOCTYPE html> <html class="writer-html5" lang="en"> <head> <meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>General Purpose Roles — Zuul-Jobs documentation</title> <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/css/theme.css" /> <link rel="stylesheet" type="text/css" href="_static/graphviz.css" />  <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script src="_static/jquery.js"></script> <script src="_static/underscore.js"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js"></script> <script src="_static/doctools.js"></script> <script src="_static/sphinx_highlight.js"></script> <script src="_static/js/theme.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Log Roles" href="log-roles.html" /> <link rel="prev" title="Roles" href="roles.html" /> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" style="background: #41B6E6" > <a href="index.html"> <img src="_static/logo.svg" class="logo" alt="Logo"/> </a> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="install.html">Installation</a></li> <li class="toctree-l1"><a class="reference internal" href="policy.html">Policy</a><ul> <li class="toctree-l2"><a class="reference internal" href="policy.html#deprecation-policy">Deprecation Policy</a><ul> <li class="toctree-l3"><a class="reference internal" href="policy.html#new-zuul-features">New Zuul Features</a></li> <li class="toctree-l3"><a class="reference internal" href="policy.html#deprecated-zuul-features">Deprecated Zuul Features</a></li> <li class="toctree-l3"><a class="reference internal" href="policy.html#deprecated-operating-systems">Deprecated Operating Systems</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="policy.html#python-version-policy">Python Version Policy</a></li> <li class="toctree-l2"><a class="reference internal" href="policy.html#coding-guidelines">Coding guidelines</a><ul> <li class="toctree-l3"><a class="reference internal" href="policy.html#role-variable-naming-policy">Role Variable Naming Policy</a></li> <li class="toctree-l3"><a class="reference internal" href="policy.html#support-for-multiple-operating-systems">Support for Multiple Operating Systems</a></li> <li class="toctree-l3"><a class="reference internal" href="policy.html#handling-privileges-on-hosts">Handling privileges on hosts</a></li> <li class="toctree-l3"><a class="reference internal" href="policy.html#output-variables">Output Variables</a></li> <li class="toctree-l3"><a class="reference internal" href="policy.html#installing-dependencies-in-roles">Installing Dependencies in Roles</a></li> <li class="toctree-l3"><a class="reference internal" href="policy.html#ansible-linting-rules">Ansible Linting Rules</a><ul> <li class="toctree-l4"><a class="reference internal" href="policy.html#loops-in-roles">Loops in Roles</a></li> <li class="toctree-l4"><a class="reference internal" href="policy.html#preservation-of-owner-between-executor-and-remote">Preservation Of Owner Between Executor And Remote</a></li> </ul> </li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="policy.html#testing">Testing</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="mirror.html">Mirror Configuration</a></li> <li class="toctree-l1"><a class="reference internal" href="jobs.html">Jobs</a><ul> <li class="toctree-l2"><a class="reference internal" href="general-jobs.html">General Purpose Jobs</a></li> <li class="toctree-l2"><a class="reference internal" href="python-jobs.html">Python Jobs</a></li> <li class="toctree-l2"><a class="reference internal" href="js-jobs.html">Javascript Jobs</a></li> <li class="toctree-l2"><a class="reference internal" href="dib-jobs.html">Diskimage-Builder Jobs</a></li> <li class="toctree-l2"><a class="reference internal" href="docker-jobs.html">Docker Jobs</a></li> <li class="toctree-l2"><a class="reference internal" href="container-jobs.html">Container Jobs</a></li> <li class="toctree-l2"><a class="reference internal" href="go-jobs.html">Go Jobs</a></li> <li class="toctree-l2"><a class="reference internal" href="hashicorp-jobs.html">Hashicorp Jobs</a></li> <li class="toctree-l2"><a class="reference internal" href="haskell-jobs.html">Haskell Jobs</a></li> <li class="toctree-l2"><a class="reference internal" href="helm-jobs.html">Helm Jobs</a></li> <li class="toctree-l2"><a class="reference internal" href="nim-jobs.html">Nim Jobs</a></li> <li class="toctree-l2"><a class="reference internal" href="system-jobs.html">System Jobs</a></li> <li class="toctree-l2"><a class="reference internal" href="deprecated-jobs.html">Deprecated Jobs</a></li> </ul> </li> <li class="toctree-l1 current"><a class="reference internal" href="roles.html">Roles</a><ul class="current"> <li class="toctree-l2 current"><a class="current reference internal" href="#">General Purpose Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="log-roles.html">Log Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="afs-roles.html">AFS Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="build-roles.html">Build Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="cloud-roles.html">Cloud Computing Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="container-roles.html">Container Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="deprecated-roles.html">Deprecated and Test Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="dib-roles.html">Diskimage-Builder Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="galaxy-roles.html">Ansible Galaxy Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="go-roles.html">Go Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="hashicorp-roles.html">Packer Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="haskell-roles.html">Haskell Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="helm-roles.html">Helm Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="java-roles.html">Java Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="js-roles.html">Javascript Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="kubernetes-roles.html">Kubernetes Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="launchpad-roles.html">Launchpad Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="nim-roles.html">Nim Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="puppet-roles.html">Puppet Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="python-roles.html">Python Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="rust-roles.html">Rust Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="system-roles.html">System Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="translation-roles.html">Translation Roles</a></li> <li class="toctree-l2"><a class="reference internal" href="logjuicer-roles.html">LogJuicer Roles</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="docker-image.html">Container Images</a><ul> <li class="toctree-l2"><a class="reference internal" href="docker-image.html#run-an-intermediate-container-registry">Run an Intermediate Container Registry</a></li> <li class="toctree-l2"><a class="reference internal" href="docker-image.html#create-parent-jobs">Create Parent Jobs</a><ul> <li class="toctree-l3"><a class="reference internal" href="docker-image.html#yoursite-buildset-registry">yoursite-buildset-registry</a></li> <li class="toctree-l3"><a class="reference internal" href="docker-image.html#yoursite-build-docker-image">yoursite-build-docker-image</a></li> <li class="toctree-l3"><a class="reference internal" href="docker-image.html#yoursite-upload-docker-image">yoursite-upload-docker-image</a></li> <li class="toctree-l3"><a class="reference internal" href="docker-image.html#yoursite-promote-docker-image">yoursite-promote-docker-image</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="docker-image.html#system-architecture">System Architecture</a></li> <li class="toctree-l2"><a class="reference internal" href="docker-image.html#using-the-jobs">Using the Jobs</a><ul> <li class="toctree-l3"><a class="reference internal" href="docker-image.html#a-repository-with-producers-and-consumers">A Repository with Producers and Consumers</a></li> <li class="toctree-l3"><a class="reference internal" href="docker-image.html#a-repository-with-only-producers">A Repository with Only Producers</a></li> <li class="toctree-l3"><a class="reference internal" href="docker-image.html#publishing-an-image">Publishing an Image</a></li> </ul> </li> </ul> </li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #41B6E6" > <a href="index.html">Zuul-Jobs</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item"><a href="roles.html">Roles</a></li> <li class="breadcrumb-item active">General Purpose Roles</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/general-roles.rst.txt" rel="nofollow"> View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="general-purpose-roles"> <h1>General Purpose Roles<a class="headerlink" href="#general-purpose-roles" title="Permalink to this heading"></a></h1> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-add-authorized-keys"> add-authorized-keys<a class="headerlink" href="#role-add-authorized-keys" title="Permalink to this definition"></a></dt> <dd>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 <cite>autohold</cite> 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: <div class="highlight-yaml notranslate"><div class="highlight"><pre>- 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 </pre></div> </div> <div class="admonition caution"> 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. </div> Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-authorized-keys.ssh_public_keys"> ssh_public_keys<a class="headerlink" href="#rolevar-add-authorized-keys.ssh_public_keys" title="Permalink to this definition"></a> </dt> <dd>A list of keys to inject. <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-authorized-keys.ssh_public_keys.public_key"> ssh_public_keys.public_key<a class="headerlink" href="#rolevar-add-authorized-keys.ssh_public_keys.public_key" title="Permalink to this definition"></a> </dt> <dd>A public key to inject into authorized_keys, or a URL to a public key. </dd></dl> </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-add-build-sshkey"> add-build-sshkey<a class="headerlink" href="#role-add-build-sshkey" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-sshkey.zuul_temp_ssh_key"> zuul_temp_ssh_key<a class="headerlink" href="#rolevar-add-build-sshkey.zuul_temp_ssh_key" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">``{{ zuul.executor.work_root }}/{{ zuul.build }}_id_rsa``</code> </dt> <dd>Where to put the newly-generated SSH private key. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-sshkey.zuul_ssh_key_dest"> zuul_ssh_key_dest<a class="headerlink" href="#rolevar-add-build-sshkey.zuul_ssh_key_dest" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">``id_{{ zuul_ssh_key_algorithm }}``</code> </dt> <dd>File name for the the newly-generated SSH private key. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-sshkey.zuul_build_sshkey_cleanup"> zuul_build_sshkey_cleanup<a class="headerlink" href="#rolevar-add-build-sshkey.zuul_build_sshkey_cleanup" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">false</code> </dt> <dd>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. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-sshkey.zuul_ssh_key_algorithm"> zuul_ssh_key_algorithm<a class="headerlink" href="#rolevar-add-build-sshkey.zuul_ssh_key_algorithm" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">rsa</code> </dt> <dd>The digital signature algorithm to be used to generate the key. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-sshkey.zuul_ssh_key_size"> zuul_ssh_key_size<a class="headerlink" href="#rolevar-add-build-sshkey.zuul_ssh_key_size" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">3072</code> </dt> <dd>Specifies the number of bits in the key to create. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-add-build-winrm-cert"> add-build-winrm-cert<a class="headerlink" href="#role-add-build-winrm-cert" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-winrm-cert.build_winrm_cert_credentials"> build_winrm_cert_credentials<a class="headerlink" href="#rolevar-add-build-winrm-cert.build_winrm_cert_credentials" title="Permalink to this definition"></a> </dt> <dd>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. <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-winrm-cert.build_winrm_cert_credentials.username"> build_winrm_cert_credentials.username<a class="headerlink" href="#rolevar-add-build-winrm-cert.build_winrm_cert_credentials.username" title="Permalink to this definition"></a> </dt> <dd>The username of the account. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-winrm-cert.build_winrm_cert_credentials.password"> build_winrm_cert_credentials.password<a class="headerlink" href="#rolevar-add-build-winrm-cert.build_winrm_cert_credentials.password" title="Permalink to this definition"></a> </dt> <dd>The password of the account. </dd></dl> </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-winrm-cert.build_winrm_cert_change_password"> build_winrm_cert_change_password<a class="headerlink" href="#rolevar-add-build-winrm-cert.build_winrm_cert_change_password" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">``False``</code> </dt> <dd>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. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-winrm-cert.zuul_temp_winrm_name"> zuul_temp_winrm_name<a class="headerlink" href="#rolevar-add-build-winrm-cert.zuul_temp_winrm_name" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">``{{ zuul.build }}_winrm``</code> </dt> <dd>The base name of the certificate file. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-winrm-cert.zuul_temp_winrm_cert"> zuul_temp_winrm_cert<a class="headerlink" href="#rolevar-add-build-winrm-cert.zuul_temp_winrm_cert" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">``{{ zuul.executor.work_root }}/{{ zuul_temp_winrm_name }}.crt``</code> </dt> <dd>File name for the the newly-generated certificate. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-winrm-cert.zuul_temp_winrm_key"> zuul_temp_winrm_key<a class="headerlink" href="#rolevar-add-build-winrm-cert.zuul_temp_winrm_key" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">``{{ zuul.executor.work_root }}/{{ zuul_temp_winrm_name }}.key``</code> </dt> <dd>File name for the the newly-generated private key. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-winrm-cert.zuul_temp_winrm_pfx"> zuul_temp_winrm_pfx<a class="headerlink" href="#rolevar-add-build-winrm-cert.zuul_temp_winrm_pfx" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">``{{ zuul.executor.work_root }}/{{ zuul_temp_winrm_name }}.pfx``</code> </dt> <dd>Executor-local file name for the the exported certificate. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-build-winrm-cert.zuul_temp_winrm_remote_tempfile"> zuul_temp_winrm_remote_tempfile<a class="headerlink" href="#rolevar-add-build-winrm-cert.zuul_temp_winrm_remote_tempfile" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">``~/appdata/local/temp/{{ zuul_temp_winrm_name }}.pfx``</code> </dt> <dd>Remote temporary location for the certificate during import. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-add-gpgkey"> add-gpgkey<a class="headerlink" href="#role-add-gpgkey" title="Permalink to this definition"></a></dt> <dd>Install a GPG private key onto a host. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-gpgkey.gpg_key"> gpg_key<a class="headerlink" href="#rolevar-add-gpgkey.gpg_key" title="Permalink to this definition"></a> </dt> <dd><blockquote> <div>Complex argument which contains the GPG private key. It is expected that this argument comes from a <cite>Secret</cite>. </div></blockquote> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-gpgkey.gpg_key.private"> gpg_key.private<a class="headerlink" href="#rolevar-add-gpgkey.gpg_key.private" title="Permalink to this definition"></a> </dt> <dd>The ascii-armored contents of the GPG private key. </dd></dl> </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-add-sshkey"> add-sshkey<a class="headerlink" href="#role-add-sshkey" title="Permalink to this definition"></a></dt> <dd>Add an ssh key to the host so that non-ansible ssh connections can be made. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-sshkey.ssh_key"> ssh_key<a class="headerlink" href="#rolevar-add-sshkey.ssh_key" title="Permalink to this definition"></a> </dt> <dd>Complex argument which contains the ssh key information. It is expected that this argument comes from a <cite>Secret</cite>. <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-sshkey.ssh_key.ssh_known_hosts"> ssh_key.ssh_known_hosts<a class="headerlink" href="#rolevar-add-sshkey.ssh_key.ssh_known_hosts" title="Permalink to this definition"></a> </dt> <dd>String containing known host signature for the remote host. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-sshkey.ssh_key.ssh_private_key"> ssh_key.ssh_private_key<a class="headerlink" href="#rolevar-add-sshkey.ssh_key.ssh_private_key" title="Permalink to this definition"></a> </dt> <dd>Contents of the ssh private key to use. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-add-sshkey.ssh_key.fqdn"> ssh_key.fqdn<a class="headerlink" href="#rolevar-add-sshkey.ssh_key.fqdn" title="Permalink to this definition"></a> </dt> <dd>The FQDN of the remote host. </dd></dl> </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-bindep"> bindep<a class="headerlink" href="#role-bindep" title="Permalink to this definition"></a></dt> <dd>Installs distro packages using bindep tool Looks for a <code class="docutils literal notranslate">bindep.txt</code> in a project’s source directory, or failing that a <code class="docutils literal notranslate">other-requirements.txt</code>. If one exists, run <code class="docutils literal notranslate">bindep</code> on the file to produce a list of required distro packages that do not exist and then install the missing packages. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-bindep.bindep_dir"> bindep_dir<a class="headerlink" href="#rolevar-bindep.bindep_dir" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ zuul.project.src_dir }}</code> </dt> <dd>The directory to look for bindep files in. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-bindep.bindep_profile"> bindep_profile<a class="headerlink" href="#rolevar-bindep.bindep_profile" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">test</code> </dt> <dd>A specific bindep profile to request. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-bindep.bindep_file"> bindep_file<a class="headerlink" href="#rolevar-bindep.bindep_file" title="Permalink to this definition"></a> </dt> <dd>Path or list of paths to a specific bindep file(s) to read from. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-bindep.bindep_command"> bindep_command<a class="headerlink" href="#rolevar-bindep.bindep_command" title="Permalink to this definition"></a> </dt> <dd>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. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-bindep.bindep_fallback"> bindep_fallback<a class="headerlink" href="#rolevar-bindep.bindep_fallback" title="Permalink to this definition"></a> </dt> <dd>Path to a bindep fallback file to be used if no bindep file can be found in <a class="reference internal" href="#rolevar-bindep.bindep_dir" title="rolevar-bindep.bindep_dir">bindep.bindep_dir</a>. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-buildset-artifacts-location"> buildset-artifacts-location<a class="headerlink" href="#role-buildset-artifacts-location" title="Permalink to this definition"></a></dt> <dd>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: <ul class="simple"> <li>Create a repository</li> <li>Fetch the repository to “{{ zuul.executor.log_root }}/buildset”</li> <li>Use the buildset-artifacts-location role</li> </ul> rpm-test jobs: <ul class="simple"> <li>Install “{{ buildset_artficats_url }}” yum repository</li> <li>Run integration tests</li> </ul> <div class="highlight-yaml notranslate"><div class="highlight"><pre>layout: jobs: - rpm-build - rpm-test1: dependencies: - rpm-build - rpm-test2: dependencies: - rpm-build </pre></div> </div> Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-buildset-artifacts-location.zuul_log_url"> zuul_log_url<a class="headerlink" href="#rolevar-buildset-artifacts-location.zuul_log_url" title="Permalink to this definition"></a> </dt> <dd>Base URL where logs are to be found. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-buildset-artifacts-location.zuul_log_path"> zuul_log_path<a class="headerlink" href="#rolevar-buildset-artifacts-location.zuul_log_path" title="Permalink to this definition"></a> </dt> <dd>Path of the logs. This optional when the role is used after ‘upload-logs’. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-clear-firewall"> clear-firewall<a class="headerlink" href="#role-clear-firewall" title="Permalink to this definition"></a></dt> <dd>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. </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-configure-mirrors"> configure-mirrors<a class="headerlink" href="#role-configure-mirrors" title="Permalink to this definition"></a></dt> <dd>An ansible role to configure services to use mirrors. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-configure-mirrors.mirror_fqdn"> mirror_fqdn<a class="headerlink" href="#rolevar-configure-mirrors.mirror_fqdn" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ zuul_site_mirror_fqdn }}</code> </dt> <dd>The base host for mirror servers. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-configure-mirrors.mirror_use_ssl"> mirror_use_ssl<a class="headerlink" href="#rolevar-configure-mirrors.mirror_use_ssl" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">False</code> </dt> <dd>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. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-configure-mirrors.pypi_fqdn"> pypi_fqdn<a class="headerlink" href="#rolevar-configure-mirrors.pypi_fqdn" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ mirror_fqdn }}</code> </dt> <dd>The base host for PyPi mirror server. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-configure-mirrors.pypi_mirror"> pypi_mirror<a class="headerlink" href="#rolevar-configure-mirrors.pypi_mirror" title="Permalink to this definition"></a> </dt> <dd>URL to override the generated pypi mirror url based on <a class="reference internal" href="#rolevar-configure-mirrors.pypi_fqdn" title="rolevar-configure-mirrors.pypi_fqdn">configure-mirrors.pypi_fqdn</a>. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-configure-mirrors.set_apt_mirrors_trusted"> set_apt_mirrors_trusted<a class="headerlink" href="#rolevar-configure-mirrors.set_apt_mirrors_trusted" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">False</code> </dt> <dd>Set to True in order to tag APT mirrors as trusted, needed when accessing unsigned mirrors with newer releases like Ubuntu Bionic. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-configure-mirrors.enable_deb_src_repos"> enable_deb_src_repos<a class="headerlink" href="#rolevar-configure-mirrors.enable_deb_src_repos" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">False</code> </dt> <dd>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. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-configure-mirrors.configure_mirrors_extra_repos"> configure_mirrors_extra_repos<a class="headerlink" href="#rolevar-configure-mirrors.configure_mirrors_extra_repos" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">True</code> </dt> <dd>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). </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-configure-mirrors.configure_mirrors_components_9_stream"> configure_mirrors_components_9_stream<a class="headerlink" href="#rolevar-configure-mirrors.configure_mirrors_components_9_stream" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">See `vars/CentOS-9.yaml`</code> </dt> <dd>A list of the components that should be redirected to the <cite>mirror_fqdn</cite> when setting up a CentOS 9-stream host. For example, your mirror may only mirror some components, or not the debug/source components, etc. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-copy-build-sshkey"> copy-build-sshkey<a class="headerlink" href="#role-copy-build-sshkey" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-copy-build-sshkey.zuul_temp_ssh_key"> zuul_temp_ssh_key<a class="headerlink" href="#rolevar-copy-build-sshkey.zuul_temp_ssh_key" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">"{{ zuul.executor.work_root }}/{{ zuul.build }}_id_rsa"</code> </dt> <dd>Where to source the build private key </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-copy-build-sshkey.copy_sshkey_target_user"> copy_sshkey_target_user<a class="headerlink" href="#rolevar-copy-build-sshkey.copy_sshkey_target_user" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">root</code> </dt> <dd>The user to copy the sshkey to. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-download-artifact"> download-artifact<a class="headerlink" href="#role-download-artifact" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-download-artifact.download_artifact_api"> download_artifact_api<a class="headerlink" href="#rolevar-download-artifact.download_artifact_api" title="Permalink to this definition"></a> </dt> <dd>The Zuul API endpoint to use. Example: <code class="docutils literal notranslate">https://zuul.example.org/api/tenant/{{ zuul.tenant }}</code> </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-download-artifact.download_artifact_pipeline"> download_artifact_pipeline<a class="headerlink" href="#rolevar-download-artifact.download_artifact_pipeline" title="Permalink to this definition"></a> </dt> <dd>The pipeline in which the previous build ran. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-download-artifact.download_artifact_job"> download_artifact_job<a class="headerlink" href="#rolevar-download-artifact.download_artifact_job" title="Permalink to this definition"></a> </dt> <dd>The job of the previous build. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-download-artifact.download_artifact_type"> download_artifact_type<a class="headerlink" href="#rolevar-download-artifact.download_artifact_type" title="Permalink to this definition"></a> </dt> <dd>The artifact type. This is the value of the <code class="docutils literal notranslate">type</code> field in the artifact metadata. This can be a string or a list of strings. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-download-artifact.download_artifact_query"> download_artifact_query<a class="headerlink" href="#rolevar-download-artifact.download_artifact_query" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">change={{ zuul.change }}&patchset={{ zuul.patchset }}&pipeline={{ download_artifact_pipeline }}&job_name={{ download_artifact_job }}</code> </dt> <dd>The query to use to find the build. Normally the default is used. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-download-artifact.download_artifact_directory"> download_artifact_directory<a class="headerlink" href="#rolevar-download-artifact.download_artifact_directory" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ zuul.executor.work_root }}</code> </dt> <dd>The directory in which to place the downloaded artifacts. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-dstat-graph"> dstat-graph<a class="headerlink" href="#role-dstat-graph" title="Permalink to this definition"></a></dt> <dd>Run dstat_graph This requires that the <a class="reference internal" href="#role-run-dstat" title="role-run-dstat">run-dstat</a> role be previously used. Add this to a post-run playbook to run <code class="docutils literal notranslate">dstat_graph</code> to graph data from dstat. Use the <a class="reference internal" href="#role-ensure-dstat-graph" title="role-ensure-dstat-graph">ensure-dstat-graph</a> 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 <code class="docutils literal notranslate">dstat.html</code> in the <code class="docutils literal notranslate">zuul-output/logs</code> directory. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-dstat-graph.dstat_graph_cache_path"> dstat_graph_cache_path<a class="headerlink" href="#rolevar-dstat-graph.dstat_graph_cache_path" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">/opt/cache/dstat_graph</code> </dt> <dd>The role will check this location to see if a cached copy of dstat_graph is available. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-dstat-graph.dstat_graph_download_path"> dstat_graph_download_path<a class="headerlink" href="#rolevar-dstat-graph.dstat_graph_download_path" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">/tmp/dstat_graph</code> </dt> <dd>If a cached copy is not available, the role will check if dstat_graph was previously downloaded to this location. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-dstat-graph.dstat_data_path"> dstat_data_path<a class="headerlink" href="#rolevar-dstat-graph.dstat_data_path" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">"{{ ansible_user_dir }}/zuul-output/logs/dstat.csv"</code> </dt> <dd>The path to the dstat data file. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-emit-job-header"> emit-job-header<a class="headerlink" href="#role-emit-job-header" title="Permalink to this definition"></a></dt> <dd>Log a few lines about the job. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-emit-job-header.zuul_log_url"> zuul_log_url<a class="headerlink" href="#rolevar-emit-job-header.zuul_log_url" title="Permalink to this definition"></a> </dt> <dd>Base URL where logs are to be found. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-emit-job-header.zuul_log_path_shard_build"> zuul_log_path_shard_build<a class="headerlink" href="#rolevar-emit-job-header.zuul_log_path_shard_build" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">False</code> </dt> <dd>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 <a class="reference internal" href="log-roles.html#rolevar-set-zuul-log-path-fact.zuul_log_path_shard_build" title="rolevar-set-zuul-log-path-fact.zuul_log_path_shard_build">set-zuul-log-path-fact.zuul_log_path_shard_build</a> </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-enable-fips"> enable-fips<a class="headerlink" href="#role-enable-fips" title="Permalink to this definition"></a></dt> <dd>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. </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-enable-netconsole"> enable-netconsole<a class="headerlink" href="#role-enable-netconsole" title="Permalink to this definition"></a></dt> <dd>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 <code class="docutils literal notranslate">netconsole_remote_ip</code> and <code class="docutils literal notranslate">netconsole_remote_port</code> variables must be set. This host can capture the logs with a command like: <div class="highlight-default notranslate"><div class="highlight"><pre>$ nc -v -u -l -p 6666 | tee console-output.log </pre></div> </div> or: <div class="highlight-default notranslate"><div class="highlight"><pre>$ socat udp-recv:6666 - | tee console-output.log </pre></div> </div> One further trick is to send interesting data to <code class="docutils literal notranslate">/dev/kmsg</code>, this should make it across the netconsole even if the main interface has been disabled, etc. e.g.: <div class="highlight-default notranslate"><div class="highlight"><pre>$ ip addr | sudo tee /dev/kmsg </pre></div> </div> Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-enable-netconsole.netconsole_remote_ip"> netconsole_remote_ip<a class="headerlink" href="#rolevar-enable-netconsole.netconsole_remote_ip" title="Permalink to this definition"></a> </dt> <dd>The IP address of the remote host to send to. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-enable-netconsole.netconsole_remote_port"> netconsole_remote_port<a class="headerlink" href="#rolevar-enable-netconsole.netconsole_remote_port" title="Permalink to this definition"></a> </dt> <dd>The port listening on the remote host. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-enable-ua-subscription"> enable-ua-subscription<a class="headerlink" href="#role-enable-ua-subscription" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-enable-ua-subscription.ubuntu_ua_token"> ubuntu_ua_token<a class="headerlink" href="#rolevar-enable-ua-subscription.ubuntu_ua_token" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">None</code> Type: dict </dt> <dd>Dict used to specify Ubuntu advantage subscription information. ubuntu_ua_token.token is a subscription key. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-encrypt-file"> encrypt-file<a class="headerlink" href="#role-encrypt-file" title="Permalink to this definition"></a></dt> <dd>encrypt-file Import GPG keys and encrypt a file Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-encrypt-file.encrypt_file"> encrypt_file<a class="headerlink" href="#rolevar-encrypt-file.encrypt_file" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">*undefined*</code> </dt> <dd>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 <code class="docutils literal notranslate">.gpg</code> added. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-encrypt-file.encrypt_file_recipients"> encrypt_file_recipients<a class="headerlink" href="#rolevar-encrypt-file.encrypt_file_recipients" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">[]</code> </dt> <dd>List of recipients who will be able to decrypt the file(s). This should be a list of <code class="docutils literal notranslate">name</code> keys that exist in <code class="docutils literal notranslate">encrypt_file_keys</code>. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-encrypt-file.encrypt_file_keys"> encrypt_file_keys<a class="headerlink" href="#rolevar-encrypt-file.encrypt_file_keys" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">[]</code> </dt> <dd>Keys available to encrypt the file with. Each entry is a dictionary with keys <ul class="simple"> <li><code class="docutils literal notranslate">name</code> : a freeform string identifier</li> <li><code class="docutils literal notranslate">key_id</code>: the GPG key ID</li> <li><code class="docutils literal notranslate">gpg_asc</code>: the GPG ASCII-armored public key. If the public-key is not already available, it will be imported to GPG.</li> </ul> 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. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-ensure-bazelisk"> ensure-bazelisk<a class="headerlink" href="#role-ensure-bazelisk" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-ensure-bazelisk.bazelisk_version"> bazelisk_version<a class="headerlink" href="#rolevar-ensure-bazelisk.bazelisk_version" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">v1.3.0</code> </dt> <dd>Version of bazelisk to install. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-ensure-bazelisk.bazelisk_arch"> bazelisk_arch<a class="headerlink" href="#rolevar-ensure-bazelisk.bazelisk_arch" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">linux-amd64</code> </dt> <dd>Architecture to install. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-ensure-bazelisk.bazelisk_url"> bazelisk_url<a class="headerlink" href="#rolevar-ensure-bazelisk.bazelisk_url" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">https://github.com/bazelbuild/bazelisk/releases/download/{{ bazelisk_version }}/bazelisk-{{ bazelisk_arch }}</code> </dt> <dd>The URL from which to download bazelisk. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-ensure-bazelisk.bazelisk_target"> bazelisk_target<a class="headerlink" href="#rolevar-ensure-bazelisk.bazelisk_target" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">"{{ ansible_user_dir }}/.local/bin/bazelisk"</code> </dt> <dd>Where to install bazelisk. If the role downloads bazelisk, it will set <a class="reference internal" href="#rolevar-ensure-bazelisk.bazelisk_executable" title="rolevar-ensure-bazelisk.bazelisk_executable">ensure-bazelisk.bazelisk_executable</a> to this value as well. </dd></dl> Output Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-ensure-bazelisk.bazelisk_executable"> bazelisk_executable<a class="headerlink" href="#rolevar-ensure-bazelisk.bazelisk_executable" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">bazelisk</code> </dt> <dd>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. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-ensure-dhall"> ensure-dhall<a class="headerlink" href="#role-ensure-dhall" title="Permalink to this definition"></a></dt> <dd>Ensure dhall is installed Installs the specified version of the haskell implementation. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-ensure-dhall.dhall_version"> dhall_version<a class="headerlink" href="#rolevar-ensure-dhall.dhall_version" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">1.31.1</code> </dt> <dd>The dhall version. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-ensure-dstat-graph"> ensure-dstat-graph<a class="headerlink" href="#role-ensure-dstat-graph" title="Permalink to this definition"></a></dt> <dd>Install dstat_graph This downloads <code class="docutils literal notranslate">dstat_graph</code> 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 <a class="reference internal" href="#role-dstat-graph" title="role-dstat-graph">dstat-graph</a>. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-ensure-dstat-graph.dstat_graph_cache_path"> dstat_graph_cache_path<a class="headerlink" href="#rolevar-ensure-dstat-graph.dstat_graph_cache_path" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">/opt/cache/dstat_graph</code> </dt> <dd>The role will check this location to see if a cached copy of dstat_graph is available. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-ensure-dstat-graph.dstat_graph_download_path"> dstat_graph_download_path<a class="headerlink" href="#rolevar-ensure-dstat-graph.dstat_graph_download_path" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">/tmp/dstat_graph</code> </dt> <dd>If a cached copy is not available, the role will download dstat_graph to this location. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-ensure-markdownlint"> ensure-markdownlint<a class="headerlink" href="#role-ensure-markdownlint" title="Permalink to this definition"></a></dt> <dd>Ensure markdownlint-cli from NPM is installed. </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-ensure-shake"> ensure-shake<a class="headerlink" href="#role-ensure-shake" title="Permalink to this definition"></a></dt> <dd>Ensure shake is installed Installs the shake tool using the distro package. </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-fetch-markdownlint"> fetch-markdownlint<a class="headerlink" href="#role-fetch-markdownlint" title="Permalink to this definition"></a></dt> <dd>Collect output from a markdownlint run. Assumes you will only run one repo, and one node. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-fetch-markdownlint.zuul_work_dir"> zuul_work_dir<a class="headerlink" href="#rolevar-fetch-markdownlint.zuul_work_dir" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ zuul.project.src_dir }}</code> </dt> <dd>The location of the main working directory of the job. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-git-prepare-nodecache"> git-prepare-nodecache<a class="headerlink" href="#role-git-prepare-nodecache" title="Permalink to this definition"></a></dt> <dd>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 <cite>prepare-workspace-git</cite>. The path to the resulting archive file will be stored in the <cite>git_cache_file</cite> 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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-git-prepare-nodecache.git_cache_root"> git_cache_root<a class="headerlink" href="#rolevar-git-prepare-nodecache.git_cache_root" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ansible_user_dir }}/git-cache"</code> </dt> <dd>Directory where the git cache should be prepared. Usually this should not be changed. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-intercept-job"> intercept-job<a class="headerlink" href="#role-intercept-job" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-intercept-job.intercept_job_pub_key_path"> intercept_job_pub_key_path<a class="headerlink" href="#rolevar-intercept-job.intercept_job_pub_key_path" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">``{{ zuul.project.src_dir }}/intercept_job.pub``</code> </dt> <dd>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. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-intercept-job.intercept_job_stop_path"> intercept_job_stop_path<a class="headerlink" href="#rolevar-intercept-job.intercept_job_stop_path" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">``{{ zuul.project.src_dir }}/intercept_job.stop``</code> </dt> <dd>If this file exists, the intercept-job role will stop waiting and allow the playbook to continue. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-log-inventory"> log-inventory<a class="headerlink" href="#role-log-inventory" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-log-inventory.zuul_info_dir"> zuul_info_dir<a class="headerlink" href="#rolevar-log-inventory.zuul_info_dir" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ zuul.executor.log_root }}/zuul-info</code> </dt> <dd>The directory path to store the inventory file. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-markdownlint"> markdownlint<a class="headerlink" href="#role-markdownlint" title="Permalink to this definition"></a></dt> <dd>Run markdownlint against all markdown files in the given project. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-markdownlint.zuul_work_dir"> zuul_work_dir<a class="headerlink" href="#rolevar-markdownlint.zuul_work_dir" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ zuul.project.src_dir }}</code> </dt> <dd>Directory to search for markdown files in. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-multi-node-bridge"> multi-node-bridge<a class="headerlink" href="#role-multi-node-bridge" title="Permalink to this definition"></a></dt> <dd>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: <ul class="simple"> <li>Install and start <code class="docutils literal notranslate">openvswitch</code></li> <li>Set up a <code class="docutils literal notranslate">br-infra</code> bridge on all nodes</li> <li>Set up the connectivity between the switch and the peer with a virtual port</li> <li>Set up an ip address on the bridge interface:</li> </ul> <div class="highlight-default notranslate"><div class="highlight"><pre>172.24.4.1/23 # switch node 172.41.4.2/23 # first peer 172.41.4.3/23 # second peer ... </pre></div> </div> Role requirements This role requires and expects two groups to be set up in the Ansible host inventory in order to work: <ul class="simple"> <li><code class="docutils literal notranslate">switch</code> (the node acting as the switch)</li> <li><code class="docutils literal notranslate">peers</code> (nodes connected to the virtual switch ports)</li> </ul> Role variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-multi-node-bridge.bridge_vni_offset"> bridge_vni_offset<a class="headerlink" href="#rolevar-multi-node-bridge.bridge_vni_offset" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">1000000</code> </dt> <dd>VXLAN Network Identifier offset (openvswitch key). </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-multi-node-bridge.bridge_mtu"> bridge_mtu<a class="headerlink" href="#rolevar-multi-node-bridge.bridge_mtu" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">Smallest mtu less 50 bytes for vxlan overhead</code> </dt> <dd>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. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-multi-node-bridge.bridge_name"> bridge_name<a class="headerlink" href="#rolevar-multi-node-bridge.bridge_name" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">br-infra</code> </dt> <dd>Name of the bridge interface. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-multi-node-bridge.bridge_configure_address"> bridge_configure_address<a class="headerlink" href="#rolevar-multi-node-bridge.bridge_configure_address" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">true</code> </dt> <dd>Whether or not to configure an IP address on the bridge interface. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-multi-node-bridge.bridge_authorize_internal_traffic"> bridge_authorize_internal_traffic<a class="headerlink" href="#rolevar-multi-node-bridge.bridge_authorize_internal_traffic" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">false</code> </dt> <dd>When <code class="docutils literal notranslate">bridge_configure_address</code> is <code class="docutils literal notranslate">true</code>, whether or not to set up firewall rules to allow traffic freely within the bridge subnet (<code class="docutils literal notranslate">bridge_address_prefix</code>.0/<code class="docutils literal notranslate">bridge_address_subnet</code>). </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-multi-node-bridge.bridge_address_prefix"> bridge_address_prefix<a class="headerlink" href="#rolevar-multi-node-bridge.bridge_address_prefix" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">172.24.4</code> </dt> <dd>The IP address range prefix. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-multi-node-bridge.bridge_address_offset"> bridge_address_offset<a class="headerlink" href="#rolevar-multi-node-bridge.bridge_address_offset" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">1</code> </dt> <dd>The IP address offset, used with <code class="docutils literal notranslate">bridge_address_prefix</code> to provide the full IP address. The initial offset defines the IP address of the switch node in the virtual network. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-multi-node-bridge.bridge_address_subnet"> bridge_address_subnet<a class="headerlink" href="#rolevar-multi-node-bridge.bridge_address_subnet" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">23</code> </dt> <dd>The IP address range CIDR/subnet. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-multi-node-bridge.install_ovs"> install_ovs<a class="headerlink" href="#rolevar-multi-node-bridge.install_ovs" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">true</code> </dt> <dd>Whether or not to install openvswitch. It can be set to false when ovs installation is taken care outside of the role. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-multi-node-firewall"> multi-node-firewall<a class="headerlink" href="#role-multi-node-firewall" title="Permalink to this definition"></a></dt> <dd>Multinode firewall is configured. This role is intended to install iptables and configure firewall. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-multi-node-firewall.iptables_package"> iptables_package<a class="headerlink" href="#rolevar-multi-node-firewall.iptables_package" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">iptables</code> </dt> <dd>Install the distribution package for Iptables. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-multi-node-hosts-file"> multi-node-hosts-file<a class="headerlink" href="#role-multi-node-hosts-file" title="Permalink to this definition"></a></dt> <dd>Configures the inventory hostnames in a multi-node job resolve to their respective private ipv4 addresses through the /etc/hosts file on each node. </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-multi-node-known-hosts"> multi-node-known-hosts<a class="headerlink" href="#role-multi-node-known-hosts" title="Permalink to this definition"></a></dt> <dd>Configures the file <code class="docutils literal notranslate">/etc/ssh/ssh_known_hosts</code> on each node in a multi-node job to contain all known host names. </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-persistent-firewall"> persistent-firewall<a class="headerlink" href="#role-persistent-firewall" title="Permalink to this definition"></a></dt> <dd>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. </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-prepare-workspace"> prepare-workspace<a class="headerlink" href="#role-prepare-workspace" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-prepare-workspace.zuul_workspace_root"> zuul_workspace_root<a class="headerlink" href="#rolevar-prepare-workspace.zuul_workspace_root" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">.</code> </dt> <dd>The directory into which the source repositories are copied. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-prepare-workspace-git"> prepare-workspace-git<a class="headerlink" href="#role-prepare-workspace-git" title="Permalink to this definition"></a></dt> <dd>Mirror the local git repos to remote nodes This role uses git operations (unlike <a class="reference internal" href="#role-prepare-workspace" title="role-prepare-workspace">prepare-workspace</a> 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 <cite>cached_repos_root</cite> directory. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-prepare-workspace-git.cached_repos_root"> cached_repos_root<a class="headerlink" href="#rolevar-prepare-workspace-git.cached_repos_root" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">/opt/git</code> </dt> <dd>The root of the cached repos. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-prepare-workspace-git.prepare_workspace_sync_required_projects_only"> prepare_workspace_sync_required_projects_only<a class="headerlink" href="#rolevar-prepare-workspace-git.prepare_workspace_sync_required_projects_only" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">False</code> Type: bool </dt> <dd>A flag which if set to true, filters the to be synchronized project list to only use projects which are required by the job. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-prepare-workspace-git.mirror_workspace_quiet"> mirror_workspace_quiet<a class="headerlink" href="#rolevar-prepare-workspace-git.mirror_workspace_quiet" title="Permalink to this definition"></a> </dt> <dd>This value is ignored; it should be removed from job configuration. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-prepare-workspace-git.zuul_workspace_root"> zuul_workspace_root<a class="headerlink" href="#rolevar-prepare-workspace-git.zuul_workspace_root" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">"{{ ansible_user_dir }}"</code> </dt> <dd>The root of the workspace in which the repos are mirrored. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-prepare-workspace-openshift"> prepare-workspace-openshift<a class="headerlink" href="#role-prepare-workspace-openshift" title="Permalink to this definition"></a></dt> <dd>Prepare remote workspaces in OpenShift This role can be used instead of the <a class="reference internal" href="#role-prepare-workspace" title="role-prepare-workspace">prepare-workspace</a> role when the synchronize module doesn’t work with kubectl connection. It copies the prepared source repos to the pods’ cwd using the <cite>oc rsync</cite> 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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-prepare-workspace-openshift.openshift_pods"> openshift_pods<a class="headerlink" href="#rolevar-prepare-workspace-openshift.openshift_pods" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ zuul.resources }}</code> </dt> <dd>The dictionary of pod name, pod information to copy the sources to. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-post-reboot-tasks"> post-reboot-tasks<a class="headerlink" href="#role-post-reboot-tasks" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-post-reboot-tasks.nslookup_target"> nslookup_target<a class="headerlink" href="#rolevar-post-reboot-tasks.nslookup_target" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">None</code> Type: str </dt> <dd>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. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-remove-build-sshkey"> remove-build-sshkey<a class="headerlink" href="#role-remove-build-sshkey" title="Permalink to this definition"></a></dt> <dd>Remove the per-build SSH key from all hosts The complement to <a class="reference internal" href="#role-add-build-sshkey" title="role-add-build-sshkey">add-build-sshkey</a>. It removes the build’s SSH key from the authorized_keys files of all remote hosts. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-remove-build-sshkey.zuul_temp_ssh_key"> zuul_temp_ssh_key<a class="headerlink" href="#rolevar-remove-build-sshkey.zuul_temp_ssh_key" title="Permalink to this definition"></a> </dt> <dd>Where the per-build SSH private key was stored. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-remove-build-sshkey.zuul_ssh_key_algorithm"> zuul_ssh_key_algorithm<a class="headerlink" href="#rolevar-remove-build-sshkey.zuul_ssh_key_algorithm" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">rsa</code> </dt> <dd>The digital signature algorithm which was used to generate the key. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-remove-build-winrm-cert"> remove-build-winrm-cert<a class="headerlink" href="#role-remove-build-winrm-cert" title="Permalink to this definition"></a></dt> <dd>Remove the per-build WinRM certificate from all hosts The complement to <a class="reference internal" href="#role-add-build-winrm-cert" title="role-add-build-winrm-cert">add-build-winrm-cert</a>. It removes the build’s WinRM certificate from WSMan registry of all Windows hosts. </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-remove-gpgkey"> remove-gpgkey<a class="headerlink" href="#role-remove-gpgkey" title="Permalink to this definition"></a></dt> <dd>Remove an added GPG key from the host. </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-remove-sshkey"> remove-sshkey<a class="headerlink" href="#role-remove-sshkey" title="Permalink to this definition"></a></dt> <dd>Remove an added ssh key from the host. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-remove-sshkey.ssh_key"> ssh_key<a class="headerlink" href="#rolevar-remove-sshkey.ssh_key" title="Permalink to this definition"></a> </dt> <dd>Complex argument which contains the ssh key information. It is expected that this argument comes from a <cite>Secret</cite>. <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-remove-sshkey.ssh_key.ssh_known_hosts"> ssh_key.ssh_known_hosts<a class="headerlink" href="#rolevar-remove-sshkey.ssh_key.ssh_known_hosts" title="Permalink to this definition"></a> </dt> <dd>String containing known host signature for the remote host. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-remove-sshkey.ssh_key.fqdn"> ssh_key.fqdn<a class="headerlink" href="#rolevar-remove-sshkey.ssh_key.fqdn" title="Permalink to this definition"></a> </dt> <dd>The FQDN of the remote host. </dd></dl> </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-render-diff"> render-diff<a class="headerlink" href="#role-render-diff" title="Permalink to this definition"></a></dt> <dd>Run render command and ensure there are no resulting differences. Ensure that generated configuration files are idempotent. Role Variables <dl class="zuul jobvar"> <dt class="sig sig-object zuul" id="jobvar-render-diff.render_command"> render_command<a class="headerlink" href="#jobvar-render-diff.render_command" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">make</code> </dt> <dd>The command that render the configuration files. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-render-diff.zuul_work_dir"> zuul_work_dir<a class="headerlink" href="#rolevar-render-diff.zuul_work_dir" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ zuul.project.src_dir }}</code> </dt> <dd>Directory to run the render command in. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-remove-zuul-sshkey"> remove-zuul-sshkey<a class="headerlink" href="#role-remove-zuul-sshkey" title="Permalink to this definition"></a></dt> <dd>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. </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-revoke-sudo"> revoke-sudo<a class="headerlink" href="#role-revoke-sudo" title="Permalink to this definition"></a></dt> <dd>Remove sudo access for the Zuul user. If the file <code class="docutils literal notranslate">/etc/sudoers.d/zuul</code> 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. </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-run-dstat"> run-dstat<a class="headerlink" href="#role-run-dstat" title="Permalink to this definition"></a></dt> <dd>Run dstat Add this to a pre-run playbook to run <code class="docutils literal notranslate">dstat</code>. The role <a class="reference internal" href="#role-dstat-graph" title="role-dstat-graph">dstat-graph</a> may optionally be used to graph the resulting data. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-run-dstat.dstat_data_path"> dstat_data_path<a class="headerlink" href="#rolevar-run-dstat.dstat_data_path" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">"{{ ansible_user_dir }}/zuul-output/logs/dstat.csv"</code> </dt> <dd>The path to the dstat data file. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-shake-build"> shake-build<a class="headerlink" href="#role-shake-build" title="Permalink to this definition"></a></dt> <dd>Run the shake build system command. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-shake-build.shake_report_name"> shake_report_name<a class="headerlink" href="#rolevar-shake-build.shake_report_name" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">shake.html</code> </dt> <dd>The name of the report. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-shake-build.shake_target"> shake_target<a class="headerlink" href="#rolevar-shake-build.shake_target" title="Permalink to this definition"></a> </dt> <dd>The name of the target to build. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-shake-build.zuul_work_dir"> zuul_work_dir<a class="headerlink" href="#rolevar-shake-build.zuul_work_dir" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ zuul.project.src_dir }}</code> </dt> <dd>Directory to run the shake command in. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-sign-artifacts"> sign-artifacts<a class="headerlink" href="#role-sign-artifacts" title="Permalink to this definition"></a></dt> <dd>Sign artifacts Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-sign-artifacts.gpg_key"> gpg_key<a class="headerlink" href="#rolevar-sign-artifacts.gpg_key" title="Permalink to this definition"></a> </dt> <dd><blockquote> <div>Complex argument which contains the GPG private key for signing the artifacts. It is expected that this argument comes from a <cite>Secret</cite>. </div></blockquote> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-sign-artifacts.gpg_key.private"> gpg_key.private<a class="headerlink" href="#rolevar-sign-artifacts.gpg_key.private" title="Permalink to this definition"></a> </dt> <dd>The ascii-armored contents of the GPG private key. </dd></dl> </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-sign-artifacts.gpg_artifact_path"> gpg_artifact_path<a class="headerlink" href="#rolevar-sign-artifacts.gpg_artifact_path" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">"{{ zuul.executor.work_root }}/artifacts/"</code> </dt> <dd>Path to a directory containing artifacts to sign. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-stage-output"> stage-output<a class="headerlink" href="#role-stage-output" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-stage-output.zuul_copy_output"> zuul_copy_output<a class="headerlink" href="#rolevar-stage-output.zuul_copy_output" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">None</code> </dt> <dd>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: <ul class="simple"> <li>logs</li> <li>artifacts</li> <li>docs</li> <li>null # ansible null, not the string null</li> </ul> null overrides the will of a parent job to copy something instructing not to copy. If the type is suffixed with <code class="docutils literal notranslate">_txt</code>, then the item will have <code class="docutils literal notranslate">.txt</code> appended to its name. For example: <div class="highlight-yaml notranslate"><div class="highlight"><pre>zuul_copy_output: /var/log/syslog: logs_txt </pre></div> </div> Will copy <code class="docutils literal notranslate">/var/log/syslog</code> to <code class="docutils literal notranslate">logs/syslog.txt</code>. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-stage-output.stage_dir"> stage_dir<a class="headerlink" href="#rolevar-stage-output.stage_dir" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ ansible_user_dir }}</code> </dt> <dd>The stage directory on the remote node. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-stage-output.extensions_to_txt"> extensions_to_txt<a class="headerlink" href="#rolevar-stage-output.extensions_to_txt" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">null</code> </dt> <dd>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 <cite>zuul_copy_output</cite> and it won’t be applied to files contained in folders listed in <cite>zuul_copy_output</cite>. Example: <div class="highlight-default notranslate"><div class="highlight"><pre>extensions_to_txt: conf: True log: True txt: False zuul.conf --(staged as)--> zuul_conf.txt </pre></div> </div> </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-stage-output.stage_compress_logs"> stage_compress_logs<a class="headerlink" href="#rolevar-stage-output.stage_compress_logs" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">False</code> </dt> <dd>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. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-start-zuul-console"> start-zuul-console<a class="headerlink" href="#role-start-zuul-console" title="Permalink to this definition"></a></dt> <dd>Start Zuul console logger It starts the Zuul console streamer on every host in the inventory. </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-test-setup"> test-setup<a class="headerlink" href="#role-test-setup" title="Permalink to this definition"></a></dt> <dd>Perform project test setup tasks. This role assumes that Zuul has checked out a change for a project at <code class="docutils literal notranslate">{{ zuul_work_dir }}</code> and looks for a file named <code class="docutils literal notranslate">tools/test-setup.sh</code>. 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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-test-setup.test_setup_environment"> test_setup_environment<a class="headerlink" href="#rolevar-test-setup.test_setup_environment" title="Permalink to this definition"></a> </dt> <dd>Environment variables to pass in to the test-setup script. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-test-setup.test_setup_args"> test_setup_args<a class="headerlink" href="#rolevar-test-setup.test_setup_args" title="Permalink to this definition"></a> </dt> <dd>String of optional command line options passed to the test-setup script. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-test-setup.test_setup_skip"> test_setup_skip<a class="headerlink" href="#rolevar-test-setup.test_setup_skip" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">false</code> </dt> <dd>Set this to true to skip running the test-setup script even if it exists. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-test-setup.zuul_work_dir"> zuul_work_dir<a class="headerlink" href="#rolevar-test-setup.zuul_work_dir" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ zuul.project.src_dir }}</code> </dt> <dd>The directory in which to look for the setup script. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-trigger-readthedocs"> trigger-readthedocs<a class="headerlink" href="#role-trigger-readthedocs" title="Permalink to this definition"></a></dt> <dd>Trigger readthedocs build for a project Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-trigger-readthedocs.rtd_project_name"> rtd_project_name<a class="headerlink" href="#rolevar-trigger-readthedocs.rtd_project_name" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">``{{ zuul.project.short_name }}``</code> </dt> <dd>The readthedocs project name </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-trigger-readthedocs.rtd_webhook_id"> rtd_webhook_id<a class="headerlink" href="#rolevar-trigger-readthedocs.rtd_webhook_id" title="Permalink to this definition"></a> </dt> <dd>The readthedocs webhook API ID. This needs to be taken from the project’s “Integrations” dashboard page in RTD. The URL will look like <code class="docutils literal notranslate">readthedocs.org/api/v2/webhook/<project-name>/<id>/</code>. This may come from a secret, however it can not be triggered without authentication. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-trigger-readthedocs.rtd_credentials"> rtd_credentials<a class="headerlink" href="#rolevar-trigger-readthedocs.rtd_credentials" title="Permalink to this definition"></a> </dt> <dd><blockquote> <div>Complex argument which contains the RTD authentication credentials. This is expected to come from a secret. </div></blockquote> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-trigger-readthedocs.rtd_credentials.integration_token"> rtd_credentials.integration_token<a class="headerlink" href="#rolevar-trigger-readthedocs.rtd_credentials.integration_token" title="Permalink to this definition"></a> </dt> <dd>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. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-trigger-readthedocs.rtd_credentials.username"> rtd_credentials.username<a class="headerlink" href="#rolevar-trigger-readthedocs.rtd_credentials.username" title="Permalink to this definition"></a> </dt> <dd>The readthedocs username. If set, this will be used to authenticate in preference to any token set via <code class="docutils literal notranslate">rtd_integration_token</code>. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-trigger-readthedocs.rtd_credentials.password"> rtd_credentials.password<a class="headerlink" href="#rolevar-trigger-readthedocs.rtd_credentials.password" title="Permalink to this definition"></a> </dt> <dd>Password for <code class="docutils literal notranslate">username</code>. Must be set if username is set. </dd></dl> </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-update-json-file"> update-json-file<a class="headerlink" href="#role-update-json-file" title="Permalink to this definition"></a></dt> <dd>Update JSON file This role reads a JSON file, merges it with supplied values using Ansible’s <code class="docutils literal notranslate">combine</code> 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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-update-json-file.update_json_file_name"> update_json_file_name<a class="headerlink" href="#rolevar-update-json-file.update_json_file_name" title="Permalink to this definition"></a> Type: path </dt> <dd>The path to the file to edit. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-update-json-file.update_json_file_combine"> update_json_file_combine<a class="headerlink" href="#rolevar-update-json-file.update_json_file_combine" title="Permalink to this definition"></a> Type: object </dt> <dd>The data to be combined with the existing file data. This uses the Jinja <code class="docutils literal notranslate">combine</code> filter. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-update-json-file.update_json_file_debug"> update_json_file_debug<a class="headerlink" href="#rolevar-update-json-file.update_json_file_debug" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">false</code> Type: bool </dt> <dd>If enabled, output the combined result in a debug task. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-update-json-file.update_json_file_default"> update_json_file_default<a class="headerlink" href="#rolevar-update-json-file.update_json_file_default" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{}</code> </dt> <dd>The default value if the given file does not exist. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-update-json-file.update_json_file_become"> update_json_file_become<a class="headerlink" href="#rolevar-update-json-file.update_json_file_become" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">false</code> Type: bool </dt> <dd>The <code class="docutils literal notranslate">become:</code> status when writing out the new file. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-update-json-file.update_json_file_mode"> update_json_file_mode<a class="headerlink" href="#rolevar-update-json-file.update_json_file_mode" title="Permalink to this definition"></a> </dt> <dd>The mode for the combined file. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-update-json-file.update_json_file_user"> update_json_file_user<a class="headerlink" href="#rolevar-update-json-file.update_json_file_user" title="Permalink to this definition"></a> </dt> <dd>The user for the combined file. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-update-json-file.update_json_file_group"> update_json_file_group<a class="headerlink" href="#rolevar-update-json-file.update_json_file_group" title="Permalink to this definition"></a> </dt> <dd>The group for the combined file. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-update-json-file.update_json_dir_mode"> update_json_dir_mode<a class="headerlink" href="#rolevar-update-json-file.update_json_dir_mode" title="Permalink to this definition"></a> </dt> <dd>The mode for the directory if that does not already exists. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-upload-artifactory"> upload-artifactory<a class="headerlink" href="#role-upload-artifactory" title="Permalink to this definition"></a></dt> <dd>Upload artifacts specified from the executor to artifactory. <div class="admonition note"> Note This role uses the <code class="docutils literal notranslate">src</code> function of the <code class="docutils literal notranslate">uri</code> module introduced in Ansible 2.7 therefore any ansible version lower than that is not supported. </div> Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_instances"> upload_artifactory_instances<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_instances" title="Permalink to this definition"></a> </dt> <dd>Complex argument that contains the information about credentials, fqdn and name. This argument is expected to come from a secret. <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_instances.upload_artifactory_instances.<name>.user"> upload_artifactory_instances.upload_artifactory_instances.<name>.user<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_instances.upload_artifactory_instances.<name>.user" title="Permalink to this definition"></a> </dt> <dd>User for authenticating. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_instances.upload_artifactory_instances.<name>.password"> upload_artifactory_instances.upload_artifactory_instances.<name>.password<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_instances.upload_artifactory_instances.<name>.password" title="Permalink to this definition"></a> </dt> <dd>Password for authenticating. Has a lower precedense than <code class="docutils literal notranslate">api_key</code>. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_instances.upload_artifactory_instances.<name>.api_key"> upload_artifactory_instances.upload_artifactory_instances.<name>.api_key<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_instances.upload_artifactory_instances.<name>.api_key" title="Permalink to this definition"></a> </dt> <dd>API key for authenticating. Has a higher precedense than <code class="docutils literal notranslate">password</code>. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_instances.upload_artifactory_instances.<name>.fqdn"> upload_artifactory_instances.upload_artifactory_instances.<name>.fqdn<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_instances.upload_artifactory_instances.<name>.fqdn" title="Permalink to this definition"></a> </dt> <dd>Fully qualified domain name to the instance. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_instances.upload_artifactory_instances.<name>.transport"> upload_artifactory_instances.upload_artifactory_instances.<name>.transport<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_instances.upload_artifactory_instances.<name>.transport" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">https</code> </dt> <dd>Set to <code class="docutils literal notranslate">http</code> if the instance does not support https. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_instances.force_basic_auth"> upload_artifactory_instances.force_basic_auth<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_instances.force_basic_auth" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">false</code> </dt> <dd>Set to <code class="docutils literal notranslate">true</code> if the instance requires basic auth to be used. </dd></dl> </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_manifest"> upload_artifactory_manifest<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_manifest" title="Permalink to this definition"></a> </dt> <dd>Dictionary of types of items to upload. Currently only supports <code class="docutils literal notranslate">artifacts</code>. <blockquote> <div><dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_manifest.artifacts"> upload_artifactory_manifest.artifacts<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_manifest.artifacts" title="Permalink to this definition"></a> </dt> <dd>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. <blockquote> <div><div class="highlight-yaml notranslate"><div class="highlight"><pre>artifacts: - name: tarball src: artifact.tar.gz dest: /destination/to/put/artifact/artifact.tar.gz instance: artifact-server1 headers: Content-Type: application/gzip </pre></div> </div> </div></blockquote> The attributes available on an artifact are the following. <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.name"> upload_artifactory_manifest.artifacts.name<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.name" title="Permalink to this definition"></a> </dt> <dd>Name of the artifact. This will be displayed in the build page. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.src"> upload_artifactory_manifest.artifacts.src<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.src" title="Permalink to this definition"></a> </dt> <dd>Path relative to <code class="docutils literal notranslate">{{ zuul.executor.work_root }}/artifacts/</code>. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.dest"> upload_artifactory_manifest.artifacts.dest<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.dest" title="Permalink to this definition"></a> </dt> <dd>Destination where the artifact should be put in. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.instance"> upload_artifactory_manifest.artifacts.instance<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.instance" title="Permalink to this definition"></a> </dt> <dd>Artifactory instance to place the artiface in, this is to choose which entry in <a class="reference internal" href="#rolevar-upload-artifactory.upload_artifactory_instances" title="rolevar-upload-artifactory.upload_artifactory_instances">upload-artifactory.upload_artifactory_instances</a> to upload the artifact to. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.headers"> upload_artifactory_manifest.artifacts.headers<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.headers" title="Permalink to this definition"></a> </dt> <dd>Any headers that should be passed to ansibles uri module when uploading. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.properties"> upload_artifactory_manifest.artifacts.properties<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.properties" title="Permalink to this definition"></a> </dt> <dd>Properties to set in artifactory. Properties can be either strings or lists of strings. <div class="highlight-yaml notranslate"><div class="highlight"><pre>properties: property1: value1 property2: - value2 - value3 </pre></div> </div> </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.metadata"> upload_artifactory_manifest.artifacts.metadata<a class="headerlink" href="#rolevar-upload-artifactory.upload_artifactory_manifest.artifacts.metadata" title="Permalink to this definition"></a> </dt> <dd>Any metadata that should be returned to Zuul together with the artifact link. </dd></dl> </dd></dl> </div></blockquote> </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-upload-git-mirror"> upload-git-mirror<a class="headerlink" href="#role-upload-git-mirror" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-git-mirror.git_mirror_credentials"> git_mirror_credentials<a class="headerlink" href="#rolevar-upload-git-mirror.git_mirror_credentials" title="Permalink to this definition"></a> </dt> <dd><blockquote> <div>Dictionary that provides the remote git repository credentials </div></blockquote> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-git-mirror.git_mirror_credentials.user"> git_mirror_credentials.user<a class="headerlink" href="#rolevar-upload-git-mirror.git_mirror_credentials.user" title="Permalink to this definition"></a> </dt> <dd>SSH user for the remote git repository </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-git-mirror.git_mirror_credentials.host"> git_mirror_credentials.host<a class="headerlink" href="#rolevar-upload-git-mirror.git_mirror_credentials.host" title="Permalink to this definition"></a> </dt> <dd>SSH host for the remote git repository </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-git-mirror.git_mirror_credentials.ssh_key"> git_mirror_credentials.ssh_key<a class="headerlink" href="#rolevar-upload-git-mirror.git_mirror_credentials.ssh_key" title="Permalink to this definition"></a> </dt> <dd>Literal private key contents. Should start with something like <code class="docutils literal notranslate">-----BEGIN RSA PRIVATE KEY-----</code>. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-git-mirror.git_mirror_credentials.host_key"> git_mirror_credentials.host_key<a class="headerlink" href="#rolevar-upload-git-mirror.git_mirror_credentials.host_key" title="Permalink to this definition"></a> </dt> <dd>SSH host key of the remote git server. Can be obtained with <code class="docutils literal notranslate">ssh-keyscan -H <host></code>. </dd></dl> </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-upload-git-mirror.git_mirror_repository"> git_mirror_repository<a class="headerlink" href="#rolevar-upload-git-mirror.git_mirror_repository" title="Permalink to this definition"></a> </dt> <dd>Path of the remote git repository </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-validate-dco-license"> validate-dco-license<a class="headerlink" href="#role-validate-dco-license" title="Permalink to this definition"></a></dt> <dd>Validate all commits have Signed-off-by header Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-validate-dco-license.dco_license_failure"> dco_license_failure<a class="headerlink" href="#rolevar-validate-dco-license.dco_license_failure" title="Permalink to this definition"></a> </dt> <dd>Message to display when Signed-off-by header is missing. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-validate-dco-license.zuul_work_dir"> zuul_work_dir<a class="headerlink" href="#rolevar-validate-dco-license.zuul_work_dir" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ zuul.project.src_dir }}</code> </dt> <dd>Directory to DCO license check in. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-validate-host"> validate-host<a class="headerlink" href="#role-validate-host" title="Permalink to this definition"></a></dt> <dd>Log information about the build node Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-validate-host.zuul_site_ipv4_route_required"> zuul_site_ipv4_route_required<a class="headerlink" href="#rolevar-validate-host.zuul_site_ipv4_route_required" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">false</code> </dt> <dd>If true, fail when no IPv4 route to <code class="docutils literal notranslate">zuul_site_traceroute_host</code> is available. When false (default) a missing IPv4 route is acceptable so long as there is still a viable IPv6 route. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-validate-host.zuul_site_ipv6_route_required"> zuul_site_ipv6_route_required<a class="headerlink" href="#rolevar-validate-host.zuul_site_ipv6_route_required" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">false</code> </dt> <dd>If true, fail when no IPv6 route to <code class="docutils literal notranslate">zuul_site_traceroute_host</code> is available. When false (default) a missing IPv6 route is acceptable so long as there is still a viable IPv4 route. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-validate-host.zuul_site_traceroute_host"> zuul_site_traceroute_host<a class="headerlink" href="#rolevar-validate-host.zuul_site_traceroute_host" title="Permalink to this definition"></a> </dt> <dd>If defined, a host to run a traceroute against to verify build node network connectivity. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-validate-host.zuul_site_image_manifest_files"> zuul_site_image_manifest_files<a class="headerlink" href="#rolevar-validate-host.zuul_site_image_manifest_files" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">['/etc/dib-builddate.txt', '/etc/image-hostname.txt']</code> </dt> <dd>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. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-validate-zone-db"> validate-zone-db<a class="headerlink" href="#role-validate-zone-db" title="Permalink to this definition"></a></dt> <dd>Validate bind zone.db files This role uses <code class="docutils literal notranslate">named-checkzone</code> to validate Bind <code class="docutils literal notranslate">zone.db</code> files. Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-validate-zone-db.zone_files"> zone_files<a class="headerlink" href="#rolevar-validate-zone-db.zone_files" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">zuul.project.src_dir</code> </dt> <dd>Look for <code class="docutils literal notranslate">zone.db</code> files recursively in this directory. The layout should be <code class="docutils literal notranslate">domain.xyz/zone.db</code> where a parent directory is named for the zone the child <code class="docutils literal notranslate">zone.db</code> file describes. This populates the <code class="docutils literal notranslate">zone_db_files</code> variable. Will not be used if <code class="docutils literal notranslate">zone_db_files</code> is explicitly set per below. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-validate-zone-db.zone_db_files"> zone_db_files<a class="headerlink" href="#rolevar-validate-zone-db.zone_db_files" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">[]</code> </dt> <dd>A list of <code class="docutils literal notranslate">zone.db</code> files to check. Each entry is a list with the first element the domain, and the second element the path to the <code class="docutils literal notranslate">zone.db</code> file. If this variable is set, automatic searching described by <code class="docutils literal notranslate">zone_files</code> will not be performed. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-version-from-git"> version-from-git<a class="headerlink" href="#role-version-from-git" title="Permalink to this definition"></a></dt> <dd>Sets three facts based on information in a git repo. <dl class="simple"> <dt>scm_sha</dt><dd>The short sha found in the repository. </dd> <dt>project_ver</dt><dd>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 <code class="docutils literal notranslate">scm_tag</code> is either the most recent tag or the value of <code class="docutils literal notranslate">scm_sha</code> if there are no commits in the repo. </dd> <dt>commits_since_tag</dt><dd>Number of commits since the most recent tag. </dd> </dl> Role Variables <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-version-from-git.zuul_work_dir"> zuul_work_dir<a class="headerlink" href="#rolevar-version-from-git.zuul_work_dir" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">{{ zuul.project.src_dir }}</code> </dt> <dd>Directory to run git in. </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-write-inventory"> write-inventory<a class="headerlink" href="#role-write-inventory" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-write-inventory.write_inventory_dest"> write_inventory_dest<a class="headerlink" href="#rolevar-write-inventory.write_inventory_dest" title="Permalink to this definition"></a> </dt> <dd>The path of the inventory file to write. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-write-inventory.write_inventory_include_hostvars"> write_inventory_include_hostvars<a class="headerlink" href="#rolevar-write-inventory.write_inventory_include_hostvars" title="Permalink to this definition"></a> Type: list </dt> <dd>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. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-write-inventory.write_inventory_exclude_hostvars"> write_inventory_exclude_hostvars<a class="headerlink" href="#rolevar-write-inventory.write_inventory_exclude_hostvars" title="Permalink to this definition"></a> Type: list </dt> <dd>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. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-write-inventory.write_inventory_additional_hostvars"> write_inventory_additional_hostvars<a class="headerlink" href="#rolevar-write-inventory.write_inventory_additional_hostvars" title="Permalink to this definition"></a> Type: dict </dt> <dd>Additional hostvars to include. This can be used to map information from nodepool into the inventory if used as follows: <div class="highlight-yaml notranslate"><div class="highlight"><pre>write_inventory_additional_hostvars: public_v4: nodepool.public_ipv4 public_v6: nodepool.public_ipv6 </pre></div> </div> This will map hostvars[hostname][‘nodepool’][‘public_ipv4’] to hostvars[hostname][‘public_v4’]. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-write-inventory.write_inventory_per_host_hostvars"> write_inventory_per_host_hostvars<a class="headerlink" href="#rolevar-write-inventory.write_inventory_per_host_hostvars" title="Permalink to this definition"></a> Type: dict </dt> <dd>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, <code class="docutils literal notranslate">hosta.com</code> will have <code class="docutils literal notranslate">foo</code> with value <code class="docutils literal notranslate">bar</code>, while <code class="docutils literal notranslate">hostb.com</code> will have <code class="docutils literal notranslate">foo</code> with value <code class="docutils literal notranslate">baz</code>. <div class="highlight-yaml notranslate"><div class="highlight"><pre>write_inventory_per_host_hostvars: hosta.com: foo: bar hostb.com: foo: baz </pre></div> </div> </dd></dl> </dd></dl> <dl class="zuul role"> <dt class="sig sig-object zuul" id="role-zuul-tenant-conf-check"> zuul-tenant-conf-check<a class="headerlink" href="#role-zuul-tenant-conf-check" title="Permalink to this definition"></a></dt> <dd>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 <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_zuul_conf_path"> zuul_tenant_conf_check_zuul_conf_path<a class="headerlink" href="#rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_zuul_conf_path" title="Permalink to this definition"></a> </dt> <dd>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. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_tenant_config_path"> zuul_tenant_conf_check_tenant_config_path<a class="headerlink" href="#rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_tenant_config_path" title="Permalink to this definition"></a> </dt> <dd>The path to the tenant config file to check. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_image"> zuul_tenant_conf_check_image<a class="headerlink" href="#rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_image" title="Permalink to this definition"></a> Default: <code class="docutils literal notranslate">quay.io/zuul-ci/zuul-scheduler:latest</code> </dt> <dd>The Zuul scheduler container image which contains the zuul-admin command to run. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_registry_credentials"> zuul_tenant_conf_check_registry_credentials<a class="headerlink" href="#rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_registry_credentials" title="Permalink to this definition"></a> </dt> <dd>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: <div class="highlight-yaml notranslate"><div class="highlight"><pre>zuul_tenant_conf_check_registry_credentials: docker.io: username: 'username' password: 'password' </pre></div> </div> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_registry_credentials.[registry_name]"> zuul_tenant_conf_check_registry_credentials.[registry_name]<a class="headerlink" href="#rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_registry_credentials.[registry_name]" title="Permalink to this definition"></a> </dt> <dd>The dictionary key should be the name of the registry <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_registry_credentials.[registry_name].username"> zuul_tenant_conf_check_registry_credentials.[registry_name].username<a class="headerlink" href="#rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_registry_credentials.[registry_name].username" title="Permalink to this definition"></a> </dt> <dd>The registry username. </dd></dl> <dl class="zuul rolevar"> <dt class="sig sig-object zuul" id="rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_registry_credentials.[registry_name].password"> zuul_tenant_conf_check_registry_credentials.[registry_name].password<a class="headerlink" href="#rolevar-zuul-tenant-conf-check.zuul_tenant_conf_check_registry_credentials.[registry_name].password" title="Permalink to this definition"></a> </dt> <dd>The registry password. </dd></dl> </dd></dl> </dd></dl> </dd></dl> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="roles.html" class="btn btn-neutral float-left" title="Roles" accesskey="p" rel="prev"> Previous</a> <a href="log-roles.html" class="btn btn-neutral float-right" title="Log Roles" accesskey="n" rel="next">Next </a> </div> <hr/> <div role="contentinfo"> © Copyright 2012-2025, Zuul project contributors. </div> Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>