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
 352     :gerrit_merge_triggers: Override Gerrit Triggers.
 353     :gerrit_trigger_file_paths: Override file paths which can be used to
 354         filter which file modifications will trigger a build.
 355         (default defined by lf_jjb_common)
 356
 357
 358 JJB Verify
 359 ----------
 360
 361 Runs `jenkins-jobs test` to validate JJB syntax
 362
 363 :Template Names:
 364     - {project-name}-jjb-verify
 365     - gerrit-jjb-verify
 366     - github-jjb-verify
 367
 368 :Comment Trigger: recheck|reverify
 369
 370 :Required parameters:
 371
 372     :build-node: The node to run build on.
 373     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 374         be configured in defaults.yaml)
 375
 376 :Optional parameters:
 377
 378     :branch: Git branch to fetch for the build. (default: master)
 379     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 380     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 381     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 382     :jjb-version: JJB version to install. (default: see job-template)
 383     :stream: Keyword that can be used to represent a release code-name.
 384         Often the same as the branch. (default: master)
 385     :submodule-recursive: Whether to checkout submodules recursively.
 386         (default: true)
 387
 388     :gerrit_verify_triggers: Override Gerrit Triggers.
 389     :gerrit_trigger_file_paths: Override file paths which can be used to
 390         filter which file modifications will trigger a build.
 391         (default defined by lf_jjb_common)
 392
 393 .. _jjb-verify-upstream-gjjb:
 394
 395 JJB Verify Upstream Global JJB
 396 ------------------------------
 397
 398 Runs ``jenkins-jobs test`` to validate JJB syntax for upstream global-jjb
 399 patches. This job is useful to notify upstream that they may be breaking
 400 project level jobs.
 401
 402 :Template Names:
 403     - {project-name}-jjb-verify-upstream-gjjb
 404     - gerrit-jjb-verify-upstream-gjjb
 405
 406 :Comment Trigger: recheck|reverify
 407
 408 :Required parameters:
 409
 410     :build-node: The node to run build on.
 411     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 412         be configured in defaults.yaml)
 413
 414 :Optional parameters:
 415
 416     :branch: Git branch to fetch for the build. (default: master)
 417     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 418     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 419     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 420     :jjb-version: JJB version to install. (default: see job-template)
 421     :stream: Keyword that can be used to represent a release code-name.
 422         Often the same as the branch. (default: master)
 423
 424 .. _info-yaml-verify:
 425
 426 Info YAML Verify
 427 ----------------
 428
 429 Info YAML Verify job validates that INFO.yaml file changes are kept isolated from
 430 other file changes. Verifies INFO.yaml files follow the schema defined in
 431 `global-jjb/info-schema`.
 432
 433 :Template Names:
 434     - {project-name}-info-yaml-verify
 435     - gerrit-info-yaml-verify
 436     - github-info-yaml-verify
 437
 438 :Required parameters:
 439
 440     :build-node: The node to run build on.
 441     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 442         be configured in defaults.yaml)
 443
 444 :Optional parameters:
 445
 446     :branch: Git branch to fetch for the build. (default: master)
 447     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 448     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 449     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 450     :stream: Keyword that can be used to represent a release code-name.
 451         Often the same as the branch. (default: master)
 452     :submodule-recursive: Whether to checkout submodules recursively.
 453         (default: true)
 454     :gerrit_verify_triggers: Override Gerrit Triggers.
 455
 456 .. _license-checker:
 457
 458 License Checker
 459 ---------------
 460
 461 Job to scan projects for files missing license headers.
 462
 463 :Template Names:
 464     - {project-name}-license-check
 465     - gerrit-license-check
 466     - github-license-check
 467
 468 :Optional parameters:
 469
 470     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 471     :file-patterns: Space-separated list of file patterns to scan.
 472         (default: \*.go \*.groovy \*.java \*.py \*.sh)
 473     :spdx-disable: Disable the SPDX-Identifier checker. (default: false)
 474     :lhc-version: Version of LHC to use. (default: 0.2.0)
 475     :license-exclude-paths: Comma-separated list of paths to exclude from the
 476         license checker. The paths used here will be matched using a contains
 477         rule so it is best to be as precise with the path as possible.
 478         For example a path of '/src/generated/' will be searched as
 479         '**/src/generated/**'.
 480         Example: org/opendaylight/yang/gen,protobuff/messages
 481         (default: '')
 482     :licenses-allowed: Comma-separated list of allowed licenses.
 483         (default: Apache-2.0,EPL-1.0,MIT)
 484     :project-pattern: The ANT based pattern for Gerrit Trigger to choose which
 485         projects to trigger job against. (default: '**')
 486
 487 .. _gjjb-openstack-cron:
 488
 489 OpenStack Cron
 490 --------------
 491
 492 Cron job that runs regularly to perform periodic tasks against OpenStack.
 493
 494 This job requires a Config File Provider file named ``clouds-yaml`` available
 495 containing the credentials for the cloud.
 496
 497 :Template Names:
 498     - {project-name}-openstack-cron
 499     - gerrit-openstack-cron
 500     - github-openstack-cron
 501
 502 :Required parameters:
 503
 504     :build-node: The node to run build on.
 505     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 506         be configured in defaults.yaml)
 507
 508 :Optional parameters:
 509
 510     :branch: Git branch to fetch for the build. (default: master)
 511     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 512     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 513     :cron: Time when the packer image should be rebuilt (default: @daily)
 514     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 515     :openstack-cloud: OS_CLOUD setting to pass to openstack client.
 516         (default: vex)
 517     :stream: Keyword that can be used to represent a release code-name.
 518         Often the same as the branch. (default: master)
 519     :submodule-recursive: Whether to checkout submodules recursively.
 520         (default: true)
 521
 522 .. _gjjb-packer-merge:
 523
 524 Packer Merge
 525 ------------
 526
 527 Packer Merge job runs `packer build` to build system images in the cloud.
 528
 529 :Template Names:
 530     - {project-name}-packer-merge-{platforms}-{templates}
 531     - gerrit-packer-merge
 532     - github-packer-merge
 533
 534 :Comment Trigger: remerge
 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     :platforms: Platform or distribution to build. Typically json file
 544         found in the packer/vars directory. (Example: centos)
 545     :template: System template to build. Typically shell script found in
 546         the packer/provision directory. (Example: java-builder)
 547
 548 :Optional parameters:
 549
 550     :cron: Time when the packer image should be rebuilt (default: @monthly)
 551     :branch: Git branch to fetch for the build. (default: master)
 552     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 553     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 554     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 555     :openstack: Packer template uses an OpenStack builder (default: true).
 556     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
 557         (default: vex).
 558     :packer-cloud-settings: Name of settings file containing credentials
 559         for the cloud that packer will build on. (default: packer-cloud-env)
 560     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 561     :stream: Keyword that can be used to represent a release code-name.
 562         Often the same as the branch. (default: master)
 563     :submodule-recursive: Whether to checkout submodules recursively.
 564         (default: true)
 565
 566     :gerrit_verify_triggers: Override Gerrit Triggers.
 567
 568
 569 .. _gjjb-packer-verify:
 570
 571 Packer Verify
 572 -------------
 573
 574 Packer Verify job runs `packer validate` to verify packer configuration.
 575
 576 :Template Names:
 577     - {project-name}-packer-verify
 578     - gerrit-packer-verify
 579     - github-packer-verify
 580
 581 :Comment Trigger: recheck|reverify
 582
 583 :Required parameters:
 584
 585     :build-node: The node to run build on.
 586     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 587         be configured in defaults.yaml)
 588     :mvn-settings: The name of settings file containing credentials for
 589         the project.
 590
 591 :Optional parameters:
 592
 593     :branch: Git branch to fetch for the build. (default: master)
 594     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 595     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 596     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 597     :openstack: Packer template uses an OpenStack builder (default: true).
 598     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
 599         (default: vex).
 600     :packer-cloud-settings: Name of settings file containing credentials
 601         for the cloud that packer will build on. (default: packer-cloud-env)
 602     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 603     :stream: Keyword that can be used to represent a release code-name.
 604         Often the same as the branch. (default: master)
 605     :submodule-recursive: Whether to checkout submodules recursively.
 606         (default: true)
 607
 608     :gerrit_verify_triggers: Override Gerrit Triggers.
 609     :gerrit_trigger_file_paths: Override file paths which can be used to
 610         filter which file modifications will trigger a build.