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     :jjb-version: JJB version to install. (default: see job-template)
 404     :stream: Keyword that can be used to represent a release code-name.
 405         Often the same as the branch. (default: master)
 406     :submodule-recursive: Whether to checkout submodules recursively.
 407         (default: true)
 408
 409     :gerrit_merge_triggers: Override Gerrit Triggers.
 410     :gerrit_trigger_file_paths: Override file paths which can be used to
 411         filter which file modifications will trigger a build.
 412         (default defined by lf_jjb_common)
 413
 414
 415 JJB Verify
 416 ----------
 417
 418 Runs `jenkins-jobs test` to validate JJB syntax
 419
 420 :Template Names:
 421     - {project-name}-jjb-verify
 422     - gerrit-jjb-verify
 423     - github-jjb-verify
 424
 425 :Comment Trigger: recheck|reverify
 426
 427 :Required parameters:
 428
 429     :build-node: The node to run build on.
 430     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 431         be configured in defaults.yaml)
 432     :mvn-settings: The name of settings file containing credentials for
 433         the project.
 434
 435 :Optional parameters:
 436
 437     :branch: Git branch to fetch for the build. (default: master)
 438     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 439     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 440     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 441     :jjb-version: JJB version to install. (default: see job-template)
 442     :stream: Keyword that can be used to represent a release code-name.
 443         Often the same as the branch. (default: master)
 444     :submodule-recursive: Whether to checkout submodules recursively.
 445         (default: true)
 446
 447     :gerrit_verify_triggers: Override Gerrit Triggers.
 448     :gerrit_trigger_file_paths: Override file paths which can be used to
 449         filter which file modifications will trigger a build.
 450         (default defined by lf_jjb_common)
 451
 452 .. _info-yaml-verify:
 453
 454 Info YAML Verify
 455 ----------------
 456
 457 Info YAML Verify job validates that INFO.yaml file changes are kept isolated from
 458 other file changes. Verifies INFO.yaml files follow the schema defined in
 459 `global-jjb/info-schema`.
 460
 461 :Template Names:
 462     - {project-name}-info-yaml-verify
 463     - gerrit-info-yaml-verify
 464     - github-info-yaml-verify
 465
 466 :Required parameters:
 467
 468     :build-node: The node to run build on.
 469     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 470         be configured in defaults.yaml)
 471
 472 :Optional parameters:
 473
 474     :branch: Git branch to fetch for the build. (default: master)
 475     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 476     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 477     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 478     :stream: Keyword that can be used to represent a release code-name.
 479         Often the same as the branch. (default: master)
 480     :submodule-recursive: Whether to checkout submodules recursively.
 481         (default: true)
 482     :gerrit_verify_triggers: Override Gerrit Triggers.
 483
 484 .. _license-checker:
 485
 486 License Checker
 487 ---------------
 488
 489 Job to scan projects for files missing license headers.
 490
 491 :Template Names:
 492     - {project-name}-license-check
 493     - gerrit-license-check
 494     - github-license-check
 495
 496 :Optional parameters:
 497
 498     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 499     :file-patterns: Space-separated list of file patterns to scan.
 500         (default: \*.go \*.groovy \*.java \*.py \*.sh)
 501     :spdx-disable: Disable the SPDX-Identifier checker. (default: false)
 502     :lhc-version: Version of LHC to use. (default: 0.2.0)
 503     :license-exclude-paths: Comma-separated list of paths to exclude from the
 504         license checker. The paths used here will be matched using a contains
 505         rule so it is best to be as precise with the path as possible.
 506         For example a path of '/src/generated/' will be searched as
 507         '**/src/generated/**'.
 508         Example: org/opendaylight/yang/gen,protobuff/messages
 509         (default: '')
 510     :licenses-allowed: Comma-separated list of allowed licenses.
 511         (default: Apache-2.0,EPL-1.0,MIT)
 512     :project-pattern: The ANT based pattern for Gerrit Trigger to choose which
 513         projects to trigger job against. (default: '**')
 514
 515 .. _gjjb-packer-merge:
 516
 517 Packer Merge
 518 ------------
 519
 520 Packer Merge job runs `packer build` to build system images in the cloud.
 521
 522 :Template Names:
 523     - {project-name}-packer-merge-{platforms}-{templates}
 524     - gerrit-packer-merge
 525     - github-packer-merge
 526
 527 :Comment Trigger: remerge
 528
 529 :Required parameters:
 530
 531     :build-node: The node to run build on.
 532     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 533         be configured in defaults.yaml)
 534     :mvn-settings: The name of settings file containing credentials for
 535         the project.
 536     :platforms: Platform or distribution to build. Typically json file
 537         found in the packer/vars directory. (Example: centos)
 538     :template: System template to build. Typically shell script found in
 539         the packer/provision directory. (Example: java-builder)
 540
 541 :Optional parameters:
 542
 543     :cron: Time when the packer image should be rebuilt (default: @monthly)
 544     :branch: Git branch to fetch for the build. (default: master)
 545     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 546     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 547     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 548     :packer-cloud-settings: Name of settings file containing credentials
 549         for the cloud that packer will build on. (default: packer-cloud-env)
 550     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 551     :stream: Keyword that can be used to represent a release code-name.
 552         Often the same as the branch. (default: master)
 553     :submodule-recursive: Whether to checkout submodules recursively.
 554         (default: true)
 555
 556     :gerrit_verify_triggers: Override Gerrit Triggers.
 557
 558
 559 .. _gjjb-packer-verify:
 560
 561 Packer Verify
 562 -------------
 563
 564 Packer Verify job runs `packer validate` to verify packer configuration.
 565
 566 :Template Names:
 567     - {project-name}-packer-verify
 568     - gerrit-packer-verify
 569     - github-packer-verify
 570
 571 :Comment Trigger: recheck|reverify
 572
 573 :Required parameters:
 574
 575     :build-node: The node to run build on.
 576     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 577         be configured in defaults.yaml)
 578     :mvn-settings: The name of settings file containing credentials for
 579         the project.
 580
 581 :Optional parameters:
 582
 583     :branch: Git branch to fetch for the build. (default: master)
 584     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 585     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 586     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 587     :packer-cloud-settings: Name of settings file containing credentials
 588         for the cloud that packer will build on. (default: packer-cloud-env)
 589     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 590     :stream: Keyword that can be used to represent a release code-name.
 591         Often the same as the branch. (default: master)
 592     :submodule-recursive: Whether to checkout submodules recursively.
 593         (default: true)
 594
 595     :gerrit_verify_triggers: Override Gerrit Triggers.
 596     :gerrit_trigger_file_paths: Override file paths which can be used to
 597         filter which file modifications will trigger a build.