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         (required)
 277     :HARDWARE_ID: OpenStack flavor to use. (required)
 278
 279     :LABELS: Labels to assign to the vm. (default: FILE_NAME)
 280     :NETWORK_ID: OpenStack network to use. (default: "")
 281     :USER_DATA_ID: User Data to pass into the instance.
 282         (default: jenkins-init-script)
 283     :INSTANCE_CAP: Total number of instances of this type that can be launched
 284         at one time. When defined in clouds.cfg it defines the total for the
 285         entire cloud. (default: null)
 286     :SANDBOX_CAP: Total number of instances of this type that can be launched
 287         at one time. When defined in clouds.cfg it defines the total for the
 288         entire cloud. This applies to "sandbox" systems and overrides the
 289         INSTANCE_CAP setting. (default: null)
 290     :FLOATING_IP_POOL: Floating ip pool to use. (default: "")
 291     :SECURITY_GROUPS: Security group to use. (default: "default")
 292     :AVAILABILITY_ZONE: OpenStack availability zone to use. (default: "")
 293     :START_TIMEOUT: Number of milliseconds to wait for the agent to be
 294         provisioned and connected. (default: 600000)
 295     :KEY_PAIR_NAME: SSH Public Key Pair to use for authentication.
 296         (default: jenkins)
 297     :NUM_EXECUTORS: Number of executors to enable for the instance.
 298         (default: 1)
 299     :JVM_OPTIONS: JVM Options to pass to Java. (default: "")
 300     :FS_ROOT: File system root for the workspace. (default: "/w")
 301     :RETENTION_TIME: Number of minutes to wait for an idle slave to be used
 302         again before it's removed. If set to -1, the slave will be kept
 303         forever. (default: 0)
 304     :CONNECTION_TYPE: The connection type for Jenkins to connect to the build
 305         minion. Valid options: JNLP, SSH. (default: "SSH")
 306
 307 For a live example see the OpenDaylight project jenkins-config directory.
 308 https://github.com/opendaylight/releng-builder/tree/master/jenkins-config
 309
 310 Troubleshooting
 311 ^^^^^^^^^^^^^^^
 312
 313 :Cloud Configuration:
 314
 315     The directory ``groovy-inserts`` contains the groovy script output that is
 316     used to push to Jenkins. In the event of a job failure this file can be
 317     inspected.
 318
 319
 320 Jenkins Sandbox Cleanup
 321 -----------------------
 322
 323 Cleanup Jenkins Sandbox of jobs and views periodically.
 324
 325 :Template names:
 326
 327     - {project-name}-jenkins-sandbox-cleanup
 328     - gerrit-jenkins-sandbox-cleanup
 329     - github-jenkins-sandbox-cleanup
 330
 331 :Comment Trigger: NONE
 332
 333 :Required parameters:
 334
 335     :build-node: The node to run build on.
 336     :jenkins-ssh-credential: Credential to use for SSH. (Generally
 337         should be configured in defaults.yaml)
 338
 339 :Optional parameters:
 340
 341     :cron: Schedule to run job. (default: '0 8 * * 6')
 342
 343
 344 JJB Deploy Job
 345 --------------
 346
 347 Deploy jobs to jenkins-sandbox system via code review comment
 348
 349 This job checks out the current code review patch and then runs a
 350 `jenkins-jobs update` to push a patch defined by the comment.
 351
 352 :Template names:
 353
 354     - {project-name}-jjb-deploy-job
 355     - gerrit-jjb-deploy-job
 356     - github-jjb-deploy-job
 357
 358 :Comment Trigger: jjb-deploy JOB_NAME
 359
 360     .. note::
 361
 362        JOB_NAME can include the * wildcard character to push multiple jobs
 363        matching the pattern. For example `jjb-deploy builder-jjb-*`` will push
 364        all builder-jjb-* jobs to the sandbox system.
 365
 366 :Required parameters:
 367
 368     :build-node: The node to run build on.
 369     :jenkins-ssh-credential: Credential to use for SSH. (Generally
 370         should be configured in defaults.yaml)
 371
 372 :Optional parameters:
 373
 374     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 375     :gerrit_jjb_deploy_job_triggers: Override Gerrit Triggers.
 376
 377
 378 JJB Merge
 379 ---------
 380
 381 Runs `jenkins-jobs update` to update production job configuration
 382
 383 :Template Names:
 384     - {project-name}-jjb-merge
 385     - gerrit-jjb-merge
 386     - github-jjb-merge
 387
 388 :Comment Trigger: remerge
 389
 390 :Required parameters:
 391
 392     :build-node: The node to run build on.
 393     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 394         be configured in defaults.yaml)
 395     :mvn-settings: The name of settings file containing credentials for
 396         the project.
 397
 398 :Optional parameters:
 399
 400     :branch: Git branch to fetch for the build. (default: master)
 401     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 402     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 403     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 404     :jjb-version: JJB version to install. (default: see job-template)
 405     :stream: Keyword that can be used to represent a release code-name.
 406         Often the same as the branch. (default: master)
 407     :submodule-recursive: Whether to checkout submodules recursively.
 408         (default: true)
 409
 410     :gerrit_merge_triggers: Override Gerrit Triggers.
 411     :gerrit_trigger_file_paths: Override file paths which can be used to
 412         filter which file modifications will trigger a build.
 413         (default defined by lf_jjb_common)
 414
 415
 416 JJB Verify
 417 ----------
 418
 419 Runs `jenkins-jobs test` to validate JJB syntax
 420
 421 :Template Names:
 422     - {project-name}-jjb-verify
 423     - gerrit-jjb-verify
 424     - github-jjb-verify
 425
 426 :Comment Trigger: recheck|reverify
 427
 428 :Required parameters:
 429
 430     :build-node: The node to run build on.
 431     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 432         be configured in defaults.yaml)
 433     :mvn-settings: The name of settings file containing credentials for
 434         the project.
 435
 436 :Optional parameters:
 437
 438     :branch: Git branch to fetch for the build. (default: master)
 439     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 440     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 441     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 442     :jjb-version: JJB version to install. (default: see job-template)
 443     :stream: Keyword that can be used to represent a release code-name.
 444         Often the same as the branch. (default: master)
 445     :submodule-recursive: Whether to checkout submodules recursively.
 446         (default: true)
 447
 448     :gerrit_verify_triggers: Override Gerrit Triggers.
 449     :gerrit_trigger_file_paths: Override file paths which can be used to
 450         filter which file modifications will trigger a build.
 451         (default defined by lf_jjb_common)
 452
 453 .. _info-yaml-verify:
 454
 455 Info YAML Verify
 456 ----------------
 457
 458 Info YAML Verify job validates that INFO.yaml file changes are kept isolated from
 459 other file changes. Verifies INFO.yaml files follow the schema defined in
 460 `global-jjb/info-schema`.
 461
 462 :Template Names:
 463     - {project-name}-info-yaml-verify
 464     - gerrit-info-yaml-verify
 465     - github-info-yaml-verify
 466
 467 :Required parameters:
 468
 469     :build-node: The node to run build on.
 470     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 471         be configured in defaults.yaml)
 472
 473 :Optional parameters:
 474
 475     :branch: Git branch to fetch for the build. (default: master)
 476     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 477     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 478     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 479     :stream: Keyword that can be used to represent a release code-name.
 480         Often the same as the branch. (default: master)
 481     :submodule-recursive: Whether to checkout submodules recursively.
 482         (default: true)
 483     :gerrit_verify_triggers: Override Gerrit Triggers.
 484
 485 .. _license-checker:
 486
 487 License Checker
 488 ---------------
 489
 490 Job to scan projects for files missing license headers.
 491
 492 :Template Names:
 493     - {project-name}-license-check
 494     - gerrit-license-check
 495     - github-license-check
 496
 497 :Optional parameters:
 498
 499     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 500     :file-patterns: Space-separated list of file patterns to scan.
 501         (default: \*.go \*.groovy \*.java \*.py \*.sh)
 502     :spdx-disable: Disable the SPDX-Identifier checker. (default: false)
 503     :lhc-version: Version of LHC to use. (default: 0.2.0)
 504     :license-exclude-paths: Comma-separated list of paths to exclude from the
 505         license checker. The paths used here will be matched using a contains
 506         rule so it is best to be as precise with the path as possible.
 507         For example a path of '/src/generated/' will be searched as
 508         '**/src/generated/**'.
 509         Example: org/opendaylight/yang/gen,protobuff/messages
 510         (default: '')
 511     :licenses-allowed: Comma-separated list of allowed licenses.
 512         (default: Apache-2.0,EPL-1.0,MIT)
 513     :project-pattern: The ANT based pattern for Gerrit Trigger to choose which
 514         projects to trigger job against. (default: '**')
 515
 516 .. _gjjb-packer-merge:
 517
 518 Packer Merge
 519 ------------
 520
 521 Packer Merge job runs `packer build` to build system images in the cloud.
 522
 523 :Template Names:
 524     - {project-name}-packer-merge-{platforms}-{templates}
 525     - gerrit-packer-merge
 526     - github-packer-merge
 527
 528 :Comment Trigger: remerge
 529
 530 :Required parameters:
 531
 532     :build-node: The node to run build on.
 533     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 534         be configured in defaults.yaml)
 535     :mvn-settings: The name of settings file containing credentials for
 536         the project.
 537     :platforms: Platform or distribution to build. Typically json file
 538         found in the packer/vars directory. (Example: centos)
 539     :template: System template to build. Typically shell script found in
 540         the packer/provision directory. (Example: java-builder)
 541
 542 :Optional parameters:
 543
 544     :cron: Time when the packer image should be rebuilt (default: @monthly)
 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: 90)
 548     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 549     :packer-cloud-settings: Name of settings file containing credentials
 550         for the cloud that packer will build on. (default: packer-cloud-env)
 551     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 552     :stream: Keyword that can be used to represent a release code-name.
 553         Often the same as the branch. (default: master)
 554     :submodule-recursive: Whether to checkout submodules recursively.
 555         (default: true)
 556
 557     :gerrit_verify_triggers: Override Gerrit Triggers.
 558
 559
 560 .. _gjjb-packer-verify:
 561
 562 Packer Verify
 563 -------------
 564
 565 Packer Verify job runs `packer validate` to verify packer configuration.
 566
 567 :Template Names:
 568     - {project-name}-packer-verify
 569     - gerrit-packer-verify
 570     - github-packer-verify
 571
 572 :Comment Trigger: recheck|reverify
 573
 574 :Required parameters:
 575
 576     :build-node: The node to run build on.
 577     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 578         be configured in defaults.yaml)
 579     :mvn-settings: The name of settings file containing credentials for
 580         the project.
 581
 582 :Optional parameters:
 583
 584     :branch: Git branch to fetch for the build. (default: master)
 585     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 586     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 587     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 588     :packer-cloud-settings: Name of settings file containing credentials
 589         for the cloud that packer will build on. (default: packer-cloud-env)
 590     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 591     :stream: Keyword that can be used to represent a release code-name.
 592         Often the same as the branch. (default: master)
 593     :submodule-recursive: Whether to checkout submodules recursively.
 594         (default: true)
 595
 596     :gerrit_verify_triggers: Override Gerrit Triggers.
 597     :gerrit_trigger_file_paths: Override file paths which can be used to
 598         filter which file modifications will trigger a build.