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. (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 can be launched
 256         at one time. When defined in clouds.cfg it defines the total for the
 257         entire cloud. (default: null)
 258     :SANDBOX_CAP: Total number of instances of this type that can be launched
 259         at one time. When defined in clouds.cfg it defines the total for the
 260         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 the agent to be
 266         provisioned and connected. (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 slave to be used
 275         again before it's removed. If set to -1, the slave will be kept
 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 that is
 290     used to push to Jenkins. In the event of a job failure this file can be
 291     inspected.
 292
 293  .. _lf-global-jjb-jenkins-cfg-verify:
 294
 295 Jenkins Configuration Verify
 296 ----------------------------
 297
 298 Jenkins job to verify the Global Jenkins configuration.
 299
 300 Requires the ``clouds-yaml`` file to be setup on the Jenkins host.
 301
 302 :Template names:
 303
 304     - {project-name}-jenkins-cfg-verify
 305     - gerrit-jenkins-cfg-verify
 306     - github-jenkins-cfg-verify
 307
 308 :Optional parameters:
 309
 310     :branch: Git branch to build against. (default: master)
 311     :git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
 312
 313 This job is not part of the "{project-name}-ci-jobs" group. It must be called
 314 explicitly.
 315
 316 Example:
 317
 318 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/jenkins-cfg-verify.yaml
 319    :language: yaml
 320
 321
 322 .. _jenkins-sandbox-cleanup:
 323
 324 Jenkins Sandbox Cleanup
 325 -----------------------
 326
 327 Cleanup Jenkins Sandbox of jobs and views periodically.
 328
 329 :Template names:
 330
 331     - {project-name}-jenkins-sandbox-cleanup
 332     - gerrit-jenkins-sandbox-cleanup
 333     - github-jenkins-sandbox-cleanup
 334
 335 :Comment Trigger: NONE
 336
 337 :Required parameters:
 338
 339     :build-node: The node to run build on.
 340     :jenkins-ssh-credential: Credential to use for SSH. (Generally
 341         should be configured in defaults.yaml)
 342
 343 :Optional parameters:
 344
 345     :cron: Schedule to run job. (default: '0 8 * * 6')
 346
 347
 348 .. _jjb-deploy:
 349
 350 JJB Deploy Job
 351 --------------
 352
 353 Deploy jobs to jenkins-sandbox system via code review comment.
 354
 355 This job checks out the current code review patch and then runs a
 356 ``jenkins-jobs update`` to push a patch defined by the comment.
 357
 358 :Template names:
 359
 360     - {project-name}-jjb-deploy-job
 361     - gerrit-jjb-deploy-job
 362     - github-jjb-deploy-job
 363
 364 :Comment Trigger: jjb-deploy JOB_NAME
 365
 366     .. note::
 367
 368        The JJB Deploy Job is configured to trigger only if the Gerrit comment
 369        starts with the `jjb-deploy` keyword.
 370
 371        Example of a valid command in Gerrit comment that triggers the job:
 372
 373        ``jjb-deploy builder-jjb-*``
 374
 375        Example of a invalid command in Gerrit comment that would _not_ trigger
 376        the job:
 377
 378        ``Update the job. jjb-deploy builder-jjb-*``
 379
 380        JOB_NAME can include the * wildcard character to push multiple jobs
 381        matching the pattern. For example ``jjb-deploy builder-jjb-*`` will push
 382        all builder-jjb-* jobs to the sandbox system.
 383
 384 :Required parameters:
 385
 386     :build-node: The node to run build on.
 387     :jenkins-ssh-credential: Credential to use for SSH. (Generally
 388         should be configured in defaults.yaml)
 389
 390 :Optional parameters:
 391
 392     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 393     :gerrit_jjb_deploy_job_triggers: Override Gerrit Triggers.
 394
 395
 396 .. _jjb-merge:
 397
 398 JJB Merge
 399 ---------
 400
 401 Runs `jenkins-jobs update` to update production job configuration
 402
 403 :Template Names:
 404     - {project-name}-jjb-merge
 405     - gerrit-jjb-merge
 406     - github-jjb-merge
 407
 408 :Comment Trigger: remerge
 409
 410 :Required parameters:
 411
 412     :build-node: The node to run build on.
 413     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 414         be configured in defaults.yaml)
 415
 416 :Optional parameters:
 417
 418     :branch: Git branch to fetch for the build. (default: master)
 419     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 420     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 421     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 422     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
 423     :jjb-workers: Number of threads to run **update** with. Set to 0 by default
 424         which is equivalent to the number of available CPU cores. (default: 0)
 425     :jjb-version: JJB version to install. (default: see job-template)
 426     :stream: Keyword that can be used to represent a release code-name.
 427         Often the same as the branch. (default: master)
 428     :submodule-recursive: Whether to checkout submodules recursively.
 429         (default: true)
 430     :submodule-timeout: Timeout (in minutes) for checkout operation.
 431         (default: 10)
 432     :submodule-disable: Disable submodule checkout operation.
 433         (default: false)
 434
 435     :gerrit_merge_triggers: Override Gerrit Triggers.
 436     :gerrit_trigger_file_paths: Override file paths which can be used to
 437         filter which file modifications will trigger a build.
 438         (default defined by lf_jjb_common)
 439
 440
 441 .. _jjb-verify:
 442
 443 JJB Verify
 444 ----------
 445
 446 Runs `jenkins-jobs test` to validate JJB syntax. Optionally validates
 447 build-node labels used in templates and job definitions.
 448
 449 :Template Names:
 450     - {project-name}-jjb-verify
 451     - gerrit-jjb-verify
 452     - github-jjb-verify
 453
 454 :Comment Trigger: recheck|reverify
 455
 456 :Required parameters:
 457
 458     :build-node: The node to run build on.
 459     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 460         be configured in defaults.yaml)
 461
 462 :Optional parameters:
 463
 464     :branch: Git branch to fetch for the build. (default: master)
 465     :build-concurrent: Whether or not to allow this job to run multiple jobs
 466         simultaneously. (default: true)
 467     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 468     :build-node-label-check: Whether to check build-node labels in jobs
 469         against node names in cloud config files (default: false)
 470     :build-node-label-list: Space-separated list of external build-node
 471         labels not present in cloud config files (default: "")
 472     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 473     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 474     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
 475     :jjb-version: JJB version to install. (default: see job-template)
 476     :stream: Keyword that can be used to represent a release code-name.
 477         Often the same as the branch. (default: master)
 478     :submodule-recursive: Whether to checkout submodules recursively.
 479         (default: true)
 480     :submodule-timeout: Timeout (in minutes) for checkout operation.
 481         (default: 10)
 482     :submodule-disable: Disable submodule checkout operation.
 483         (default: false)
 484     :throttle_categories: List of categories to throttle by.
 485     :throttle-enabled: Whether or not to enable throttling on the job.
 486         (default: true)
 487     :throttle-max-per-node: Max jobs to run on the same node. (default: 1)
 488     :throttle-max-total: Max jobs to run across the entire project. - 0
 489         means 'unlimited' (default: 0)
 490     :throttle-option: Throttle by the project or by list of categories
 491         defined in the throttle plugin configuration. (options: 'project',
 492         'category'; default: project)
 493
 494     :gerrit_verify_triggers: Override Gerrit Triggers.
 495     :gerrit_trigger_file_paths: Override file paths which can be used to
 496         filter which file modifications will trigger a build.
 497         (default defined by lf_jjb_common)
 498
 499 .. _jjb-verify-upstream-gjjb:
 500
 501 JJB Verify Upstream Global JJB
 502 ------------------------------
 503
 504 Runs ``jenkins-jobs test`` to validate JJB syntax for upstream global-jjb
 505 patches. This job is useful to notify upstream that they may be breaking
 506 project level jobs.
 507
 508 :Template Names:
 509     - {project-name}-jjb-verify-upstream-gjjb
 510     - gerrit-jjb-verify-upstream-gjjb
 511     - github-jjb-verify-upstream-gjjb
 512
 513 :Comment Trigger: recheck|reverify
 514
 515 :Required parameters:
 516
 517     :build-node: The node to run build on.
 518     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 519         be configured in defaults.yaml)
 520
 521 :Optional parameters:
 522
 523     :branch: Git branch to fetch for the build. (default: master)
 524     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 525     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 526     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 527     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
 528     :jjb-version: JJB version to install. (default: see job-template)
 529     :stream: Keyword that can be used to represent a release code-name.
 530         Often the same as the branch. (default: master)
 531
 532 .. _info-yaml-verify:
 533
 534 Info YAML Verify
 535 ----------------
 536
 537 Info YAML Verify job validates that INFO.yaml file changes are kept isolated from
 538 other file changes. Verifies INFO.yaml files follow the schema defined in
 539 `lfit/releng-global-jjb/schema/info-schema.yaml`.
 540
 541 :Template Names:
 542     - {project-name}-info-yaml-verify
 543     - gerrit-info-yaml-verify
 544     - github-info-yaml-verify
 545
 546 :Required parameters:
 547
 548     :build-node: The node to run build on.
 549     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 550         be configured in defaults.yaml)
 551
 552 :Optional parameters:
 553
 554     :branch: Git branch to fetch for the build. (default: master)
 555     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 556     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 557     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 558     :stream: Keyword that can be used to represent a release code-name.
 559         Often the same as the branch. (default: master)
 560     :submodule-recursive: Whether to checkout submodules recursively.
 561         (default: true)
 562     :submodule-timeout: Timeout (in minutes) for checkout operation.
 563         (default: 10)
 564     :submodule-disable: Disable submodule checkout operation.
 565         (default: false)
 566
 567     :gerrit_verify_triggers: Override Gerrit Triggers.
 568
 569 .. _lf_pipelines_verify:
 570
 571 LF Pipelines Verify
 572 -------------------
 573
 574 Verify job for the LF RelEng pipeline library. This can be implemented on any
 575 Jenkins machine that has the appropriate Pipelines plugins installed. It will
 576 look for a Gerrit system named "lf-releng" (which should be mapped to
 577 https://gerrit.linuxfoundation.org/infra/), and pull in the Jenkinsfile in the
 578 root directory of the repo.
 579
 580 :Template Names:
 581     - lf-pipelines-verify
 582
 583 :Comment Trigger: recheck|reverify
 584
 585 .. _license-checker:
 586
 587 License Checker
 588 ---------------
 589
 590 Job to scan projects for files missing license headers.
 591
 592 :Template Names:
 593     - {project-name}-license-check
 594     - gerrit-license-check
 595     - github-license-check
 596
 597 :Optional parameters:
 598
 599     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 600     :file-patterns: Space-separated list of file patterns to scan.
 601         (default: \*.go \*.groovy \*.java \*.py \*.sh)
 602     :spdx-disable: Disable the SPDX-Identifier checker. (default: false)
 603     :lhc-version: Version of LHC to use. (default: 0.2.0)
 604     :license-exclude-paths: Comma-separated list of paths to exclude from the
 605         license checker. The paths used here will be matched using a contains
 606         rule so it is best to be as precise with the path as possible.
 607         For example a path of '/src/generated/' will be searched as
 608         '**/src/generated/**'.
 609         Example: org/opendaylight/yang/gen,protobuff/messages
 610         (default: '')
 611     :licenses-allowed: Comma-separated list of allowed licenses.
 612         (default: Apache-2.0,EPL-1.0,MIT)
 613     :project-pattern: The ANT based pattern for Gerrit Trigger to choose which
 614         projects to trigger job against. (default: '**')
 615
 616 .. _gjjb-openstack-cron:
 617
 618 OpenStack Cron
 619 --------------
 620
 621 Cron job that runs regularly to perform periodic tasks against OpenStack.
 622
 623 This job requires a Config File Provider file named ``clouds-yaml`` available
 624 containing the credentials for the cloud.
 625
 626 :Template Names:
 627     - {project-name}-openstack-cron
 628     - gerrit-openstack-cron
 629     - github-openstack-cron
 630
 631 :Required parameters:
 632
 633     :build-node: The node to run build on.
 634     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 635         be configured in defaults.yaml)
 636     :jenkins-urls: URLs to Jenkins systems to check for active builds.
 637
 638 :Optional parameters:
 639
 640     :branch: Git branch to fetch for the build. (default: master)
 641     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 642     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 643     :cron: Time when the packer image should be rebuilt (default: @hourly)
 644     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 645     :openstack-cloud: OS_CLOUD setting to pass to openstack client.
 646         (default: vex)
 647     :openstack-image-cleanup: Whether or not to run the image cleanup script.
 648         (default: true)
 649     :openstack-image-cleanup-age: Age in days of image before marking it for
 650         removal. (default: 30)
 651     :openstack-image-protect: Whether or not to run the image protect script.
 652         (default: true)
 653     :openstack-server-cleanup: Whether or not to run the server cleanup script.
 654         (default: true)
 655     :openstack-stack-cleanup: Whether or not to run the stack cleanup script.
 656         (default: true)
 657     :openstack-volume-cleanup: Whether or not to run the volume cleanup script.
 658         (default: true)
 659     :stream: Keyword that can be used to represent a release code-name.
 660         Often the same as the branch. (default: master)
 661     :submodule-recursive: Whether to checkout submodules recursively.
 662         (default: true)
 663     :submodule-timeout: Timeout (in minutes) for checkout operation.
 664         (default: 10)
 665     :submodule-disable: Disable submodule checkout operation.
 666         (default: false)
 667
 668 Minimal Example:
 669
 670 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-cron-minimal.yaml
 671
 672 Full Example:
 673
 674 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-cron-full.yaml
 675
 676 .. _gjjb-openstack-update-cloud-image:
 677
 678 OpenStack Update Cloud Image
 679 ----------------------------
 680
 681 This job finds and updates OpenStack cloud images on the ci-management source
 682 repository.
 683
 684 The job is triggered in two ways:
 685
 686 1. When packer merge job completes, the new image name created is passed
 687    down to the job.
 688 2. When the job is triggered manually to update all new images.
 689
 690 When the job is triggered through an upstream packer merge job, this only
 691 generates a change request for the new image built.
 692
 693 When the job is triggered manually, this job finds the latest images on
 694 OpenStack cloud and compares them with the images currently used in the source
 695 ci-management source repository. If the compared images have newer
 696 time stamps are **all** updated 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 should
 710         be configured 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 can be used to represent 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 :Template Names:
 750     - {project-name}-packer-merge-{platforms}-{templates}
 751     - gerrit-packer-merge
 752     - github-packer-merge
 753
 754 :Comment Trigger: remerge
 755
 756 :Required parameters:
 757
 758     :build-node: The node to run build on.
 759     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 760         be configured in defaults.yaml)
 761     :mvn-settings: The name of settings file containing credentials for
 762         the project.
 763     :platforms: Platform or distribution to build. Typically json file
 764         found in the packer/vars directory. (Example: centos-7)
 765     :templates: System template to build. Typically a yaml file or shell script
 766         found in the packer/provision directory. (Example: docker)
 767
 768 :Optional parameters:
 769
 770     :cron: Time when the packer image should be rebuilt (default: @monthly)
 771     :branch: Git branch to fetch for the build. (default: master)
 772     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 773     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 774     :gerrit_verify_triggers: Override Gerrit Triggers.
 775     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 776     :openstack: Packer template uses an OpenStack builder (default: true).
 777     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
 778         (default: vex).
 779     :packer-cloud-settings: Name of settings file containing credentials
 780         for the cloud that packer will build on. (default: packer-cloud-env)
 781     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 782     :stream: Keyword that can be used to represent a release code-name.
 783         Often the same as the branch. (default: master)
 784     :submodule-recursive: Whether to checkout submodules recursively.
 785         (default: true)
 786     :submodule-timeout: Timeout (in minutes) for checkout operation.
 787         (default: 10)
 788     :submodule-disable: Disable submodule checkout operation.
 789         (default: false)
 790     :update-cloud-image: Submit a change request to update newly built cloud
 791         image to Jenkins. (default: false)
 792
 793
 794 Test an in-progress patch
 795 ^^^^^^^^^^^^^^^^^^^^^^^^^
 796
 797 To test an in-progress patch from a GitHub Pull Request, upload this
 798 job to the :doc:`Jenkins Sandbox <lfdocs:jenkins-sandbox>`. Then when manually
 799 building the job, replace the GERRIT_REFSPEC parameter with the GitHub Pull
 800 Request number of the patch you would like to test.
 801
 802 Example GitHub:
 803
 804 .. code-block:: none
 805
 806    GERRIT_REFSPEC: origin/pr/49/merge
 807
 808
 809 .. _gjjb-packer-verify:
 810
 811 Packer Verify
 812 -------------
 813
 814 Packer Verify job runs `packer validate` to verify packer configuration. The
 815 verify job checks superficial syntax of the template and other files. It does
 816 not attempt to build an image, and cannot detect all possible build issues.
 817
 818 :Template Names:
 819     - {project-name}-packer-verify
 820     - gerrit-packer-verify
 821     - github-packer-verify
 822
 823 :Comment Trigger: recheck|reverify
 824
 825 :Required parameters:
 826
 827     :build-node: The node to run build on.
 828     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 829         be configured in defaults.yaml)
 830     :mvn-settings: The name of settings file containing credentials for
 831         the project.
 832
 833 :Optional parameters:
 834
 835     :branch: Git branch to fetch for the build. (default: master)
 836     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 837     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 838     :gerrit_trigger_file_paths: Override file paths which can be used to
 839         filter which file modifications will trigger a build.
 840     :gerrit_verify_triggers: Override Gerrit Triggers.
 841     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 842     :openstack: Packer template uses an OpenStack builder (default: true).
 843     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
 844         (default: vex).
 845     :packer-cloud-settings: Name of settings file containing credentials
 846         for the cloud that packer will build on. (default: packer-cloud-env)
 847     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 848     :stream: Keyword that can be used to represent a release code-name.
 849         Often the same as the branch. (default: master)
 850     :submodule-recursive: Whether to checkout submodules recursively.
 851         (default: true)
 852     :submodule-timeout: Timeout (in minutes) for checkout operation.
 853         (default: 10)
 854     :submodule-disable: Disable submodule checkout operation.
 855         (default: false)
 856
 857
 858 .. _gjjb-packer-verify-build:
 859
 860 Packer Verify Build
 861 -------------------
 862
 863 Packer Verify Build job is essentially the same as the
 864 :ref:`Packer Merge job<gjjb-packer-merge>`. It is triggered only by its keyword,
 865 and will build a useable image. If the last patch set before a merge has a
 866 successful verify build, the merge job will not build the same image.
 867
 868 :Template Names:
 869    - {project-name}-packer-verify-build-{platforms}-{templates}
 870    - gerrit-packer-verify-build
 871    - github-packer-verify-build
 872
 873 :Comment Trigger: verify-build|packer-build
 874
 875 :Required parameters:
 876
 877    :build-node: The node to run build on.
 878    :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 879        be configured in defaults.yaml)
 880    :mvn-settings: The name of settings file containing credentials for
 881        the project.
 882    :platforms: Platform or distribution to build. Typically json file
 883        found in the packer/vars directory. (Example: centos-7)
 884    :templates: System template to build. Typically a yaml file or shell script
 885        found in the packer/provision directory. (Example: docker)
 886
 887 :Optional parameters:
 888
 889    :branch: Git branch to fetch for the build. (default: master)
 890    :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 891    :build-timeout: Timeout in minutes before aborting build. (default: 10)
 892    :gerrit_trigger_file_paths: Override file paths which can be used to
 893        filter which file modifications will trigger a build.
 894    :gerrit_verify_triggers: Override Gerrit Triggers.
 895    :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 896    :openstack: Packer template uses an OpenStack builder (default: true).
 897    :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
 898        (default: vex).
 899    :packer-cloud-settings: Name of settings file containing credentials
 900        for the cloud that packer will build on. (default: packer-cloud-env)
 901    :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 902    :stream: Keyword that can be used to represent a release code-name.
 903        Often the same as the branch. (default: master)
 904    :submodule-recursive: Whether to checkout submodules recursively.
 905        (default: true)
 906    :submodule-timeout: Timeout (in minutes) for checkout operation.
 907        (default: 10)
 908    :submodule-disable: Disable submodule checkout operation.
 909        (default: false)
 910    :update-cloud-image: Submit a change request to update new built cloud
 911        image to Jenkins. (default: false)
 912
 913
 914 Puppet Verify
 915 -------------
 916
 917 Runs puppet-lint in the ``puppet-dir`` directory. puppet-lint runs recursively,
 918 the base directory is usually the best place to run from.
 919
 920 :Template Names:
 921
 922     - {project-name}-puppet-verify
 923     - gerrit-puppet-verify
 924     - github-puppet-verify
 925
 926 :Comment Trigger: recheck|reverify
 927
 928 :Required Parameters:
 929
 930     :build-node: The node to run build on.
 931     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 932         in defaults.yaml)
 933
 934 :Optional Parameters:
 935
 936     :branch: The branch to build against. (default: master)
 937     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 938     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 939     :gerrit_trigger_file_paths: Override file paths which used to filter which
 940         file modifications will trigger a build. Refer to JJB documentation for
 941         "file-path" details.
 942         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 943     :git-url: URL clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
 944     :puppet-dir: Directory containing the project's puppet module(s) relative
 945         to the workspace.
 946         (default: '')
 947     :puppet-lint-version: Version of puppet-lint to use for testing.
 948         (default: 2.3.6)
 949     :stream: Keyword representing a release code-name.
 950         Often the same as the branch. (default: master)
 951     :submodule-recursive: Whether to checkout submodules recursively.
 952         (default: true)
 953     :submodule-timeout: Timeout (in minutes) for checkout operation.
 954         (default: 10)
 955     :submodule-disable: Disable submodule checkout operation.
 956         (default: false)
 957
 958
 959 Sonar
 960 -----
 961
 962 Runs the Jenkins SonarQube Scanner plug-in to analyze code for bugs,
 963 code smells and security vulnerabilities, and to upload the result
 964 (possibly including code-coverage statistics) to a SonarQube server
 965 or to SonarCloud.io.
 966
 967 Requires ``SonarQube Scanner for Jenkins``
 968
 969 One of the optional parameters sonar-project-file and sonar-properties
 970 must be supplied; they cannot both be empty.
 971
 972 Plug-in configurations
 973     Manage Jenkins --> Configure System --> SonarQube servers
 974         - Name: Sonar (fixed)
 975         - Server URL: https://sonar.server.org/ or https://sonarcloud.io
 976         - Server authentication token: none for local, API token (saved as a
 977           "secret text" credential) for Sonarcloud
 978
 979     Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
 980         - Name: SonarQube Scanner (fixed)
 981         - Install automatically
 982         - Select latest version
 983
 984 .. note:: Sonar properties can be set directly in the job definition by
 985    setting the sonar-project-file to ``""`` and adding all properties under
 986    ``sonar-properties``.
 987
 988 :Template Names:
 989
 990     - {project-name}-sonar
 991     - gerrit-sonar
 992     - github-sonar
 993
 994 :Optional Parameters:
 995     :sonar-task: Sonar task to run. (default: "")
 996     :sonar-project-file: The filename for the project's properties
 997         (default: "sonar-project.properties")
 998     :sonar-properties: Sonar configuration properties. (default: "")
 999     :sonar-java-opts: JVM options. (default: "")
1000     :sonar-additional-args: Additional command line arguments. (default: "")
1001
1002
1003 Sonar with Prescan
1004 ------------------
1005
1006 The same as the Sonar job above, except the caller also defines a builder
1007 called ``lf-sonar-prescan``, in which they can put any builders that they want
1008 to run prior to the Sonar scan.
1009
1010 .. code-block:: yaml
1011
1012    - builder:
1013        name: lf-sonar-prescan
1014        builders:
1015          - shell: "# Pre-scan shell script"
1016
1017 :Template Names:
1018
1019     - {project-name}-sonar-prescan
1020     - gerrit-sonar-prescan
1021     - github-sonar-prescan
1022
1023 :Required Parameters:
1024     :lf-sonar-prescan: A builder that will run prior to the Sonar scan.
1025
1026 :Optional Parameters:
1027     :sonar-task: Sonar task to run. (default: "")
1028     :sonar-project-file: The filename for the project's properties
1029         (default: "sonar-project.properties")
1030     :sonar-properties: Sonar configuration properties. (default: "")
1031     :sonar-java-opts: JVM options. (default: "")
1032     :sonar-additional-args: Additional command line arguments. (default: "")
1033
1034
1035 Sonar with Prescan Script
1036 -------------------------
1037
1038 The same as the Sonar job above, except the caller must supply a shell script
1039 to run prior to the Sonar scan. This is commonly used to install prerequisites,
1040 build the project, execute unit tests and generate a code-coverage report.
1041
1042 :Template Names:
1043
1044     - {project-name}-sonar-prescan-script
1045     - gerrit-sonar-prescan-script
1046     - github-sonar-prescan-script
1047
1048 :Required Parameters:
1049     :sonar-prescan-script: A shell script that will run prior to the Sonar scan.
1050
1051 :Optional Parameters:
1052     :sonar-task: Sonar task to run. (default: "")
1053     :sonar-project-file: The filename for the project's properties.
1054         (default: "sonar-project.properties")
1055     :sonar-properties: Sonar configuration properties. (default: "")
1056     :sonar-java-opts: JVM options. (default: "")
1057     :sonar-additional-args: Additional command line arguments. (default: "")