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. This should only be
 111 loaded once, as "ci-management-gerrit-branch-lock" (or "ci-management"
 112 equivalent). That job will process lock/unlock requests for all projects and
 113 all branches.
 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
 128         should be configured 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 the job group is being used.
 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 Global Environment Variables are managed 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 and is
 203 currently the only cloud plugin supported.
 204
 205 OpenStack Cloud plugin version supported:
 206
 207 * 2.30 - 2.34
 208 * 2.35 - 2.37
 209
 210 Cloud configuration are managed via a directory structure in ci-management as
 211 follows:
 212
 213 - jenkins-config/clouds/openstack/
 214 - jenkins-config/clouds/openstack/cattle/cloud.cfg
 215 - jenkins-config/clouds/openstack/cattle/centos7-builder-2c-2g.cfg
 216 - jenkins-config/clouds/openstack/cattle/centos7-builder-4c-4g.cfg
 217 - jenkins-config/clouds/openstack/cattle/centos7-docker-4c-4g.cfg
 218
 219 The directory name inside of the "openstack" directory is used as the name of
 220 the cloud configuration. In this case "cattle" is being used as 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        In the case of template definitions of a parameter below is not passed
 244        the one defined in default clouds will be inherited.
 245
 246     :IMAGE_NAME: The image name to use for this template.
 247         (required)
 248     :HARDWARE_ID: OpenStack flavor to use. (required)
 249
 250     :LABELS: Labels to assign to the vm. (default: FILE_NAME)
 251     :NETWORK_ID: OpenStack network to use. (default: "")
 252     :USER_DATA_ID: User Data to pass into the instance.
 253         (default: jenkins-init-script)
 254     :INSTANCE_CAP: Total number of instances of this type that can be launched
 255         at one time. When defined in clouds.cfg it defines the total for the
 256         entire cloud. (default: null)
 257     :SANDBOX_CAP: Total number of instances of this type that can be launched
 258         at one time. When defined in clouds.cfg it defines the total for the
 259         entire cloud. This applies to "sandbox" systems and overrides the
 260         INSTANCE_CAP setting. (default: null)
 261     :FLOATING_IP_POOL: Floating ip pool to use. (default: "")
 262     :SECURITY_GROUPS: Security group to use. (default: "default")
 263     :AVAILABILITY_ZONE: OpenStack availability zone to use. (default: "")
 264     :START_TIMEOUT: Number of milliseconds to wait for the agent to be
 265         provisioned and connected. (default: 600000)
 266     :KEY_PAIR_NAME: SSH Public Key Pair to use for authentication.
 267         (default: jenkins)
 268     :NUM_EXECUTORS: Number of executors to enable for the instance.
 269         (default: 1)
 270     :JVM_OPTIONS: JVM Options to pass to Java. (default: "")
 271     :FS_ROOT: File system root for the workspace. (default: "/w")
 272     :RETENTION_TIME: Number of minutes to wait for an idle slave to be used
 273         again before it's removed. If set to -1, the slave will be kept
 274         forever. (default: 0)
 275     :CONNECTION_TYPE: The connection type for Jenkins to connect to the build
 276         minion. Valid options: JNLP, SSH. (default: "SSH")
 277
 278 For a live example see the OpenDaylight project jenkins-config directory.
 279 https://github.com/opendaylight/releng-builder/tree/master/jenkins-config
 280
 281 Troubleshooting
 282 ^^^^^^^^^^^^^^^
 283
 284 :Cloud Configuration:
 285
 286     The directory ``groovy-inserts`` contains the groovy script output that is
 287     used to push to Jenkins. In the event of a job failure this file can be
 288     inspected.
 289
 290  .. _lf-global-jjb-jenkins-cfg-verify:
 291
 292 Jenkins Configuration Verify
 293 ----------------------------
 294
 295 Jenkins job to verify the Global Jenkins configuration.
 296
 297 Requires the ``clouds-yaml`` file to be setup on the Jenkins host.
 298
 299 :Template names:
 300
 301     - {project-name}-jenkins-cfg-verify
 302     - gerrit-jenkins-cfg-verify
 303     - github-jenkins-cfg-verify
 304
 305 :Optional parameters:
 306
 307     :branch: Git branch to build against. (default: master)
 308     :git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
 309
 310 This job is not part of the "{project-name}-ci-jobs" group. It must be called
 311 explicitly.
 312
 313 Example:
 314
 315 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/jenkins-cfg-verify.yaml
 316    :language: yaml
 317
 318
 319 .. _jenkins-sandbox-cleanup:
 320
 321 Jenkins Sandbox Cleanup
 322 -----------------------
 323
 324 Cleanup Jenkins Sandbox of jobs and views periodically.
 325
 326 :Template names:
 327
 328     - {project-name}-jenkins-sandbox-cleanup
 329     - gerrit-jenkins-sandbox-cleanup
 330     - github-jenkins-sandbox-cleanup
 331
 332 :Comment Trigger: NONE
 333
 334 :Required parameters:
 335
 336     :build-node: The node to run build on.
 337     :jenkins-ssh-credential: Credential to use for SSH. (Generally
 338         should be configured in defaults.yaml)
 339
 340 :Optional parameters:
 341
 342     :cron: Schedule to run job. (default: '0 8 * * 6')
 343
 344
 345 .. _jjb-deploy:
 346
 347 JJB Deploy Job
 348 --------------
 349
 350 Deploy jobs to jenkins-sandbox system via code review comment.
 351
 352 This job checks out the current code review patch and then runs a
 353 ``jenkins-jobs update`` to push a patch defined by the comment.
 354
 355 :Template names:
 356
 357     - {project-name}-jjb-deploy-job
 358     - gerrit-jjb-deploy-job
 359     - github-jjb-deploy-job
 360
 361 :Comment Trigger: jjb-deploy JOB_NAME
 362
 363     .. note::
 364
 365        The JJB Deploy Job is configured to trigger only if the Gerrit comment
 366        starts with the `jjb-deploy` keyword.
 367
 368        Example of a valid command in Gerrit comment that triggers the job:
 369
 370        ``jjb-deploy builder-jjb-*``
 371
 372        Example of a invalid command in Gerrit comment that would _not_ trigger
 373        the job:
 374
 375        ``Update the job. jjb-deploy builder-jjb-*``
 376
 377        JOB_NAME can include the * wildcard character to push multiple jobs
 378        matching the pattern. For example ``jjb-deploy builder-jjb-*`` will push
 379        all builder-jjb-* jobs to the sandbox system.
 380
 381 :Required parameters:
 382
 383     :build-node: The node to run build on.
 384     :jenkins-ssh-credential: Credential to use for SSH. (Generally
 385         should be configured in defaults.yaml)
 386
 387 :Optional parameters:
 388
 389     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 390     :gerrit_jjb_deploy_job_triggers: Override Gerrit Triggers.
 391
 392
 393 .. _jjb-merge:
 394
 395 JJB Merge
 396 ---------
 397
 398 Runs `jenkins-jobs update` to update production job configuration
 399
 400 :Template Names:
 401     - {project-name}-jjb-merge
 402     - gerrit-jjb-merge
 403     - github-jjb-merge
 404
 405 :Comment Trigger: remerge
 406
 407 :Required parameters:
 408
 409     :build-node: The node to run build on.
 410     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 411         be configured in defaults.yaml)
 412
 413 :Optional parameters:
 414
 415     :branch: Git branch to fetch for the build. (default: master)
 416     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 417     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 418     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 419     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
 420     :jjb-workers: Number of threads to run **update** with. Set to 0 by default
 421         which is equivalent to the number of available CPU cores. (default: 0)
 422     :jjb-version: JJB version to install. (default: see job-template)
 423     :stream: Keyword that can be used to represent a release code-name.
 424         Often the same as the branch. (default: master)
 425     :submodule-recursive: Whether to checkout submodules recursively.
 426         (default: true)
 427     :submodule-timeout: Timeout (in minutes) for checkout operation.
 428         (default: 10)
 429     :submodule-disable: Disable submodule checkout operation.
 430         (default: false)
 431
 432     :gerrit_merge_triggers: Override Gerrit Triggers.
 433     :gerrit_trigger_file_paths: Override file paths which can be used to
 434         filter which file modifications will trigger a build.
 435         (default defined by lf_jjb_common)
 436
 437
 438 .. _jjb-verify:
 439
 440 JJB Verify
 441 ----------
 442
 443 Runs `jenkins-jobs test` to validate JJB syntax
 444
 445 :Template Names:
 446     - {project-name}-jjb-verify
 447     - gerrit-jjb-verify
 448     - github-jjb-verify
 449
 450 :Comment Trigger: recheck|reverify
 451
 452 :Required parameters:
 453
 454     :build-node: The node to run build on.
 455     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 456         be configured in defaults.yaml)
 457
 458 :Optional parameters:
 459
 460     :branch: Git branch to fetch for the build. (default: master)
 461     :build-concurrent: Whether or not to allow this job to run multiple jobs
 462         simultaneously. (default: true)
 463     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 464     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 465     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 466     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
 467     :jjb-version: JJB version to install. (default: see job-template)
 468     :stream: Keyword that can be used to represent a release code-name.
 469         Often the same as the branch. (default: master)
 470     :submodule-recursive: Whether to checkout submodules recursively.
 471         (default: true)
 472     :submodule-timeout: Timeout (in minutes) for checkout operation.
 473         (default: 10)
 474     :submodule-disable: Disable submodule checkout operation.
 475         (default: false)
 476     :throttle_categories: List of categories to throttle by.
 477     :throttle-enabled: Whether or not to enable throttling on the job.
 478         (default: true)
 479     :throttle-max-per-node: Max jobs to run on the same node. (default: 1)
 480     :throttle-max-total: Max jobs to run across the entire project. - 0
 481         means 'unlimited' (default: 0)
 482     :throttle-option: Throttle by the project or by list of categories
 483         defined in the throttle plugin configuration. (options: 'project',
 484         'category'; default: project)
 485
 486     :gerrit_verify_triggers: Override Gerrit Triggers.
 487     :gerrit_trigger_file_paths: Override file paths which can be used to
 488         filter which file modifications will trigger a build.
 489         (default defined by lf_jjb_common)
 490
 491 .. _jjb-verify-upstream-gjjb:
 492
 493 JJB Verify Upstream Global JJB
 494 ------------------------------
 495
 496 Runs ``jenkins-jobs test`` to validate JJB syntax for upstream global-jjb
 497 patches. This job is useful to notify upstream that they may be breaking
 498 project level jobs.
 499
 500 :Template Names:
 501     - {project-name}-jjb-verify-upstream-gjjb
 502     - gerrit-jjb-verify-upstream-gjjb
 503
 504 :Comment Trigger: recheck|reverify
 505
 506 :Required parameters:
 507
 508     :build-node: The node to run build on.
 509     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 510         be configured in defaults.yaml)
 511
 512 :Optional parameters:
 513
 514     :branch: Git branch to fetch for the build. (default: master)
 515     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 516     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 517     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 518     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
 519     :jjb-version: JJB version to install. (default: see job-template)
 520     :stream: Keyword that can be used to represent a release code-name.
 521         Often the same as the branch. (default: master)
 522
 523 .. _info-yaml-verify:
 524
 525 Info YAML Verify
 526 ----------------
 527
 528 Info YAML Verify job validates that INFO.yaml file changes are kept isolated from
 529 other file changes. Verifies INFO.yaml files follow the schema defined in
 530 `lfit/releng-global-jjb/schema/info-schema.yaml`.
 531
 532 :Template Names:
 533     - {project-name}-info-yaml-verify
 534     - gerrit-info-yaml-verify
 535     - github-info-yaml-verify
 536
 537 :Required parameters:
 538
 539     :build-node: The node to run build on.
 540     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 541         be configured in defaults.yaml)
 542
 543 :Optional parameters:
 544
 545     :branch: Git branch to fetch for the build. (default: master)
 546     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 547     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 548     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 549     :stream: Keyword that can be used to represent a release code-name.
 550         Often the same as the branch. (default: master)
 551     :submodule-recursive: Whether to checkout submodules recursively.
 552         (default: true)
 553     :submodule-timeout: Timeout (in minutes) for checkout operation.
 554         (default: 10)
 555     :submodule-disable: Disable submodule checkout operation.
 556         (default: false)
 557
 558     :gerrit_verify_triggers: Override Gerrit Triggers.
 559
 560 .. _license-checker:
 561
 562 License Checker
 563 ---------------
 564
 565 Job to scan projects for files missing license headers.
 566
 567 :Template Names:
 568     - {project-name}-license-check
 569     - gerrit-license-check
 570     - github-license-check
 571
 572 :Optional parameters:
 573
 574     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 575     :file-patterns: Space-separated list of file patterns to scan.
 576         (default: \*.go \*.groovy \*.java \*.py \*.sh)
 577     :spdx-disable: Disable the SPDX-Identifier checker. (default: false)
 578     :lhc-version: Version of LHC to use. (default: 0.2.0)
 579     :license-exclude-paths: Comma-separated list of paths to exclude from the
 580         license checker. The paths used here will be matched using a contains
 581         rule so it is best to be as precise with the path as possible.
 582         For example a path of '/src/generated/' will be searched as
 583         '**/src/generated/**'.
 584         Example: org/opendaylight/yang/gen,protobuff/messages
 585         (default: '')
 586     :licenses-allowed: Comma-separated list of allowed licenses.
 587         (default: Apache-2.0,EPL-1.0,MIT)
 588     :project-pattern: The ANT based pattern for Gerrit Trigger to choose which
 589         projects to trigger job against. (default: '**')
 590
 591 .. _gjjb-openstack-cron:
 592
 593 OpenStack Cron
 594 --------------
 595
 596 Cron job that runs regularly to perform periodic tasks against OpenStack.
 597
 598 This job requires a Config File Provider file named ``clouds-yaml`` available
 599 containing the credentials for the cloud.
 600
 601 :Template Names:
 602     - {project-name}-openstack-cron
 603     - gerrit-openstack-cron
 604     - github-openstack-cron
 605
 606 :Required parameters:
 607
 608     :build-node: The node to run build on.
 609     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 610         be configured in defaults.yaml)
 611     :jenkins-urls: URLs to Jenkins systems to check for active builds.
 612
 613 :Optional parameters:
 614
 615     :branch: Git branch to fetch for the build. (default: master)
 616     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 617     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 618     :cron: Time when the packer image should be rebuilt (default: @hourly)
 619     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 620     :openstack-cloud: OS_CLOUD setting to pass to openstack client.
 621         (default: vex)
 622     :openstack-image-cleanup: Whether or not to run the image cleanup script.
 623         (default: true)
 624     :openstack-image-cleanup-age: Age in days of image before marking it for
 625         removal. (default: 30)
 626     :openstack-image-protect: Whether or not to run the image protect script.
 627         (default: true)
 628     :openstack-server-cleanup: Whether or not to run the server cleanup script.
 629         (default: true)
 630     :openstack-stack-cleanup: Whether or not to run the stack cleanup script.
 631         (default: true)
 632     :openstack-volume-cleanup: Whether or not to run the volume cleanup script.
 633         (default: true)
 634     :stream: Keyword that can be used to represent a release code-name.
 635         Often the same as the branch. (default: master)
 636     :submodule-recursive: Whether to checkout submodules recursively.
 637         (default: true)
 638     :submodule-timeout: Timeout (in minutes) for checkout operation.
 639         (default: 10)
 640     :submodule-disable: Disable submodule checkout operation.
 641         (default: false)
 642
 643 Minimal Example:
 644
 645 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-cron-minimal.yaml
 646
 647 Full Example:
 648
 649 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-cron-full.yaml
 650
 651 .. _gjjb-openstack-update-cloud-image:
 652
 653 OpenStack Update Cloud Image
 654 ----------------------------
 655
 656 This job finds and updates OpenStack cloud images on the ci-management source
 657 repository.
 658
 659 The job is triggered in two ways:
 660
 661 1. When packer merge job completes, the new image name created is passed
 662    down to the job.
 663 2. When the job is triggered manually to update all new images.
 664
 665 When the job is triggered through an upstream packer merge job, this only
 666 generates a change request for the new image built.
 667
 668 When the job is triggered manually, this job finds the latest images on
 669 OpenStack cloud and compares them with the images currently used in the source
 670 ci-management source repository. If the compared images have newer
 671 time stamps are **all** updated through a change request.
 672
 673 This job requires a Jenkins configuration merge and verify job setup and
 674 working on Jenkins.
 675
 676 :Template Names:
 677     - {project-name}-openstack-update-cloud-image
 678     - gerrit-openstack-update-cloud-image
 679     - github-openstack-update-cloud-image
 680
 681 :Required parameters:
 682
 683     :build-node: The node to run build on.
 684     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 685         be configured in defaults.yaml)
 686     :new-image-name: Name of new image name passed from packer merge job or
 687         set to 'all' to update all images. (default: all)
 688
 689 :Optional parameters:
 690
 691     :branch: Git branch to fetch for the build. (default: master)
 692     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 693     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 694     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 695     :openstack-cloud: OS_CLOUD setting to pass to openstack client.
 696         (default: vex)
 697     :stream: Keyword that can be used to represent a release code-name.
 698         Often the same as the branch. (default: master)
 699     :submodule-recursive: Whether to checkout submodules recursively.
 700         (default: true)
 701     :submodule-timeout: Timeout (in minutes) for checkout operation.
 702         (default: 10)
 703     :submodule-disable: Disable submodule checkout operation.
 704         (default: false)
 705     :update-cloud-image: Submit a change request to update new built cloud
 706         image to Jenkins. (default: false)
 707
 708 Minimal Example:
 709
 710 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-update-cloud-image-minimal.yaml
 711
 712 Full Example:
 713
 714 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-update-cloud-image-full.yaml
 715
 716
 717 .. _gjjb-packer-merge:
 718
 719 Packer Merge
 720 ------------
 721
 722 Packer Merge job runs `packer build` to build system images in the cloud.
 723
 724 :Template Names:
 725     - {project-name}-packer-merge-{platforms}-{templates}
 726     - gerrit-packer-merge
 727     - github-packer-merge
 728
 729 :Comment Trigger: remerge
 730
 731 :Required parameters:
 732
 733     :build-node: The node to run build on.
 734     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 735         be configured in defaults.yaml)
 736     :mvn-settings: The name of settings file containing credentials for
 737         the project.
 738     :platforms: Platform or distribution to build. Typically json file
 739         found in the packer/vars directory. (Example: centos)
 740     :template: System template to build. Typically shell script found in
 741         the packer/provision directory. (Example: java-builder)
 742
 743 :Optional parameters:
 744
 745     :cron: Time when the packer image should be rebuilt (default: @monthly)
 746     :branch: Git branch to fetch for the build. (default: master)
 747     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 748     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 749     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 750     :openstack: Packer template uses an OpenStack builder (default: true).
 751     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
 752         (default: vex).
 753     :packer-cloud-settings: Name of settings file containing credentials
 754         for the cloud that packer will build on. (default: packer-cloud-env)
 755     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 756     :stream: Keyword that can be used to represent a release code-name.
 757         Often the same as the branch. (default: master)
 758     :submodule-recursive: Whether to checkout submodules recursively.
 759         (default: true)
 760     :submodule-timeout: Timeout (in minutes) for checkout operation.
 761         (default: 10)
 762     :submodule-disable: Disable submodule checkout operation.
 763         (default: false)
 764
 765     :gerrit_verify_triggers: Override Gerrit Triggers.
 766     :update-cloud-image: Submit a change request to update new built cloud
 767         image to Jenkins. (default: false)
 768
 769
 770 Test an in-progress patch
 771 ^^^^^^^^^^^^^^^^^^^^^^^^^
 772
 773 To test an in-progress patch from a GitHub Pull Request. Upload this
 774 job to the :doc:`Jenkins Sandbox <lfdocs:jenkins-sandbox>`. Then when manually
 775 building the job replace the GERRIT_REFSPEC parameter with the GitHub Pull
 776 Request number of the patch you would like to test.
 777
 778 Example GitHub:
 779
 780 .. code-block:: none
 781
 782    GERRIT_REFSPEC: origin/pr/49/merge
 783
 784 .. _gjjb-packer-verify:
 785
 786 Packer Verify
 787 -------------
 788
 789 Packer Verify job runs `packer validate` to verify packer configuration.
 790
 791 :Template Names:
 792     - {project-name}-packer-verify
 793     - gerrit-packer-verify
 794     - github-packer-verify
 795
 796 :Comment Trigger: recheck|reverify
 797
 798 :Required parameters:
 799
 800     :build-node: The node to run build on.
 801     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 802         be configured in defaults.yaml)
 803     :mvn-settings: The name of settings file containing credentials for
 804         the project.
 805
 806 :Optional parameters:
 807
 808     :branch: Git branch to fetch for the build. (default: master)
 809     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 810     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 811     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 812     :openstack: Packer template uses an OpenStack builder (default: true).
 813     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
 814         (default: vex).
 815     :packer-cloud-settings: Name of settings file containing credentials
 816         for the cloud that packer will build on. (default: packer-cloud-env)
 817     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 818     :stream: Keyword that can be used to represent a release code-name.
 819         Often the same as the branch. (default: master)
 820     :submodule-recursive: Whether to checkout submodules recursively.
 821         (default: true)
 822     :submodule-timeout: Timeout (in minutes) for checkout operation.
 823         (default: 10)
 824     :submodule-disable: Disable submodule checkout operation.
 825         (default: false)
 826
 827     :gerrit_verify_triggers: Override Gerrit Triggers.
 828     :gerrit_trigger_file_paths: Override file paths which can be used to
 829         filter which file modifications will trigger a build.
 830
 831
 832 Puppet Verify
 833 -------------
 834
 835 Runs puppet-lint in the ``puppet-dir`` directory. puppet-lint runs recursively,
 836 the base directory is usually the best place to run from.
 837
 838 :Template Names:
 839
 840     - {project-name}-puppet-verify
 841     - gerrit-puppet-verify
 842     - github-puppet-verify
 843
 844 :Comment Trigger: recheck|reverify
 845
 846 :Required Parameters:
 847
 848     :build-node: The node to run build on.
 849     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 850         in defaults.yaml)
 851
 852 :Optional Parameters:
 853
 854     :branch: The branch to build against. (default: master)
 855     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 856     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 857     :gerrit_trigger_file_paths: Override file paths which used to filter which
 858         file modifications will trigger a build. Refer to JJB documentation for
 859         "file-path" details.
 860         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 861     :git-url: URL clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
 862     :puppet-dir: Directory containing the project's puppet module(s) relative
 863         to the workspace.
 864         (default: '')
 865     :puppet-lint-version: Version of puppet-lint to use for testing.
 866         (default: 2.3.6)
 867     :stream: Keyword representing a release code-name.
 868         Often the same as the branch. (default: master)
 869     :submodule-recursive: Whether to checkout submodules recursively.
 870         (default: true)
 871     :submodule-timeout: Timeout (in minutes) for checkout operation.
 872         (default: 10)
 873     :submodule-disable: Disable submodule checkout operation.
 874         (default: false)
 875
 876
 877 Sonar
 878 -----
 879
 880 Runs Jenkins Sonarqube plug-in to review for bugs, code smells,
 881 and security vulnerabilities.
 882
 883 Requires ``SonarQube Scanner for Jenkins``
 884
 885 Plug-in configurations
 886     Manage Jenkins --> Configure System --> SonarQube servers
 887         - Name: Sonar (fixed)
 888         - Server URL: https://sonar.server.org/ or https://sonarcloud.io
 889         - Server authentication token: none for local, API token (saved as a
 890           "secret text" credential) for Sonarcloud
 891
 892     Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
 893         - Name: SonarQube Scanner (fixed)
 894         - Install automatically
 895         - Select latest version
 896
 897 .. note:: Sonar properties can be set directly in the job definition by
 898    setting the sonar-project-file to ``""`` and adding all properties under
 899    ``sonar-properties``.
 900
 901 :Template Names:
 902
 903     - {project-name}-sonar
 904     - gerrit-sonar
 905     - github-sonar
 906
 907 :Optional Parameters:
 908     :sonar-task: Sonar task to run. (default: "")
 909     :sonar-project-file: The filename for the project's properties
 910         (default: "sonar-project.properties")
 911     :sonar-properties: Sonar configuration properties. (default: "")
 912     :sonar-java-opts: JVM options. (default: "")
 913     :sonar-additional-args: Additional command line arguments. (default: "")
 914
 915
 916 Sonar with Prescan
 917 ------------------
 918
 919 The same as the Sonar job above, except the caller also defines a builder
 920 called ``lf-sonar-prescan``, in which they can put any builders that they want
 921 to run prior to the Sonar scan.
 922
 923 .. code-block:: yaml
 924
 925    - builder:
 926        name: lf-sonar-prescan
 927        builders:
 928          - shell: "# Pre-scan shell script"
 929
 930 :Template Names:
 931
 932     - {project-name}-sonar-prescan
 933     - gerrit-sonar-prescan
 934     - github-sonar-prescan
 935
 936 :Required Parameters:
 937     :lf-sonar-prescan: A builder that will run prior to the Sonar scan.
 938
 939 :Optional Parameters:
 940     :sonar-task: Sonar task to run. (default: "")
 941     :sonar-project-file: The filename for the project's properties
 942         (default: "sonar-project.properties")
 943     :sonar-properties: Sonar configuration properties. (default: "")
 944     :sonar-java-opts: JVM options. (default: "")
 945     :sonar-additional-args: Additional command line arguments. (default: "")