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-cache: Location of Jenkins Job Builder (JJB) cache used for jjb
  25         jobs.
  26     :jjb-version: Version of Jenkins Job Builder (JJB) to install and use in
  27         the jjb jobs.
  28
  29 lf-jenkins-cfg-clouds
  30 ---------------------
  31
  32 Deploys Jenkins Cloud configuration read from the ``jenkins-clouds`` directory
  33 in ci-management repositories.
  34
  35 .. note::
  36
  37    Requires the jjbini file in Jenkins CFP to contain JJB 2.0 style
  38    config definitions for "production" and "sandbox" systems.
  39
  40 :Required Parameters:
  41
  42     :jenkins-silos: Space-separated list of Jenkins silos to update
  43         configuration for as defined in ~/.config/jenkins_jobs/jenkins_jobs.ini
  44
  45 lf-jenkins-cfg-global-vars
  46 --------------------------
  47
  48 Manages the Global Jenkins variables. This macro will clear all exist macros
  49 in Jenkins and replaces them with the ones defined by the
  50 ci-management/jenkins-config/global-vars-SILO.sh script.
  51
  52 .. note::
  53
  54    Requires the jjbini file in Jenkins CFP to contain JJB 2.0 style
  55    config definitions for "production" and "sandbox" systems.
  56
  57 :Required parameters:
  58
  59     :jenkins-silos: Space-separated list of Jenkins silos to update
  60         configuration for as defined in ~/.config/jenkins_jobs/jenkins_jobs.ini
  61
  62 lf-infra-jjbini
  63 ---------------
  64
  65 Provides jenkins_jobs.ini configuration for Jenkins.
  66
  67 lf-packer-common
  68 ----------------
  69
  70 Common packer configuration.
  71
  72 lf-packer-file-paths
  73 --------------------
  74
  75 Gerrit file-paths for packer jobs.
  76
  77 lf-packer-parameters
  78 --------------------
  79
  80 Parameters useful for packer related tasks.
  81
  82 :Parameters:
  83
  84     :packer-version: Version of packer to install / use.
  85         (shell: PACKER_VERSION)
  86
  87 lf-packer-verify-file-paths
  88 ---------------------------
  89
  90 Gerrit file-paths for packer verify jobs.
  91
  92 lf-puppet-parameters
  93 --------------------
  94
  95 Parameters useful for Puppet related tasks.
  96
  97 :Parameters:
  98
  99     :puppet-lint-version: Version of puppet-lint to install / use.
 100         (shell: PUPPET_LINT_VERSION)
 101
 102 Job Templates
 103 =============
 104
 105 .. _gerrit-branch-lock:
 106
 107 Gerrit Branch Lock
 108 ------------------
 109
 110 Job submits a patch to lock or unlock a project's branch.
 111
 112 This job will process lock/unlock requests for all projects and all branches
 113 and does not need to have per-project configuration.
 114
 115 :Template Names:
 116     - {project-name}-gerrit-branch-lock
 117     - gerrit-branch-lock
 118
 119 :Comment Trigger:
 120
 121     * lock branch
 122     * unlock branch
 123
 124 :Required parameters:
 125
 126     :build-node: The node to run build on.
 127     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
 128         in defaults.yaml)
 129
 130 :Optional parameters:
 131
 132     :git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
 133     :submodule-timeout: Timeout (in minutes) for checkout operation.
 134         (default: 10)
 135     :gerrit_merge_triggers: Override Gerrit Triggers.
 136
 137 .. _lf-global-jjb-jenkins-cfg-merge:
 138
 139 Jenkins Configuration Merge
 140 ---------------------------
 141
 142 Jenkins job to manage Global Jenkins configuration.
 143
 144 .. note::
 145
 146    Requires the jjbini file in Jenkins CFP to contain JJB 2.0 style
 147    config definitions for "production" and "sandbox" systems.
 148
 149 :Template names:
 150
 151     - {project-name}-jenkins-cfg-merge
 152     - gerrit-jenkins-cfg-merge
 153     - github-jenkins-cfg-merge
 154
 155 :Optional parameters:
 156
 157     :branch: Git branch to build against. (default: master)
 158     :cron: How often to run the job on a cron schedule. (default: @daily)
 159     :git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
 160     :jenkins-silos: Space separated list of Jenkins silos to update
 161         configuration for as defined in ~/.config/jenkins_jobs/jenkins_jobs.ini
 162         (default: production sandbox)
 163
 164 Typically this template is automatically pulled in by the
 165 "{project-name}-ci-jobs" job-group and does not need to be explicitly called if
 166 you are already using the job group.
 167
 168 Minimal Example:
 169
 170 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/jenkins-cfg-merge-minimal.yaml
 171    :language: yaml
 172
 173 Full Example:
 174
 175 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/jenkins-cfg-merge-full.yaml
 176    :language: yaml
 177
 178 .. _jenkins-cfg-envvar:
 179
 180 Global Environment Variables
 181 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 182
 183 Manage Global Environment Variables via the
 184 ``jenkins-config/global-vars-SILO.sh`` file in ci-management. Replace SILO with
 185 the name of the Jenkins silo the variable configuration is for.
 186
 187 The format for this file is ``KEY=value`` for example::
 188
 189     GERRIT_URL=https://git.opendaylight.org/gerrit
 190     GIT_BASE=git://devvexx.opendaylight.org/mirror/$PROJECT
 191     GIT_URL=git://devvexx.opendaylight.org/mirror
 192     JENKINS_HOSTNAME=vex-yul-odl-jenkins-2
 193     LOGS_SERVER=https://logs.opendaylight.org
 194     NEXUS_URL=https://nexus.opendaylight.org
 195     ODLNEXUSPROXY=https://nexus.opendaylight.org
 196     SILO=sandbox
 197     SONAR_URL=https://sonar.opendaylight.org
 198
 199 Cloud Configuration
 200 ^^^^^^^^^^^^^^^^^^^
 201
 202 This configuration requires the **OpenStack Cloud plugin** in Jenkins.
 203
 204 OpenStack Cloud plugin version supported:
 205
 206 * 2.30 - 2.34
 207 * 2.35 - 2.37
 208
 209 Cloud configuration follows a directory structure in ci-management like this:
 210
 211 - jenkins-config/clouds/openstack/
 212 - jenkins-config/clouds/openstack/**cattle**/cloud.cfg
 213 - jenkins-config/clouds/openstack/**cattle**/centos7-builder-2c-2g.cfg
 214 - jenkins-config/clouds/openstack/**cattle**/centos7-builder-4c-4g.cfg
 215 - jenkins-config/clouds/openstack/**cattle**/centos7-docker-4c-4g.cfg
 216
 217 This job uses the directory name of the directory inside of the "openstack"
 218 directory as the name of the cloud configuration in Jenkins. This is to support
 219 systems that want to use more than one cloud provider. In this example "cattle"
 220 is the cloud name.
 221
 222 The ``cloud.cfg`` file is a special file used to configure the main cloud
 223 configuration in the format ``KEY=value``.
 224
 225 :Cloud Parameters:
 226
 227     :CLOUD_URL: API endpoint URL for Keystone.
 228         (default: "")
 229     :CLOUD_IGNORE_SSL: Ignore unverified SSL certificates. (default: false)
 230     :CLOUD_ZONE: OpenStack region to use. (default: "")
 231     :CLOUD_CREDENTIAL_ID: Credential to use for authentication to OpenStack.
 232         (default: "os-cloud")
 233     :INSTANCE_CAP: Total number of instances the cloud will allow spin up.
 234         (default: null)
 235     :SANDBOX_CAP: Total number of instances the cloud will allow to
 236         spin up. This applies to "sandbox" systems and overrides the
 237         INSTANCE_CAP setting. (default: null)
 238
 239 :Template Parameters:
 240
 241     .. note::
 242
 243         Parameters below that are not defined will inherit the ones defined in
 244         the default clouds configuration.
 245
 246     :IMAGE_NAME: The image name to use for this template. (required)
 247     :HARDWARE_ID: OpenStack flavor to use. (required)
 248
 249     :LABELS: Labels to assign to the vm. (default: FILE_NAME)
 250     :VOLUME_SIZE: Volume size to assign to vm. (default: "")
 251     :HARDWARE_ID: Hardware Id to assign to vm. (default: "")
 252     :NETWORK_ID: OpenStack network to use. (default: "")
 253     :USER_DATA_ID: User Data to pass into the instance.
 254         (default: jenkins-init-script)
 255     :INSTANCE_CAP: Total number of instances of this type that is available for
 256         use at one time. When defined in clouds.cfg it defines the total for
 257         the entire cloud. (default: null)
 258     :SANDBOX_CAP: Total number of instances of this type that is available for
 259         use at one time. When defined in clouds.cfg it defines the total for
 260         the entire cloud. This applies to "sandbox" systems and overrides the
 261         INSTANCE_CAP setting. (default: null)
 262     :FLOATING_IP_POOL: Floating ip pool to use. (default: "")
 263     :SECURITY_GROUPS: Security group to use. (default: "default")
 264     :AVAILABILITY_ZONE: OpenStack availability zone to use. (default: "")
 265     :START_TIMEOUT: Number of milliseconds to wait for agent provisioning.
 266         (default: 600000)
 267     :KEY_PAIR_NAME: SSH Public Key Pair to use for authentication.
 268         (default: jenkins-ssh)
 269     :NUM_EXECUTORS: Number of executors to enable for the instance.
 270         (default: 1)
 271     :JVM_OPTIONS: JVM Options to pass to Java. (default: null)
 272     :FS_ROOT: File system root for the workspace. (default: "/w")
 273     :NODE_PROPERTIES: Node properties. (default: null)
 274     :RETENTION_TIME: Number of minutes to wait for an idle minion before
 275         removing it from the system. If set to -1, the minion will stick around
 276         forever. (default: 0)
 277     :CONNECTION_TYPE: The connection type for Jenkins to connect to the build
 278         minion. Valid options: JNLP, SSH. (default: "SSH")
 279     :CONFIG_TYPE: Configuration drive. (default: null)
 280
 281 For a live example see the OpenDaylight project jenkins-config directory.
 282 https://github.com/opendaylight/releng-builder/tree/master/jenkins-config
 283
 284 Troubleshooting
 285 ^^^^^^^^^^^^^^^
 286
 287 :Cloud Configuration:
 288
 289     The directory ``groovy-inserts`` contains the groovy script output used by
 290     Jenkins to push the cloud configuration. In the event of a job failure use
 291     this file to debug.
 292
 293
 294  .. _lf-global-jjb-jenkins-cfg-verify:
 295
 296 Jenkins Configuration Verify
 297 ----------------------------
 298
 299 Jenkins job to verify the Global Jenkins configuration.
 300
 301 Requires the ``clouds-yaml`` file to be setup on the Jenkins host.
 302
 303 :Template names:
 304
 305     - {project-name}-jenkins-cfg-verify
 306     - gerrit-jenkins-cfg-verify
 307     - github-jenkins-cfg-verify
 308
 309 :Optional parameters:
 310
 311     :branch: Git branch to build against. (default: master)
 312     :git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
 313
 314 This job is not part of the "{project-name}-ci-jobs" group and requires
 315 separate configuration.
 316
 317 Example:
 318
 319 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/jenkins-cfg-verify.yaml
 320    :language: yaml
 321
 322
 323 .. _jenkins-sandbox-cleanup:
 324
 325 Jenkins Sandbox Cleanup
 326 -----------------------
 327
 328 Cleanup Jenkins Sandbox of jobs and views periodically.
 329
 330 :Template names:
 331
 332     - {project-name}-jenkins-sandbox-cleanup
 333     - gerrit-jenkins-sandbox-cleanup
 334     - github-jenkins-sandbox-cleanup
 335
 336 :Comment Trigger: NONE
 337
 338 :Required parameters:
 339
 340     :build-node: The node to run build on.
 341     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
 342         in defaults.yaml)
 343
 344 :Optional parameters:
 345
 346     :cron: Schedule to run job. (default: '0 8 * * 6')
 347
 348
 349 .. _jjb-deploy:
 350
 351 JJB Deploy Job
 352 --------------
 353
 354 Deploy jobs to jenkins-sandbox system via code review comment.
 355
 356 This job checks out the current code review patch and then runs a
 357 ``jenkins-jobs update`` to push a patch defined by the comment.
 358
 359 :Template names:
 360
 361     - {project-name}-jjb-deploy-job
 362     - gerrit-jjb-deploy-job
 363     - github-jjb-deploy-job
 364
 365 :Comment Trigger: jjb-deploy JOB_NAME
 366
 367     .. note::
 368
 369         The JJB Deploy Job is a manual job and triggers via Gerrit comment
 370         which starts with the ``jjb-deploy`` keyword.
 371
 372         Example of a valid command in Gerrit comment that triggers the job:
 373
 374         ``jjb-deploy builder-jjb-*``
 375
 376         Example of a invalid command in Gerrit comment that would _not_ trigger
 377         the job:
 378
 379         ``Update the job. jjb-deploy builder-jjb-*``
 380
 381         JOB_NAME can include the ``*`` wildcard character to push jobs matching
 382         the pattern. For example ``jjb-deploy builder-jjb-*`` will push all
 383         builder-jjb-* jobs to the sandbox system.
 384
 385 :Required parameters:
 386
 387     :build-node: The node to run build on.
 388     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
 389         in defaults.yaml)
 390
 391 :Optional parameters:
 392
 393     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 394     :gerrit_jjb_deploy_job_triggers: Override Gerrit Triggers.
 395
 396
 397 .. _jjb-merge:
 398
 399 JJB Merge
 400 ---------
 401
 402 Runs ``jenkins-jobs update`` to update production job configuration
 403
 404 :Template Names:
 405     - {project-name}-jjb-merge
 406     - gerrit-jjb-merge
 407     - github-jjb-merge
 408
 409 :Comment Trigger: remerge
 410
 411 :Required parameters:
 412
 413     :build-node: The node to run build on.
 414     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
 415         in defaults.yaml)
 416
 417 :Optional parameters:
 418
 419     :branch: Git branch to fetch for the build. (default: master)
 420     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 421     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 422     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 423     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
 424     :jjb-workers: Number of threads to run **update** with. Set to 0 by default
 425         which will use the number of available CPU cores. (default: 0)
 426     :jjb-version: JJB version to install. (default: see job-template)
 427     :stream: Keyword that represents a release code-name.
 428         Often the same as the branch. (default: master)
 429     :submodule-recursive: Whether to checkout submodules recursively.
 430         (default: true)
 431     :submodule-timeout: Timeout (in minutes) for checkout operation.
 432         (default: 10)
 433     :submodule-disable: Disable submodule checkout operation.
 434         (default: false)
 435
 436     :gerrit_merge_triggers: Override Gerrit Triggers.
 437     :gerrit_trigger_file_paths: Override file paths to filter which file
 438         modifications will trigger a build.
 439         (default defined by lf_jjb_common)
 440
 441
 442 .. _jjb-verify:
 443
 444 JJB Verify
 445 ----------
 446
 447 Runs ``jenkins-jobs test`` to verify JJB syntax. Optionally verifies
 448 build-node labels used in templates and job definitions.
 449
 450 :Template Names:
 451     - {project-name}-jjb-verify
 452     - gerrit-jjb-verify
 453     - github-jjb-verify
 454
 455 :Comment Trigger: recheck|reverify
 456
 457 :Required parameters:
 458
 459     :build-node: The node to run build on.
 460     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
 461         in defaults.yaml)
 462
 463 :Optional parameters:
 464
 465     :branch: Git branch to fetch for the build. (default: master)
 466     :build-concurrent: Set to ``true`` to allow this job to run jobs
 467         simultaneously. (default: true)
 468     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 469     :build-node-label-check: Whether to check build-node labels in jobs
 470         against node names in cloud config files (default: false)
 471     :build-node-label-list: Space-separated list of external build-node
 472         labels not present in cloud config files (default: "")
 473     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 474     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 475     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
 476     :jjb-version: JJB version to install. (default: see job-template)
 477     :stream: Keyword that represents a release code-name.
 478         Often the same as the branch. (default: master)
 479     :submodule-recursive: Set to ``true`` to checkout submodules recursively.
 480         (default: true)
 481     :submodule-timeout: Timeout (in minutes) for checkout operation.
 482         (default: 10)
 483     :submodule-disable: Disable submodule checkout operation.
 484         (default: false)
 485     :throttle_categories: List of categories to throttle by.
 486     :throttle-enabled: Set to ``true`` to enable throttling on the job.
 487         (default: true)
 488     :throttle-max-per-node: Max jobs to run on the same node. (default: 1)
 489     :throttle-max-total: Max jobs to run across the entire project. - 0
 490         means 'unlimited' (default: 0)
 491     :throttle-option: Throttle by the project or by list of categories
 492         defined in the throttle plugin configuration. (options: 'project',
 493         'category'; default: project)
 494
 495     :gerrit_verify_triggers: Override Gerrit Triggers.
 496     :gerrit_trigger_file_paths: Override file paths to filter which file
 497         modifications will trigger a build.
 498         (default defined by lf_jjb_common)
 499
 500 .. _jjb-verify-upstream-gjjb:
 501
 502 JJB Verify Upstream Global JJB
 503 ------------------------------
 504
 505 Runs ``jenkins-jobs test`` to verify JJB syntax for upstream global-jjb
 506 patches. This job is useful to notify upstream that they may be breaking
 507 project level jobs.
 508
 509 :Template Names:
 510     - {project-name}-jjb-verify-upstream-gjjb
 511     - gerrit-jjb-verify-upstream-gjjb
 512     - github-jjb-verify-upstream-gjjb
 513
 514 :Comment Trigger: recheck|reverify
 515
 516 :Required parameters:
 517
 518     :build-node: The node to run build on.
 519     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
 520         in defaults.yaml)
 521
 522 :Optional parameters:
 523
 524     :branch: Git branch to fetch for the build. (default: master)
 525     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 526     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 527     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 528     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
 529     :jjb-version: JJB version to install. (default: see job-template)
 530     :stream: Keyword that represents a release code-name.
 531         Often the same as the branch. (default: master)
 532
 533 .. _info-yaml-verify:
 534
 535 Info YAML Verify
 536 ----------------
 537
 538 This job verifies that ``INFO.yaml`` file changes follow the schema defined in
 539 `lfit/releng-global-jjb/schema/info-schema.yaml`.
 540
 541 The ``INFO.yaml`` file changes must be independent of any other files changes.
 542
 543 :Template Names:
 544     - {project-name}-info-yaml-verify
 545     - gerrit-info-yaml-verify
 546     - github-info-yaml-verify
 547
 548 :Required parameters:
 549
 550     :build-node: The node to run build on.
 551     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
 552         in defaults.yaml)
 553
 554 :Optional parameters:
 555
 556     :branch: Git branch to fetch for the build. (default: master)
 557     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 558     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 559     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 560     :stream: Keyword that represents a release code-name.
 561         Often the same as the branch. (default: master)
 562     :submodule-recursive: Whether to checkout submodules recursively.
 563         (default: true)
 564     :submodule-timeout: Timeout (in minutes) for checkout operation.
 565         (default: 10)
 566     :submodule-disable: Disable submodule checkout operation.
 567         (default: false)
 568
 569     :gerrit_verify_triggers: Override Gerrit Triggers.
 570
 571 .. _lf_pipelines_verify:
 572
 573 LF Pipelines Verify
 574 -------------------
 575
 576 Verify job for the LF RelEng pipeline library.
 577
 578 Requires the Pipelines plugins installed. This job will look for a Gerrit
 579 system named "lf-releng" (mapped to https://gerrit.linuxfoundation.org/infra/),
 580 and pull in the Jenkinsfile in the root directory of the repo.
 581
 582 :Template Names:
 583     - lf-pipelines-verify
 584
 585 :Comment Trigger: recheck|reverify
 586
 587 .. _license-checker:
 588
 589 License Checker
 590 ---------------
 591
 592 Job to scan projects for files missing license headers.
 593
 594 :Template Names:
 595     - {project-name}-license-check
 596     - gerrit-license-check
 597     - github-license-check
 598
 599 :Optional parameters:
 600
 601     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 602     :file-patterns: Space-separated list of file patterns to scan.
 603         (default: \*.go \*.groovy \*.java \*.py \*.sh)
 604     :spdx-disable: Disable the SPDX-Identifier checker. (default: false)
 605     :lhc-version: Version of LHC to use. (default: 0.2.0)
 606     :license-exclude-paths: Comma-separated list of paths to exclude from the
 607         license checker. Matches the paths defined here using a contains rule,
 608         we recommend you to configure as precisely as possible. For example
 609         a path of '/src/generated/' will search as '**/src/generated/**'.
 610         Example: org/opendaylight/yang/gen,protobuff/messages
 611         (default: '')
 612     :licenses-allowed: Comma-separated list of allowed licenses.
 613         (default: Apache-2.0,EPL-1.0,MIT)
 614     :project-pattern: The ANT based pattern for Gerrit Trigger to choose which
 615         projects to trigger job against. (default: '**')
 616
 617 .. _gjjb-openstack-cron:
 618
 619 OpenStack Cron
 620 --------------
 621
 622 Cron job that runs on a schedule to perform periodic tasks against OpenStack.
 623
 624 This job requires a Config File Provider file named ``clouds-yaml`` available
 625 containing the credentials for the cloud.
 626
 627 :Template Names:
 628     - {project-name}-openstack-cron
 629     - gerrit-openstack-cron
 630     - github-openstack-cron
 631
 632 :Required parameters:
 633
 634     :build-node: The node to run build on.
 635     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
 636         in defaults.yaml)
 637     :jenkins-urls: URLs to Jenkins systems to check for active builds.
 638
 639 :Optional parameters:
 640
 641     :branch: Git branch to fetch for the build. (default: master)
 642     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 643     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 644     :cron: Time when the packer image should be rebuilt (default: @hourly)
 645     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 646     :openstack-cloud: OS_CLOUD setting to pass to openstack client.
 647         (default: vex)
 648     :openstack-image-cleanup: Set ``true`` to run the image cleanup script.
 649         (default: true)
 650     :openstack-image-cleanup-age: Age in days of image before marking it for
 651         removal. (default: 30)
 652     :openstack-image-protect: Set ``true`` to run the image protect script.
 653         (default: true)
 654     :openstack-server-cleanup: Set ``true`` to run the server cleanup script.
 655         (default: true)
 656     :openstack-stack-cleanup: Set ``true`` to run the stack cleanup script.
 657         (default: true)
 658     :openstack-volume-cleanup: Set ``true`` to run the volume cleanup script.
 659         (default: true)
 660     :stream: Keyword that represents a release code-name.
 661         Often the same as the branch. (default: master)
 662     :submodule-recursive: Whether to checkout submodules recursively.
 663         (default: true)
 664     :submodule-timeout: Timeout (in minutes) for checkout operation.
 665         (default: 10)
 666     :submodule-disable: Disable submodule checkout operation.
 667         (default: false)
 668
 669 Minimal Example:
 670
 671 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-cron-minimal.yaml
 672
 673 Full Example:
 674
 675 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-cron-full.yaml
 676
 677 .. _gjjb-openstack-update-cloud-image:
 678
 679 OpenStack Update Cloud Image
 680 ----------------------------
 681
 682 This job finds and updates OpenStack cloud images on the ci-management source
 683 repository.
 684
 685 This job functions in 2 ways:
 686
 687 1. When triggered via packer-merge job, updates the image created by the job.
 688 2. When triggered manually or via cron, updates all images.
 689
 690 When triggered through an upstream packer merge job, this generates a change
 691 request for the new image built.
 692
 693 When triggered manually, this job finds the latest images on OpenStack cloud
 694 and compares them with the images in use in the source ci-management source
 695 repository. If the compared images have newer time stamps are **all** updated
 696 through a change request.
 697
 698 This job requires a Jenkins configuration merge and verify job setup and
 699 working on Jenkins.
 700
 701 :Template Names:
 702     - {project-name}-openstack-update-cloud-image
 703     - gerrit-openstack-update-cloud-image
 704     - github-openstack-update-cloud-image
 705
 706 :Required parameters:
 707
 708     :build-node: The node to run build on.
 709     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
 710         in defaults.yaml)
 711     :new-image-name: Name of new image name passed from packer merge job or
 712         set to 'all' to update all images. (default: all)
 713
 714 :Optional parameters:
 715
 716     :branch: Git branch to fetch for the build. (default: master)
 717     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 718     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 719     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 720     :openstack-cloud: OS_CLOUD setting to pass to openstack client.
 721         (default: vex)
 722     :stream: Keyword that represents a release code-name.
 723         Often the same as the branch. (default: master)
 724     :submodule-recursive: Whether to checkout submodules recursively.
 725         (default: true)
 726     :submodule-timeout: Timeout (in minutes) for checkout operation.
 727         (default: 10)
 728     :submodule-disable: Disable submodule checkout operation.
 729         (default: false)
 730     :update-cloud-image: Submit a change request to update new built cloud
 731         image to Jenkins. (default: false)
 732
 733 Minimal Example:
 734
 735 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-update-cloud-image-minimal.yaml
 736
 737 Full Example:
 738
 739 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-update-cloud-image-full.yaml
 740
 741
 742 .. _gjjb-packer-merge:
 743
 744 Packer Merge
 745 ------------
 746
 747 Packer Merge job runs `packer build` to build system images in the cloud.
 748
 749 This job requires a Config File Provider file named ``ansible-cfg`` created
 750 on Jenkins. The file can include ansible host configuration required for the
 751 environment.
 752
 753 :Template Names:
 754     - {project-name}-packer-merge-{platforms}-{templates}
 755     - gerrit-packer-merge
 756     - github-packer-merge
 757
 758 :Comment Trigger: remerge
 759
 760 :Required parameters:
 761
 762     :build-node: The node to run build on.
 763     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
 764         in defaults.yaml)
 765     :mvn-settings: The name of settings file containing credentials for
 766         the project.
 767     :platforms: Platform or distribution to build. Typically json file
 768         found in the packer/vars directory. (Example: centos-7)
 769     :templates: System template to build. Typically a yaml file or shell script
 770         found in the packer/provision directory. (Example: docker)
 771
 772 :Optional parameters:
 773
 774     :cron: Time when the packer image should be rebuilt (default: @monthly)
 775     :branch: Git branch to fetch for the build. (default: master)
 776     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 777     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 778     :gerrit_verify_triggers: Override Gerrit Triggers.
 779     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 780     :openstack: Packer template uses an OpenStack builder (default: true).
 781     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
 782         (default: vex).
 783     :packer-cloud-settings: Name of settings file containing credentials
 784         for the cloud that packer will build on. (default: packer-cloud-env)
 785     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 786     :stream: Keyword that represents a release code-name.
 787         Often the same as the branch. (default: master)
 788     :submodule-recursive: Whether to checkout submodules recursively.
 789         (default: true)
 790     :submodule-timeout: Timeout (in minutes) for checkout operation.
 791         (default: 10)
 792     :submodule-disable: Disable submodule checkout operation.
 793         (default: false)
 794     :update-cloud-image: Submit a change request to update newly built cloud
 795         image to Jenkins. (default: false)
 796
 797
 798 Test an in-progress patch
 799 ^^^^^^^^^^^^^^^^^^^^^^^^^
 800
 801 To test an in-progress patch from a GitHub Pull Request, upload this
 802 job to the :doc:`Jenkins Sandbox <lfdocs:jenkins-sandbox>`. Then when manually
 803 building the job, replace the GERRIT_REFSPEC parameter with the GitHub Pull
 804 Request number of the patch you would like to test.
 805
 806 Example GitHub:
 807
 808 .. code-block:: none
 809
 810    GERRIT_REFSPEC: origin/pr/49/merge
 811
 812
 813 .. _gjjb-packer-verify:
 814
 815 Packer Verify
 816 -------------
 817
 818 Packer Verify job runs ``packer validate`` to verify packer configuration. The
 819 verify job checks superficial syntax of the template and other files. It does
 820 not attempt to build an image, and cannot detect all possible build issues.
 821
 822 This job requires a Config File Provider file named ``ansible-cfg`` created
 823 on Jenkins. The file can include ansible host configuration required for the
 824 environment.
 825
 826 :Template Names:
 827     - {project-name}-packer-verify
 828     - gerrit-packer-verify
 829     - github-packer-verify
 830
 831 :Comment Trigger: recheck|reverify
 832
 833 :Required parameters:
 834
 835     :build-node: The node to run build on.
 836     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
 837         in defaults.yaml)
 838     :mvn-settings: The name of settings file containing credentials for
 839         the project.
 840
 841 :Optional parameters:
 842
 843     :branch: Git branch to fetch for the build. (default: master)
 844     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 845     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 846     :gerrit_trigger_file_paths: Override file paths to filter which file
 847         modifications will trigger a build.
 848     :gerrit_verify_triggers: Override Gerrit Triggers.
 849     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 850     :openstack: Packer template uses an OpenStack builder (default: true).
 851     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
 852         (default: vex).
 853     :packer-cloud-settings: Name of settings file containing credentials
 854         for the cloud that packer will build on. (default: packer-cloud-env)
 855     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 856     :stream: Keyword that represents a release code-name.
 857         Often the same as the branch. (default: master)
 858     :submodule-recursive: Whether to checkout submodules recursively.
 859         (default: true)
 860     :submodule-timeout: Timeout (in minutes) for checkout operation.
 861         (default: 10)
 862     :submodule-disable: Disable submodule checkout operation.
 863         (default: false)
 864
 865
 866 .. _gjjb-packer-verify-build:
 867
 868 Packer Verify Build
 869 -------------------
 870
 871 Packer Verify Build job is essentially the same as the
 872 :ref:`Packer Merge job <gjjb-packer-merge>`. Trigger using its keyword,
 873 and will build a useable image. If the last patch set before a merge has a
 874 successful verify build, the merge job will not build the same image.
 875
 876 :Template Names:
 877     - {project-name}-packer-verify-build-{platforms}-{templates}
 878     - gerrit-packer-verify-build
 879     - github-packer-verify-build
 880
 881 :Comment Trigger: verify-build|packer-build
 882
 883 :Required parameters:
 884
 885     :build-node: The node to run build on.
 886     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured in
 887         defaults.yaml)
 888     :mvn-settings: The name of settings file containing credentials for
 889         the project.
 890     :platforms: Platform or distribution to build. Typically json file
 891         found in the packer/vars directory. (Example: centos-7)
 892     :templates: System template to build. Typically a yaml file or shell script
 893         found in the packer/provision directory. (Example: docker)
 894
 895 :Optional parameters:
 896
 897     :branch: Git branch to fetch for the build. (default: master)
 898     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 899     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 900     :gerrit_trigger_file_paths: Override file paths to filter which file
 901         modifications will trigger a build.
 902     :gerrit_verify_triggers: Override Gerrit Triggers.
 903     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 904     :openstack: Packer template uses an OpenStack builder (default: true).
 905     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
 906         (default: vex).
 907     :packer-cloud-settings: Name of settings file containing credentials
 908         for the cloud that packer will build on. (default: packer-cloud-env)
 909     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 910     :stream: Keyword that represents a release code-name.
 911         Often the same as the branch. (default: master)
 912     :submodule-recursive: Whether to checkout submodules recursively.
 913         (default: true)
 914     :submodule-timeout: Timeout (in minutes) for checkout operation.
 915         (default: 10)
 916     :submodule-disable: Disable submodule checkout operation.
 917         (default: false)
 918     :update-cloud-image: Submit a change request to update new built cloud
 919         image to Jenkins. (default: false)
 920
 921
 922 Puppet Verify
 923 -------------
 924
 925 Runs puppet-lint in the ``puppet-dir`` directory. Since ``puppet-lint`` runs
 926 recursively, we recommend to run from the base directory.
 927
 928 :Template Names:
 929
 930     - {project-name}-puppet-verify
 931     - gerrit-puppet-verify
 932     - github-puppet-verify
 933
 934 :Comment Trigger: recheck|reverify
 935
 936 :Required Parameters:
 937
 938     :build-node: The node to run build on.
 939     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 940         in defaults.yaml)
 941
 942 :Optional Parameters:
 943
 944     :branch: The branch to build against. (default: master)
 945     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 946     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 947     :gerrit_trigger_file_paths: Override file paths which used to filter which
 948         file modifications will trigger a build. Refer to JJB documentation for
 949         "file-path" details.
 950         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
 951     :git-url: URL clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
 952     :puppet-dir: Directory containing the project's puppet module(s) relative
 953         to the workspace.
 954         (default: '')
 955     :puppet-lint-version: Version of puppet-lint to use for testing.
 956         (default: 2.3.6)
 957     :stream: Keyword representing a release code-name.
 958         Often the same as the branch. (default: master)
 959     :submodule-recursive: Whether to checkout submodules recursively.
 960         (default: true)
 961     :submodule-timeout: Timeout (in minutes) for checkout operation.
 962         (default: 10)
 963     :submodule-disable: Disable submodule checkout operation.
 964         (default: false)
 965
 966
 967 Sonar
 968 -----
 969
 970 Runs the Jenkins SonarQube Scanner plug-in to analyze code for bugs,
 971 code smells and security vulnerabilities, and to upload the result
 972 (possibly including code-coverage statistics) to a SonarQube server
 973 or to SonarCloud.io.
 974
 975 Requires ``SonarQube Scanner for Jenkins``
 976
 977 Configuration must set one of the parameters ``sonar-project-file`` or
 978 ``sonar-properties``; they cannot both be empty.
 979
 980 Plug-in configurations
 981     Manage Jenkins --> Configure System --> SonarQube servers
 982         - Name: Sonar (fixed)
 983         - Server URL: https://sonar.server.org/ or https://sonarcloud.io
 984         - Server authentication token: none for local, API token (saved as a
 985           "secret text" credential) for Sonarcloud
 986
 987     Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
 988         - Name: SonarQube Scanner (fixed)
 989         - Install automatically
 990         - Select latest version
 991
 992 .. note::
 993
 994     Optionally, set Sonar properties directly in the job definition by
 995     setting the sonar-project-file to ``""`` and adding all properties under
 996     ``sonar-properties``.
 997
 998 :Template Names:
 999
1000     - {project-name}-sonar
1001     - gerrit-sonar
1002     - github-sonar
1003
1004 :Optional Parameters:
1005     :sonar-task: Sonar task to run. (default: "")
1006     :sonar-project-file: The filename for the project's properties
1007         (default: "sonar-project.properties")
1008     :sonar-properties: Sonar configuration properties. (default: "")
1009     :sonar-java-opts: JVM options. (default: "")
1010     :sonar-additional-args: Additional command line arguments. (default: "")
1011     :sonarcloud-java-version: Version of Java to run the Sonar scan. (default: "openjdk13")
1012
1013
1014 Sonar with Prescan
1015 ------------------
1016
1017 The same as the Sonar job above, except the caller also defines a builder
1018 called ``lf-sonar-prescan``, in which they can put any builders that they want
1019 to run before the Sonar scan.
1020
1021 .. code-block:: yaml
1022
1023    - builder:
1024        name: lf-sonar-prescan
1025        builders:
1026          - shell: "# Pre-scan shell script"
1027
1028 :Template Names:
1029
1030     - {project-name}-sonar-prescan
1031     - gerrit-sonar-prescan
1032     - github-sonar-prescan
1033
1034 :Required Parameters:
1035     :lf-sonar-prescan: A builder that will run before the Sonar scan.
1036
1037 :Optional Parameters:
1038     :sonar-task: Sonar task to run. (default: "")
1039     :sonar-project-file: The filename for the project's properties
1040         (default: "sonar-project.properties")
1041     :sonar-properties: Sonar configuration properties. (default: "")
1042     :sonar-java-opts: JVM options. (default: "")
1043     :sonar-additional-args: Additional command line arguments. (default: "")
1044     :sonarcloud-java-version: Version of Java to run the Sonar scan. (default: "openjdk13")
1045
1046
1047 Sonar with Prescan Script
1048 -------------------------
1049
1050 The same as the Sonar job above, except the caller must supply a shell script
1051 to run before the Sonar scan. This is commonly used to install prerequisites,
1052 build the project, execute unit tests and generate a code-coverage report.
1053
1054 :Template Names:
1055
1056     - {project-name}-sonar-prescan-script
1057     - gerrit-sonar-prescan-script
1058     - github-sonar-prescan-script
1059
1060 :Required Parameters:
1061     :sonar-prescan-script: A shell script that will run before the Sonar scan.
1062
1063 :Optional Parameters:
1064     :sonar-task: Sonar task to run. (default: "")
1065     :sonar-project-file: The filename for the project's properties.
1066         (default: "sonar-project.properties")
1067     :sonar-properties: Sonar configuration properties. (default: "")
1068     :sonar-java-opts: JVM options. (default: "")
1069     :sonar-additional-args: Additional command line arguments. (default: "")
1070     :sonarcloud-java-version: Version of Java to run the Sonar scan. (default: "openjdk13")