blob: 48e7ba8aa680b9410edaeb69168d9f1ef071faa0 [file] [log] [blame]
James E. Blaireff5a9d2017-06-20 00:00:37 -07001:title: Tenant Configuration
2
3.. _tenant-config:
4
5Tenant Configuration
6====================
7
James E. Blairb4eab922017-08-04 09:29:45 -07008After ``zuul.conf`` is configured, Zuul component servers will be able
James E. Blaireff5a9d2017-06-20 00:00:37 -07009to start, but a tenant configuration is required in order for Zuul to
10perform any actions. The tenant configuration file specifies upon
James E. Blairb4eab922017-08-04 09:29:45 -070011which projects Zuul should operate. These repositories are grouped
12into tenants. The configuration of each tenant is separate from the
13rest (no pipelines, jobs, etc are shared between them).
James E. Blaireff5a9d2017-06-20 00:00:37 -070014
15A project may appear in more than one tenant; this may be useful if
16you wish to use common job definitions across multiple tenants.
17
James E. Blairb4eab922017-08-04 09:29:45 -070018The tenant configuration file is specified by the
19:attr:`scheduler.tenant_config` setting in ``zuul.conf``. It is a
20YAML file which, like other Zuul configuration files, is a list of
21configuration objects, though only one type of object is supported:
22``tenant``.
James E. Blaireff5a9d2017-06-20 00:00:37 -070023
24Tenant
25------
26
27A tenant is a collection of projects which share a Zuul
James E. Blairb4eab922017-08-04 09:29:45 -070028configuration. An example tenant definition is:
James E. Blaireff5a9d2017-06-20 00:00:37 -070029
James E. Blairb4eab922017-08-04 09:29:45 -070030.. code-block:: yaml
James E. Blaireff5a9d2017-06-20 00:00:37 -070031
James E. Blairb4eab922017-08-04 09:29:45 -070032 - tenant:
33 name: my-tenant
34 max-nodes-per-job: 5
35 exclude-unprotected-branches: false
36 source:
37 gerrit:
38 config-projects:
39 - common-config
40 - shared-jobs:
41 include: job
42 untrusted-projects:
43 - zuul-jobs:
44 shadow: common-config
45 - project1
46 - project2:
47 exclude-unprotected-branches: true
James E. Blaireff5a9d2017-06-20 00:00:37 -070048
James E. Blairb4eab922017-08-04 09:29:45 -070049.. attr:: tenant
James E. Blaireff5a9d2017-06-20 00:00:37 -070050
James E. Blairb4eab922017-08-04 09:29:45 -070051 The following attributes are supported:
Tristan Cacqueray82f864b2017-08-01 05:54:42 +000052
James E. Blairb4eab922017-08-04 09:29:45 -070053 .. attr:: name
54 :required:
Tobias Henkeleca46202017-08-02 20:27:10 +020055
James E. Blairb4eab922017-08-04 09:29:45 -070056 The name of the tenant. This may appear in URLs, paths, and
57 monitoring fields, and so should be restricted to URL friendly
58 characters (ASCII letters, numbers, hyphen and underscore) and
59 you should avoid changing it unless necessary.
James E. Blaireff5a9d2017-06-20 00:00:37 -070060
James E. Blairb4eab922017-08-04 09:29:45 -070061 .. attr:: source
62 :required:
James E. Blaireff5a9d2017-06-20 00:00:37 -070063
James E. Blairb4eab922017-08-04 09:29:45 -070064 A dictionary of sources to consult for projects. A tenant may
65 contain projects from multiple sources; each of those sources
66 must be listed here, along with the projects it supports. The
67 name of a :ref:`connection<connections>` is used as the
68 dictionary key (e.g. ``gerrit`` in the example above), and the
69 value is a further dictionary containing the keys below.
James E. Blaireff5a9d2017-06-20 00:00:37 -070070
James E. Blairb4eab922017-08-04 09:29:45 -070071 The next two attributes, **config-projects** and
72 **untrusted-projects** provide the bulk of the information for
73 tenant configuration. They list all of the projects upon which
74 Zuul will act.
James E. Blaireff5a9d2017-06-20 00:00:37 -070075
James E. Blairb4eab922017-08-04 09:29:45 -070076 The order of the projects listed in a tenant is important. A job
77 which is defined in one project may not be redefined in another
78 project; therefore, once a job appears in one project, a project
79 listed later will be unable to define a job with that name.
80 Further, some aspects of project configuration (such as the merge
81 mode) may only be set on the first appearance of a project
82 definition.
James E. Blaireff5a9d2017-06-20 00:00:37 -070083
James E. Blairb4eab922017-08-04 09:29:45 -070084 Zuul loads the configuration from all **config-projects** in the
85 order listed, followed by all **untrusted-projects** in order.
James E. Blaireff5a9d2017-06-20 00:00:37 -070086
James E. Blairb4eab922017-08-04 09:29:45 -070087 .. attr:: config-projects
James E. Blair4b42e362017-07-13 13:52:22 -070088
James E. Blairb4eab922017-08-04 09:29:45 -070089 A list of projects to be treated as :term:`config projects
90 <config-project>` in this tenant. The jobs in a config project
91 are trusted, which means they run with extra privileges, do not
92 have their configuration dynamically loaded for proposed
93 changes, and Zuul config files are only searched for in the
94 ``master`` branch.
Tobias Henkeleca46202017-08-02 20:27:10 +020095
James E. Blairb4eab922017-08-04 09:29:45 -070096 The items in the list follow the same format described in
97 **untrusted-projects**.
James E. Blaireff5a9d2017-06-20 00:00:37 -070098
James E. Blairb4eab922017-08-04 09:29:45 -070099 .. attr:: untrusted-projects
100
101 A list of projects to be treated as untrusted in this tenant.
102 An :term:`untrusted-project` is the typical project operated on
103 by Zuul. Their jobs run in a more restrictive environment, they
104 may not define pipelines, their configuration dynamically
105 changes in response to proposed changes, and Zuul will read
106 configuration files in all of their branches.
107
Joshua Hesketh731cdf32017-12-11 13:37:44 +1100108 .. attr:: <project>
James E. Blairb4eab922017-08-04 09:29:45 -0700109
110 The items in the list may either be simple string values of
111 the project names, or a dictionary with the project name as
112 key and the following values:
113
114 .. attr:: include
115
Monty Taylordb39bbb2017-08-23 17:24:00 -0400116 Normally Zuul will load all of the :ref:`configuration-items`
James E. Blairb4eab922017-08-04 09:29:45 -0700117 appropriate for the type of project (config or untrusted)
118 in question. However, if you only want to load some
119 items, the **include** attribute can be used to specify
Monty Taylordb39bbb2017-08-23 17:24:00 -0400120 that *only* the specified items should be loaded.
James E. Blairb4eab922017-08-04 09:29:45 -0700121 Supplied as a string, or a list of strings.
122
Monty Taylordb39bbb2017-08-23 17:24:00 -0400123 The following **configuration items** are recognized:
124
125 * pipeline
126 * job
127 * semaphore
128 * project
129 * project-template
130 * nodeset
131 * secret
132
James E. Blairb4eab922017-08-04 09:29:45 -0700133 .. attr:: exclude
134
Monty Taylordb39bbb2017-08-23 17:24:00 -0400135 A list of **configuration items** that should not be loaded.
James E. Blairb4eab922017-08-04 09:29:45 -0700136
137 .. attr:: shadow
138
139 A list of projects which this project is permitted to
140 shadow. Normally, only one project in Zuul may contain
141 definitions for a given job. If a project earlier in the
142 configuration defines a job which a later project
143 redefines, the later definition is considered an error and
144 is not permitted. The **shadow** attribute of a project
145 indicates that job definitions in this project which
146 conflict with the named projects should be ignored, and
147 those in the named project should be used instead. The
148 named projects must still appear earlier in the
149 configuration. In the example above, if a job definition
150 appears in both the ``common-config`` and ``zuul-jobs``
151 projects, the definition in ``common-config`` will be
152 used.
153
154 .. attr:: exclude-unprotected-branches
155
156 Define if unprotected github branches should be
157 processed. Defaults to the tenant wide setting of
158 exclude-unprotected-branches.
159
160 .. attr:: max-nodes-per-job
161 :default: 5
162
163 The maximum number of nodes a job can request. A value of
164 '-1' value removes the limit.
165
Tristan Cacquerayc98bff72017-09-10 15:25:26 +0000166 .. attr:: max-job-timeout
167 :default: 10800
168
169 The maximum timeout for jobs. A value of '-1' value removes the limit.
170
James E. Blairb4eab922017-08-04 09:29:45 -0700171 .. attr:: exclude-unprotected-branches
172 :default: false
173
174 When using a branch and pull model on a shared GitHub repository
175 there are usually one or more protected branches which are gated
176 and a dynamic number of personal/feature branches which are the
177 source for the pull requests. These branches can potentially
178 include broken Zuul config and therefore break the global tenant
179 wide configuration. In order to deal with this Zuul's operations
180 can be limited to the protected branches which are gated. This
181 is a tenant wide setting and can be overridden per project.
182 This currently only affects GitHub projects.
James E. Blair2bab6e72017-08-07 09:52:45 -0700183
184 .. attr:: default-parent
185 :default: base
186
187 If a job is defined without an explicit :attr:`job.parent`
188 attribute, this job will be configured as the job's parent.
189 This allows an administrator to configure a default base job to
190 implement local policies such as node setup and artifact
191 publishing.