Merge changes from topic '10422'
[releng/global-jjb.git] / docs / jjb / lf-ci-jobs.rst
1 #######
2 CI Jobs
3 #######
4
5 Job Groups
6 ==========
7
8 {project-name}-ci-jobs
9 ----------------------
10
11 Recommended jobs that should be deployed for CI using Gerrit.
12
13 :Includes:
14
15     - gerrit-jenkins-cfg-merge
16     - gerrit-jjb-deploy-job
17     - gerrit-jjb-merge
18     - gerrit-jjb-verify
19
20 {project-name}-github-ci-jobs
21 -----------------------------
22
23 Recommended jobs that should be deployed CI using GitHub.
24
25 :Includes:
26
27     - github-jenkins-cfg-merge
28     - github-jjb-deploy-job
29     - github-jjb-merge
30     - github-jjb-verify
31
32 {project-name}-info-yaml-jobs
33 -----------------------------
34
35 Jobs to verify INFO.yaml file changes.
36
37 :Includes:
38
39     - gerrit-info-yaml-verify
40
41 {project-name}-github-info-yaml-jobs
42 ------------------------------------
43
44 Jobs to verify INFO.yaml file changes using Github.
45
46 :Includes:
47
48     - github-info-yaml-verify
49
50 {project-name}-packer-jobs
51 --------------------------
52
53 Jobs related to Packer builds for CI using Gerrit.
54
55 :Includes:
56
57     - gerrit-packer-merge
58     - gerrit-packer-verify
59
60 {project-name}-github-packer-jobs
61 ---------------------------------
62
63 Jobs related to Packer builds for CI using GitHub.
64
65 :Includes:
66
67     - github-packer-merge
68     - github-packer-verify
69
70 Macros
71 ======
72
73 lf-infra-jjb-parameters
74 -----------------------
75
76 :Required Parameters:
77
78     :jjb-version: Version of Jenkins Job Builder (JJB) to install and use in
79         the jjb jobs.
80
81 lf-jenkins-cfg-clouds
82 ---------------------
83
84 Deploys Jenkins Cloud configuration read from the ``jenkins-clouds`` directory
85 in ci-management repositories.
86
87 .. note::
88
89    Requires the jjbini file in Jenkins CFP to contain JJB 2.0 style
90    config definitions for "production" and "sandbox" systems.
91
92 :Required Parameters:
93
94     :jenkins-silos: Space-separated list of Jenkins silos to update
95         configuration for as defined in ~/.config/jenkins_jobs/jenkins_jobs.ini
96
97 lf-jenkins-cfg-global-vars
98 --------------------------
99
100 Manages the Global Jenkins variables. This macro will clear all exist macros
101 in Jenkins and replaces them with the ones defined by the
102 ci-management/jenkins-config/global-vars-SILO.sh script.
103
104 .. note::
105
106    Requires the jjbini file in Jenkins CFP to contain JJB 2.0 style
107    config definitions for "production" and "sandbox" systems.
108
109 :Required parameters:
110
111     :jenkins-silos: Space-separated list of Jenkins silos to update
112         configuration for as defined in ~/.config/jenkins_jobs/jenkins_jobs.ini
113
114 lf-infra-jjbini
115 ---------------
116
117 Provides jenkins_jobs.ini configuration for Jenkins.
118
119 lf-infra-jjbini-sandbox
120 -----------------------
121
122 Provides jenkins_jobs.ini configuration for Jenkins sandbox.
123
124 .. todo:: This needs to be consolidated into lf-infra-jjbini when JJB 2.0 is available
125
126 lf-packer-common
127 ----------------
128
129 Common packer configuration.
130
131 lf-packer-file-paths
132 --------------------
133
134 Gerrit file-paths for packer jobs.
135
136 lf-packer-parameters
137 --------------------
138
139 Parameters useful for packer related tasks.
140
141 :Parameters:
142
143     :packer-version: Version of packer to install / use.
144         (shell: PACKER_VERSION)
145
146 lf-packer-verify-file-paths
147 ---------------------------
148
149 Gerrit file-paths for packer verify jobs.
150
151 Job Templates
152 =============
153
154 Gerrit Branch Lock
155 ------------------
156
157 Job submits a patch to lock or unlock a project's branch.
158
159 :Template Names:
160     - {project-name}-gerrit-branch-lock-{stream}
161     - gerrit-branch-lock
162
163
164 .. _lf-global-jjb-jenkins-cfg-merge:
165
166 Jenkins Configuration Merge
167 ---------------------------
168
169 Jenkins job to manage Global Jenkins configuration.
170
171 .. note::
172
173    Requires the jjbini file in Jenkins CFP to contain JJB 2.0 style
174    config definitions for "production" and "sandbox" systems.
175
176 :Template names:
177
178     - {project-name}-jenkins-cfg-merge
179     - gerrit-jenkins-cfg-merge
180     - github-jenkins-cfg-merge
181
182 :Optional parameters:
183
184     :branch: Git branch to build against. (default: master)
185     :cron: How often to run the job on a cron schedule. (default: @daily)
186     :git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
187     :jenkins-silos: Space separated list of Jenkins silos to update
188         configuration for as defined in ~/.config/jenkins_jobs/jenkins_jobs.ini
189         (default: production sandbox)
190
191 Typically this template is automatically pulled in by the
192 "{project-name}-ci-jobs" job-group and does not need to be explicitly called if
193 the job group is being used.
194
195 Miniaml Example:
196
197 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/jenkins-cfg-merge-minimal.yaml
198    :language: yaml
199
200 Full Example:
201
202 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/jenkins-cfg-merge-full.yaml
203    :language: yaml
204
205 .. _jenkins-cfg-envvar:
206
207 Global Environment Variables
208 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
209
210 Global Environment Variables are managed via the
211 ``jenkins-config/global-vars-SILO.sh`` file in ci-management. Replace SILO with
212 the name of the Jenkins silo the variable configuration is for.
213
214 The format for this file is ``KEY=value`` for example::
215
216     GERRIT_URL=https://git.opendaylight.org/gerrit
217     GIT_BASE=git://devvexx.opendaylight.org/mirror/$PROJECT
218     GIT_URL=git://devvexx.opendaylight.org/mirror
219     JENKINS_HOSTNAME=vex-yul-odl-jenkins-2
220     LOGS_SERVER=https://logs.opendaylight.org
221     NEXUS_URL=https://nexus.opendaylight.org
222     ODLNEXUSPROXY=https://nexus.opendaylight.org
223     SILO=sandbox
224     SONAR_URL=https://sonar.opendaylight.org
225
226 Cloud Configuration
227 ^^^^^^^^^^^^^^^^^^^
228
229 This configuration requires the OpenStack Cloud plugin in Jenkins and is
230 currently the only cloud plugin supported.
231
232 OpenStack Cloud plugin version supported:
233
234 * 2.30
235 * 2.31
236 * 2.32
237 * 2.33
238 * 2.34
239 * 2.35
240
241 Cloud configuration are managed via a directory structure in ci-management as
242 follows:
243
244 - jenkins-config/clouds/openstack/
245 - jenkins-config/clouds/openstack/cattle/cloud.cfg
246 - jenkins-config/clouds/openstack/cattle/centos7-builder-2c-2g.cfg
247 - jenkins-config/clouds/openstack/cattle/centos7-builder-4c-4g.cfg
248 - jenkins-config/clouds/openstack/cattle/centos7-docker-4c-4g.cfg
249
250 The directory name inside of the "openstack" directory is used as the name of
251 the cloud configuration. In this case "cattle" is being used as the cloud name.
252
253 The ``cloud.cfg`` file is a special file used to configure the main cloud
254 configuration in the format ``KEY=value``.
255
256 :Cloud Parameters:
257
258     :CLOUD_URL: API endpoint URL for Keystone.
259         (default: "")
260     :CLOUD_IGNORE_SSL: Ignore unverified SSL certificates. (default: false)
261     :CLOUD_ZONE: OpenStack region to use. (default: "")
262     :CLOUD_CREDENTIAL_ID: Credential to use for authentication to OpenStack.
263         (default: "os-cloud")
264     :INSTANCE_CAP: Total number of instances the cloud will allow spin up.
265         (default: null)
266     :SANDBOX_CAP: Total number of instances the clodu will allow to
267         spin up. This applies to "sandbox" systems and overrides the
268         INSTANCE_CAP setting. (default: null)
269
270 :Template Parameters:
271
272     .. note::
273
274        In the case of template definitions of a parameter below is not passed
275        the one defined in default clouds will be inherited.
276
277     :IMAGE_NAME: The image name to use for this template.
278         (default: "")
279     :LABELS: Labels to assign to the vm. (default: FILE_NAME)
280     :HARDWARE_ID: OpenStack flavor to use. (default: "")
281     :NETWORK_ID: OpenStack network to use. (default: "")
282     :USER_DATA_ID: User Data to pass into the instance.
283         (default: jenkins-init-script)
284     :INSTANCE_CAP: Total number of instances of this type that can be launched
285         at one time. When defined in clouds.cfg it defines the total for the
286         entire cloud. (default: null)
287     :SANDBOX_CAP: Total number of instances of this type that can be launched
288         at one time. When defined in clouds.cfg it defines the total for the
289         entire cloud. This applies to "sandbox" systems and overrides the
290         INSTANCE_CAP setting. (default: null)
291     :FLOATING_IP_POOL: Floating ip pool to use. (default: "")
292     :SECURITY_GROUPS: Security group to use. (default: "default")
293     :AVAILABILITY_ZONE: OpenStack availability zone to use. (default: "")
294     :START_TIMEOUT: Number of milliseconds to wait for the agent to be
295         provisioned and connected. (default: 600000)
296     :KEY_PAIR_NAME: SSH Public Key Pair to use for authentication.
297         (default: jenkins)
298     :NUM_EXECUTORS: Number of executors to enable for the instance.
299         (default: 1)
300     :JVM_OPTIONS: JVM Options to pass to Java. (default: "")
301     :FS_ROOT: File system root for the workspace. (default: "/w")
302     :RETENTION_TIME: Number of minutes to wait for an idle slave to be used
303         again before it's removed. If set to -1, the slave will be kept
304         forever. (default: 0)
305
306 For a live example see the OpenDaylight project jenkins-config directory.
307 https://github.com/opendaylight/releng-builder/tree/master/jenkins-config
308
309 Troubleshooting
310 ^^^^^^^^^^^^^^^
311
312 :Cloud Configuration:
313
314     The directory ``groovy-inserts`` contains the groovy script output that is
315     used to push to Jenkins. In the event of a job failure this file can be
316     inspected.
317
318
319 JJB Deploy Job
320 --------------
321
322 Deploy jobs to jenkins-sandbox system via code review comment
323
324 This job checks out the current code review patch and then runs a
325 `jenkins-jobs update` to push a patch defined by the comment.
326
327 :Template names:
328
329     - {project-name}-jjb-deploy-job
330     - gerrit-jjb-deploy-job
331     - github-jjb-deploy-job
332
333 :Comment Trigger: jjb-deploy JOB_NAME
334
335     .. note::
336
337        JOB_NAME can include the * wildcard character to push multiple jobs
338        matching the pattern. For example `jjb-deploy builder-jjb-*`` will push
339        all builder-jjb-* jobs to the sandbox system.
340
341 :Required parameters:
342
343     :build-node: The node to run build on.
344     :jenkins-ssh-credential: Credential to use for SSH. (Generally
345         should be configured in defaults.yaml)
346
347 :Optional parameters:
348
349     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
350     :gerrit_jjb_deploy_job_triggers: Override Gerrit Triggers.
351
352
353 JJB Merge
354 ---------
355
356 Runs `jenkins-jobs update` to update production job configuration
357
358 :Template Names:
359     - {project-name}-jjb-merge
360     - gerrit-jjb-merge
361     - github-jjb-merge
362
363 :Required parameters:
364
365     :build-node: The node to run build on.
366     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
367         be configured in defaults.yaml)
368     :mvn-settings: The name of settings file containing credentials for
369         the project.
370
371 :Optional parameters:
372
373     :branch: Git branch to fetch for the build. (default: master)
374     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
375     :build-timeout: Timeout in seconds before aborting build. (default: 10)
376     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
377     :stream: Keyword that can be used to represent a release code-name.
378         Often the same as the branch. (default: master)
379     :submodule-recursive: Whether to checkout submodules recursively.
380         (default: true)
381
382     :gerrit_merge_triggers: Override Gerrit Triggers.
383     :gerrit_trigger_file_paths: Override file paths which can be used to
384         filter which file modifications will trigger a build.
385         (default defined by lf_jjb_common)
386
387
388 JJB Verify
389 ----------
390
391 Runs `jenkins-jobs test` to validate JJB syntax
392
393 :Template Names:
394     - {project-name}-jjb-verify
395     - gerrit-jjb-verify
396     - github-jjb-verify
397
398 :Required parameters:
399
400     :build-node: The node to run build on.
401     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
402         be configured in defaults.yaml)
403     :mvn-settings: The name of settings file containing credentials for
404         the project.
405
406 :Optional parameters:
407
408     :branch: Git branch to fetch for the build. (default: master)
409     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
410     :build-timeout: Timeout in seconds before aborting build. (default: 10)
411     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
412     :stream: Keyword that can be used to represent a release code-name.
413         Often the same as the branch. (default: master)
414     :submodule-recursive: Whether to checkout submodules recursively.
415         (default: true)
416
417     :gerrit_verify_triggers: Override Gerrit Triggers.
418     :gerrit_trigger_file_paths: Override file paths which can be used to
419         filter which file modifications will trigger a build.
420         (default defined by lf_jjb_common)
421
422 .. _info-yaml-verify:
423
424 Info YAML Verify
425 ----------------
426
427 Info YAML Verify job validates that INFO.yaml file changes are kept isolated from
428 other file changes. Verifies INFO.yaml files follow the schema defined in
429 `global-jjb/info-schema`.
430
431 :Template Names:
432     - {project-name}-info-yaml-verify
433     - gerrit-info-yaml-verify
434     - github-info-yaml-verify
435
436 :Required parameters:
437
438     :build-node: The node to run build on.
439     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
440         be configured in defaults.yaml)
441
442 :Optional parameters:
443
444     :branch: Git branch to fetch for the build. (default: master)
445     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
446     :build-timeout: Timeout in seconds before aborting build. (default: 10)
447     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
448     :stream: Keyword that can be used to represent a release code-name.
449         Often the same as the branch. (default: master)
450     :submodule-recursive: Whether to checkout submodules recursively.
451         (default: true)
452     :gerrit_verify_triggers: Override Gerrit Triggers.
453
454 .. _license-checker:
455
456 License Checker
457 ---------------
458
459 Job to scan projects for files missing license headers.
460
461 :Template Names:
462     - {project-name}-license-check
463     - gerrit-license-check
464     - github-license-check
465
466 :Optional parameters:
467
468     :file-patterns: Space-separated list of file patterns to scan.
469         (default: \*.go \*.groovy \*.java \*.py \*.sh)
470     :spdx-disable: Disable the SPDX-Identifier checker. (default: false)
471     :lhc-version: Version of LHC to use. (default: 0.2.0)
472     :license-exclude-paths: Comma-separated list of paths to exclude from the
473         license checker. The paths used here will be matched using a contains
474         rule so it is best to be as precise with the path as possible.
475         For example a path of '/src/generated/' will be searched as
476         '**/src/generated/**'.
477         Example: org/opendaylight/yang/gen,protobuff/messages
478         (default: '')
479     :licenses-allowed: Comma-separated list of allowed licenses.
480         (default: Apache-2.0,EPL-1.0,MIT)
481
482 .. _gjjb-packer-merge:
483
484 Packer Merge
485 ------------
486
487 Packer Merge job runs `packer build` to build system images in the cloud.
488
489 :Template Names:
490     - {project-name}-packer-merge-{platforms}-{templates}
491     - gerrit-packer-merge
492     - github-packer-merge
493
494 :Required parameters:
495
496     :build-node: The node to run build on.
497     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
498         be configured in defaults.yaml)
499     :mvn-settings: The name of settings file containing credentials for
500         the project.
501     :platforms: Platform or distribution to build. Typically json file
502         found in the packer/vars directory. (Example: centos)
503     :template: System template to build. Typically shell script found in
504         the packer/provision directory. (Example: java-builder)
505
506 :Optional parameters:
507
508     :cron: Time when the packer image should be rebuilt (default: @monthly)
509     :branch: Git branch to fetch for the build. (default: master)
510     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
511     :build-timeout: Timeout in seconds before aborting build. (default: 10)
512     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
513     :packer-cloud-settings: Name of settings file containing credentials
514         for the cloud that packer will build on. (default: packer-cloud-env)
515     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
516     :stream: Keyword that can be used to represent a release code-name.
517         Often the same as the branch. (default: master)
518     :submodule-recursive: Whether to checkout submodules recursively.
519         (default: true)
520
521     :gerrit_verify_triggers: Override Gerrit Triggers.
522
523
524 .. _gjjb-packer-verify:
525
526 Packer Verify
527 -------------
528
529 Packer Verify job runs `packer validate` to verify packer configuration.
530
531 :Template Names:
532     - {project-name}-packer-verify
533     - gerrit-packer-verify
534     - github-packer-verify
535
536 :Required parameters:
537
538     :build-node: The node to run build on.
539     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
540         be configured in defaults.yaml)
541     :mvn-settings: The name of settings file containing credentials for
542         the project.
543
544 :Optional parameters:
545
546     :branch: Git branch to fetch for the build. (default: master)
547     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
548     :build-timeout: Timeout in seconds before aborting build. (default: 10)
549     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
550     :packer-cloud-settings: Name of settings file containing credentials
551         for the cloud that packer will build on. (default: packer-cloud-env)
552     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
553     :stream: Keyword that can be used to represent a release code-name.
554         Often the same as the branch. (default: master)
555     :submodule-recursive: Whether to checkout submodules recursively.
556         (default: true)
557
558     :gerrit_verify_triggers: Override Gerrit Triggers.
559     :gerrit_trigger_file_paths: Override file paths which can be used to
560         filter which file modifications will trigger a build.