Docs: reformat merger and executor config docs
Change-Id: I75e67a592cdef5fcf4a2576cd5a5814cb79211f8
This commit is contained in:
parent
979401944a
commit
9d0b4cc482
|
@ -177,10 +177,12 @@ The following sections of ``zuul.conf`` are used by the scheduler:
|
|||
Path to log config file.
|
||||
|
||||
.. attr:: pidfile
|
||||
:default: /var/run/zuul-schedurecr/zuul-scheduler.pid
|
||||
|
||||
Path to PID lock file.
|
||||
|
||||
.. attr:: state_dir
|
||||
:default: /var/lib/zuul
|
||||
|
||||
Path to directory in which Zuul should save its state.
|
||||
|
||||
|
@ -219,35 +221,32 @@ to reduce the load on executors.
|
|||
Configuration
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
The following section of **zuul.conf** is used by the merger:
|
||||
The following section of ``zuul.conf`` is used by the merger:
|
||||
|
||||
merger
|
||||
""""""
|
||||
.. attr:: merger
|
||||
|
||||
**git_dir**
|
||||
Directory that Zuul should clone local git repositories to::
|
||||
.. attr:: git_dir
|
||||
|
||||
git_dir=/var/lib/zuul/git
|
||||
Directory in which Zuul should clone git repositories.
|
||||
|
||||
**git_user_email**
|
||||
Value to pass to `git config user.email`::
|
||||
.. attr:: git_user_email
|
||||
|
||||
git_user_email=zuul@example.com
|
||||
Value to pass to `git config user.email
|
||||
<https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup>`_.
|
||||
|
||||
**git_user_name**
|
||||
Value to pass to `git config user.name`::
|
||||
.. attr:: git_user_name
|
||||
|
||||
git_user_name=zuul
|
||||
Value to pass to `git config user.name
|
||||
<https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup>`_.
|
||||
|
||||
**log_config**
|
||||
Path to log config file for the merger process::
|
||||
.. attr:: log_config
|
||||
|
||||
log_config=/etc/zuul/logging.yaml
|
||||
Path to log config file for the merger process.
|
||||
|
||||
**pidfile**
|
||||
Path to PID lock file for the merger process::
|
||||
.. attr:: pidfile
|
||||
:default: /var/run/zuul-merger/zuul-merger.pid
|
||||
|
||||
pidfile=/var/run/zuul-merger/merger.pid
|
||||
Path to PID lock file for the merger process.
|
||||
|
||||
Operation
|
||||
~~~~~~~~~
|
||||
|
@ -280,10 +279,11 @@ Trusted and Untrusted Playbooks
|
|||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The executor runs playbooks in one of two execution contexts depending
|
||||
on whether the project containing the playbook is a *config project*
|
||||
or an *untrusted project*. If the playbook is in a *config project*,
|
||||
the executor runs the playbook in the *trusted* execution context,
|
||||
otherwise, it is run in the *untrusted* execution context.
|
||||
on whether the project containing the playbook is a
|
||||
:term:`config-project` or an :term:`untrusted-project`. If the
|
||||
playbook is in a config project, the executor runs the playbook in the
|
||||
*trusted* execution context, otherwise, it is run in the *untrusted*
|
||||
execution context.
|
||||
|
||||
Both execution contexts use `bubblewrap`_ to create a namespace to
|
||||
ensure that playbook executions are isolated and are unable to access
|
||||
|
@ -291,7 +291,7 @@ files outside of a restricted environment. The administrator may
|
|||
configure additional local directories on the executor to be made
|
||||
available to the restricted environment.
|
||||
|
||||
The *trusted* execution context has access to all Ansible features,
|
||||
The trusted execution context has access to all Ansible features,
|
||||
including the ability to load custom Ansible modules. Needless to
|
||||
say, extra scrutiny should be given to code that runs in a trusted
|
||||
context as it could be used to compromise other jobs running on the
|
||||
|
@ -299,128 +299,129 @@ executor, or the executor itself, especially if the administrator has
|
|||
granted additional access through bubblewrap, or a method of escaping
|
||||
the restricted environment created by bubblewrap is found.
|
||||
|
||||
Playbooks run in the *untrusted* execution context are not permitted
|
||||
to load additional Ansible modules or access files outside of the
|
||||
Playbooks run in the untrusted execution context are not permitted to
|
||||
load additional Ansible modules or access files outside of the
|
||||
restricted environment prepared for them by the executor. In addition
|
||||
to the bubblewrap environment applied to both execution contexts, in
|
||||
the *untrusted* context some standard Ansible modules are replaced
|
||||
with versions which prohibit some actions, including attempts to
|
||||
access files outside of the restricted execution context. These
|
||||
redundant protections are made as part of a defense-in-depth strategy.
|
||||
the untrusted context some standard Ansible modules are replaced with
|
||||
versions which prohibit some actions, including attempts to access
|
||||
files outside of the restricted execution context. These redundant
|
||||
protections are made as part of a defense-in-depth strategy.
|
||||
|
||||
.. _bubblewrap: https://github.com/projectatomic/bubblewrap
|
||||
|
||||
Configuration
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
The following sections of **zuul.conf** are used by the executor:
|
||||
The following sections of ``zuul.conf`` are used by the executor:
|
||||
|
||||
executor
|
||||
""""""""
|
||||
.. attr:: executor
|
||||
|
||||
**finger_port**
|
||||
Port to use for finger log streamer::
|
||||
.. attr:: finger_port
|
||||
:default: 79
|
||||
|
||||
finger_port=79
|
||||
Port to use for finger log streamer.
|
||||
|
||||
.. attr:: git_dir
|
||||
:default: /var/lib/zuul/git
|
||||
|
||||
**git_dir**
|
||||
Directory that Zuul should clone local git repositories to. The
|
||||
executor keeps a local copy of every git repository it works with to
|
||||
speed operations and perform speculative merging.
|
||||
executor keeps a local copy of every git repository it works
|
||||
with to speed operations and perform speculative merging.
|
||||
|
||||
This should be on the same filesystem as **job_dir** so that when
|
||||
git repos are cloned into the job workspaces, they can be
|
||||
hard-linked to the local git cache. Example::
|
||||
This should be on the same filesystem as
|
||||
:attr:`executor.job_dir` so that when git repos are cloned into
|
||||
the job workspaces, they can be hard-linked to the local git
|
||||
cache.
|
||||
|
||||
git_dir=/var/lib/zuul/git
|
||||
.. attr:: job_dir
|
||||
:default: /tmp
|
||||
|
||||
**job_dir**
|
||||
Directory that Zuul should use to hold temporary job directories.
|
||||
When each job is run, a new entry will be created under this
|
||||
directory to hold the configuration and scratch workspace for that
|
||||
job. It will be deleted at the end of the job (unless the
|
||||
directory to hold the configuration and scratch workspace for
|
||||
that job. It will be deleted at the end of the job (unless the
|
||||
`--keep-jobdir` command line option is specified).
|
||||
|
||||
This should be on the same filesystem as **git_dir** so that when
|
||||
git repos are cloned into the job workspaces, they can be
|
||||
hard-linked to the local git cache. Example::
|
||||
This should be on the same filesystem as :attr:`executor.git_dir`
|
||||
so that when git repos are cloned into the job workspaces, they
|
||||
can be hard-linked to the local git cache.
|
||||
|
||||
job_dir=/var/lib/zuul/jobs
|
||||
.. attr:: log_config
|
||||
|
||||
**log_config**
|
||||
Path to log config file for the executor process::
|
||||
Path to log config file for the executor process.
|
||||
|
||||
log_config=/etc/zuul/logging.yaml
|
||||
.. attr:: pidfile
|
||||
:default: /var/run/zuul-executor/zuul-executor.pid
|
||||
|
||||
**private_key_file**
|
||||
SSH private key file to be used when logging into worker nodes::
|
||||
Path to PID lock file for the executor process.
|
||||
|
||||
private_key_file=~/.ssh/id_rsa
|
||||
.. attr:: private_key_file
|
||||
:default: ~/.ssh/id_rsa
|
||||
|
||||
**user**
|
||||
User ID for the zuul-executor process. In normal operation as a daemon,
|
||||
the executor should be started as the ``root`` user, but it will drop
|
||||
privileges to this user during startup::
|
||||
SSH private key file to be used when logging into worker nodes.
|
||||
|
||||
user=zuul
|
||||
.. attr:: user
|
||||
:default: zuul
|
||||
|
||||
.. _admin_sitewide_variables:
|
||||
User ID for the zuul-executor process. In normal operation as a
|
||||
daemon, the executor should be started as the ``root`` user, but
|
||||
it will drop privileges to this user during startup.
|
||||
|
||||
.. _admin_sitewide_variables:
|
||||
|
||||
.. attr:: variables
|
||||
|
||||
**variables**
|
||||
Path to an Ansible variables file to supply site-wide variables.
|
||||
This should be a YAML-formatted file consisting of a single
|
||||
dictionary. The contents will be made available to all jobs as
|
||||
Ansible variables. These variables take precedence over all other
|
||||
forms (job variables and secrets). Care should be taken when naming
|
||||
these variables to avoid potential collisions with those used by
|
||||
jobs. Prefixing variable names with a site-specific identifier is
|
||||
recommended. The default is not to add any site-wide variables.
|
||||
See the :ref:`User's Guide <user_sitewide_variables>` for more
|
||||
information.
|
||||
Ansible variables. These variables take precedence over all
|
||||
other forms (job variables and secrets). Care should be taken
|
||||
when naming these variables to avoid potential collisions with
|
||||
those used by jobs. Prefixing variable names with a
|
||||
site-specific identifier is recommended. The default is not to
|
||||
add any site-wide variables. See the :ref:`User's Guide
|
||||
<user_sitewide_variables>` for more information.
|
||||
|
||||
Example::
|
||||
.. attr:: disk_limit_per_job
|
||||
:default: 250
|
||||
|
||||
variables=/etc/zuul/variables.yaml
|
||||
This integer is the maximum number of megabytes that any one job
|
||||
is allowed to consume on disk while it is running. If a job's
|
||||
scratch space has more than this much space consumed, it will be
|
||||
aborted.
|
||||
|
||||
**disk_limit_per_job**
|
||||
This integer is the maximum number of megabytes that any one job is
|
||||
allowed to consume on disk while it is running. If a job's scratch
|
||||
space has more than this much space consumed, it will be aborted::
|
||||
.. attr:: trusted_ro_paths
|
||||
|
||||
disk_limit_per_job=100
|
||||
List of paths, separated by ``:`` to read-only bind mount into
|
||||
trusted bubblewrap contexts.
|
||||
|
||||
**trusted_ro_paths**
|
||||
.. attr:: trusted_rw_paths
|
||||
|
||||
List of paths, separated by ':' to read-only bind mount into trusted
|
||||
bubblewrap contexts.
|
||||
List of paths, separated by ``:`` to read-write bind mount into
|
||||
trusted bubblewrap contexts.
|
||||
|
||||
**trusted_rw_paths**
|
||||
.. attr:: untrusted_ro_paths
|
||||
|
||||
List of paths, separated by ':' to read-write bind mount into trusted
|
||||
bubblewrap contexts.
|
||||
List of paths, separated by ``:`` to read-only bind mount into
|
||||
untrusted bubblewrap contexts.
|
||||
|
||||
**untrusted_ro_paths**
|
||||
.. attr:: untrusted_rw_paths
|
||||
|
||||
List of paths, separated by ':' to read-only bind mount into untrusted
|
||||
bubblewrap contexts.
|
||||
List of paths, separated by ``:`` to read-write bind mount into
|
||||
untrusted bubblewrap contexts.
|
||||
|
||||
**untrusted_rw_paths**
|
||||
.. attr:: merger
|
||||
|
||||
List of paths, separated by ':' to read-write bind mount into untrusted
|
||||
bubblewrap contexts.
|
||||
.. attr:: git_user_email
|
||||
|
||||
merger
|
||||
""""""
|
||||
Value to pass to `git config user.email
|
||||
<https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup>`_.
|
||||
|
||||
**git_user_email**
|
||||
Value to pass to `git config user.email`::
|
||||
.. attr:: git_user_name
|
||||
|
||||
git_user_email=zuul@example.com
|
||||
|
||||
**git_user_name**
|
||||
Value to pass to `git config user.name`::
|
||||
|
||||
git_user_name=zuul
|
||||
Value to pass to `git config user.name
|
||||
<https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup>`_.
|
||||
|
||||
Operation
|
||||
~~~~~~~~~
|
||||
|
|
|
@ -45,6 +45,27 @@ Glossary
|
|||
might leave feedback in a remote system on a proposed change,
|
||||
send email, or store information in a database.
|
||||
|
||||
trusted execution context
|
||||
|
||||
Playbooks defined in a :term:`config-project` run in the
|
||||
*trusted* execution context. The trusted execution context has
|
||||
access to all Ansible features, including the ability to load
|
||||
custom Ansible modules.
|
||||
|
||||
untrusted execution context
|
||||
|
||||
Playbooks defined in an :term:`untrusted-project` run in the
|
||||
*untrusted* execution context. Playbooks run in the untrusted
|
||||
execution context are not permitted to load additional Ansible
|
||||
modules or access files outside of the restricted environment
|
||||
prepared for them by the executor. In addition to the
|
||||
bubblewrap environment applied to both execution contexts, in
|
||||
the untrusted context some standard Ansible modules are replaced
|
||||
with versions which prohibit some actions, including attempts to
|
||||
access files outside of the restricted execution context. These
|
||||
redundant protections are made as part of a defense-in-depth
|
||||
strategy.
|
||||
|
||||
untrusted-project
|
||||
|
||||
One of two types of projects which may be specified by the
|
||||
|
|
Loading…
Reference in New Issue