RTD Allow projects to change their default-version
[releng/global-jjb.git] / docs / configuration.rst
1 #############
2 Configuration
3 #############
4
5 .. _defaults-yaml:
6
7 defaults.yaml
8 =============
9
10 This file lives in the ci-management repo typically under the path
11 ``jjb/defaults.yaml``. The purpose of this file is to store default variable
12 values used by global-jjb templates.
13
14 **Required**
15
16 :jenkins-ssh-credential: The name of the Jenkins Credential to
17     use for ssh connections. (ex: jenkins-ssh)
18
19 :lftools-version: Version of lftools to install. Can be a specific version
20     like '0.6.1' or a `PEP-440 definition <https://www.python.org/dev/peps/pep-0440/>`_
21     For example `<1.0.0` or `>=1.0.0,<2.0.0`.
22
23 :mvn-site-id: Maven Server ID from settings.xml containing the credentials
24     to push to a Maven site repository.
25
26 :mvn-staging-id: Maven Server ID from settings.xml containing the credentials
27     to push to a Maven staging repository.
28
29 **Gerrit required parameters**:
30
31 :gerrit-server-name: The name of the Gerrit Server as defined in Gerrit
32     Trigger global configuration. (ex: Primary)
33
34 **GitHub required parameters**:
35
36 :git-url: Set this to the base URL of your GitHub repo. In
37     general this should be https://github.com. If you are using
38     GitHub Enterprise, or some other GitHub-style system, then it
39     should be whatever your installation base URL is. This sets a job
40     property that GitHub Pull Request Builder requires to work.
41     Note that this is the web url to your project: (eg. https://github.com/$ORG/$PROJECT)
42
43 :git-clone-url: This is the clone prefix used by GitHub jobs.
44     Set this to either the same base url as **git-url**, or to
45     'git@github.com:' including the trailing ':'.  Determined
46     by your clone method (https or git).
47
48 :github-org: The name of the GitHub organization interpolated
49     into the scm config.
50
51 :github_pr_org: The name of the GitHub organization. All members
52     of this organization will be able to trigger jobs.
53
54 :github_pr_whitelist: List of GitHub members you wish to be able to
55     trigger jobs.
56
57 :github_pr_admin_list: List of GitHub members that will have admin
58     privileges on the jobs.
59
60 Example Gerrit Infra:
61
62 .. code-block:: yaml
63
64    - defaults:
65        name: global
66
67        # lf-infra defaults
68        jenkins-ssh-credential: jenkins-ssh
69        gerrit-server-name: OpenDaylight
70        lftools-version: '<1.0.0'
71        mvn-site-id: opendaylight-site
72        mvn-staging-id: opendaylight-staging
73
74 Example GitHub Infra:
75
76 .. code-block:: yaml
77
78    - defaults:
79        name: global
80
81        # lf-infra defaults
82        jenkins-ssh-credential: jenkins-ssh
83        github-org: lfit
84        github_pr_whitelist:
85          - jpwku
86          - tykeal
87          - zxiiro
88        github_pr_admin_list:
89          - tykeal
90        lftools-version: '<1.0.0'
91        mvn-site-id: opendaylight-site
92        mvn-staging-id: opendaylight-staging
93
94 .. _jenkins-files:
95
96 Jenkins Files
97 =============
98
99 global-jjb makes use of the Jenkins Config File Provider plugin to provide some
100 default configurations for certain tools. This section details the files to
101 define in Jenkins' **Managed Files** configuration (eg: https://jenkins.example.org/configfiles/index).
102
103 .. _npmrc:
104
105 npmrc
106 -----
107
108 This file contains default npmrc configuration and lives in $HOME/.npmrc.
109 Documentation for npmrc is available via the `npm project
110 <https://docs.npmjs.com/files/npmrc>`_.
111
112 :Required: This file MUST exist. An empty file is acceptable if a
113     proxy is not available for the project.
114 :type: Custom file
115
116 Create a **Custom file** with contents:
117
118 .. code-block:: ini
119
120    registry = https://nexus.opendaylight.org/content/repositories/npmjs/
121
122 .. _clouds-yaml:
123
124 clouds-yaml
125 -----------
126
127 Needed by ``openstack client`` and ``packer`` to fetch OpenStack
128 credentials and configuration. This file is OpenStack's `clouds.yaml
129 <https://docs.openstack.org/python-openstackclient/pike/configuration/index.html>`_
130 file.
131
132 :Optional: Needed for jobs that use ``openstack client``. ``packer`` if
133     building against OpenStack infra.
134 :type: Custom file
135
136 Create a **Custom file** with contents:
137
138 .. code-block:: yaml
139
140    clouds:
141    vex:
142     auth:
143       project_name: OS_PROJECT_NAME
144       username: OS_USERNAME
145       password: OS_PASSWORD
146       auth_url: 'https://auth.vexxhost.net/v3/'
147       user_domain_name: Default
148       project_domain_name: Default
149     region_name: ca-ymq-1
150
151 .. warning::
152
153    If using packer 1.3.0 make sure that the clouds.yaml **profile**
154    configuration is **NOT** configured. Using **profile** causes packer to look
155    for another file called ``clouds-public.yaml`` for configuration.
156
157
158 .. _pipconf:
159
160 pipconf
161 -------
162
163 This file contains default configuration for the python-pip tool and lives
164 in $HOME/.config/pip/pip.conf. Documentation for pip.conf is available via the
165 `pip project <https://pip.readthedocs.io/en/stable/user_guide/#configuration>`_.
166
167 :Required: This file MUST exist. An empty file is acceptable if a
168     proxy is not available for the project.
169 :type: Custom file
170
171 Create a **Custom file** with contents:
172
173 .. code-block:: ini
174
175    [global]
176    timeout = 60
177    index-url = https://nexus3.opendaylight.org/repository/PyPi/simple
178
179 .. _jjbini:
180
181 jjbini
182 ------
183
184 This file contains the Jenkins Job Builder `configuration
185 <https://docs.openstack.org/infra/jenkins-job-builder/execution.html#configuration-file>`_
186 for :doc:`jjb/lf-ci-jobs`.
187
188 :Required: This file MUST exist.
189 :type: Custom file
190
191 Create a **Custom file** with contents:
192
193 .. code-block:: ini
194
195     [job_builder]
196     ignore_cache=True
197     keep_descriptions=False
198     include_path=.:scripts:~/git/
199     recursive=True
200
201     [jenkins]
202     user=jenkins-jobbuilder
203     password=1234567890abcdef1234567890abcdef
204     url=https://jenkins.example.org
205     query_plugins_info=False
206
207     [production]
208     user=jenkins-jobbuilder
209     password=1234567890abcdef1234567890abcdef
210     url=https://jenkins.example.org
211     query_plugins_info=False
212
213     [sandbox]
214     user=jenkins-jobbuilder
215     password=1234567890abcdef1234567890abcdef
216     url=https://jenkins.example.org/sandbox
217     query_plugins_info=False
218
219 The last 2 sections are for the ``jenkins-cfg`` job use, they should match the
220 ``silo`` names for the respective Jenkins systems, typically ``production`` and
221 ``sandbox``.
222
223 .. _jenkins-log-archives-settings:
224
225 jenkins-log-archives-settings
226 -----------------------------
227
228 See :ref:`lf-infra-ship-logs` for usage. If not archiving logs then keep this
229 file with default settings, global-jjb needs the file to exist to function.
230
231 Requires a *credential* named 'logs' of type 'Username and Password' created in
232 the Jenkins Credentials system.
233
234 #. Add Server Credentials
235 #. Set ``ServerId`` to ``logs``
236 #. Set ``Credentials`` to the ``logs`` user created in the Credentials System
237
238 :Required: This file MUST exist if using log archiving.
239 :type: Maven settings.xml
240
241 .. code-block:: xml
242
243    <?xml version="1.0" encoding="UTF-8"?>
244    <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
245              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
246              xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
247    </settings>
248
249 .. note::
250
251    This example is the default boilerplate generated by Jenkins with
252    the comments stripped out. We can also use the default generated by Jenkins
253    without modifying it.
254
255 .. _packer-cloud-env:
256
257 packer-cloud-env
258 ----------------
259
260 Cloud environment configuration variables for Packer jobs. These can
261 contain credentials and configuration for whichever clouds packer jobs
262 are using.
263
264 :Required: This file MUST exist to use packer jobs.
265 :type: Json file
266
267 .. code-block:: json
268
269    {
270      "cloud_auth_url": "https://auth.vexxhost.net/v3/",
271      "cloud_tenant": "TENANT_ID",
272      "cloud_user": "CLOUD_USERNAME",
273      "cloud_pass": "CLOUD_PASSWORD",
274      "cloud_network": "CLOUD_NETWORK",
275      "ssh_proxy_host": ""
276    }
277
278 .. _jenkins-ci-jobs:
279
280 Jenkins CI Jobs
281 ===============
282
283 .. _jenkins-cfg-merge:
284
285 jenkins-cfg-merge
286 -----------------
287
288 This job manages Jenkins Global configuration. Refer to
289 the :ref:`CI Documentation <lf-global-jjb-jenkins-cfg-merge>` for job
290 configuration details.
291
292 .. _log-archiving:
293
294 Log Archiving
295 =============
296
297 The logs account requires a Maven Settings file created called
298 **jenkins-log-archives-settings** with a server ID of **logs** containing the
299 credentials for the logs user in Nexus.