docs/jjb/lf-ci-jobs.rst

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