docs/jjb/lf-ci-jobs.rst

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