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