docs/jjb/lf-docker-jobs.rst

   1 ###########
   2 Docker Jobs
   3 ###########
   4
   5 Job Groups
   6 ==========
   7
   8 .. include:: ../job-groups.rst
   9
  10 Below is a list of Docker job groups:
  11
  12 .. literalinclude:: ../../jjb/lf-docker-job-groups.yaml
  13    :language: yaml
  14
  15
  16 Macros
  17 ======
  18
  19 lf-docker-get-container-tag
  20 ---------------------------
  21
  22 Chooses a container tag to label the image based on the 'container-tag-method'
  23 parameter.  If container-tag-method: latest, the tag 'latest' is used.
  24 If container-tag-method: git-describe, the tag is obtained using
  25 the git describe command, which requires that the repository has a git tag.
  26 If container-tag-method: yaml-file, the tag is obtained using
  27 the yq command, which requires that the repository has a YAML file named
  28 'container-tag.yaml'. The script checks the docker-root directory by
  29 default or the directory specified by parameter container-tag-yaml-dir.
  30 An example file appears below. Optionally, teams can call their own script to
  31 handle the docker tagging differently.
  32
  33
  34 lf-docker-build
  35 ---------------
  36
  37 Calls docker build to build the container.
  38
  39 lf-docker-push
  40 --------------
  41
  42 Calls docker-push.sh script to push docker images.
  43
  44 Job Templates
  45 =============
  46
  47 Docker Verify
  48 -------------
  49
  50 Executes a docker build task.
  51
  52 :Template Names:
  53
  54     - {project-name}-docker-verify-{stream}
  55     - gerrit-docker-verify
  56     - github-docker-verify
  57
  58 :Comment Trigger: **recheck|reverify** post a comment with one of the
  59     triggers to launch this job manually. Do not include any other
  60     text or vote in the same comment.
  61
  62 :Required parameters:
  63
  64     :build-node: The node to run build on.
  65     :container-public-registry: Docker registry source with base images.
  66     :docker-name: Name of the Docker image.
  67     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
  68         be configured in defaults.yaml)
  69     :mvn-settings: Maven settings.xml file containing credentials to use.
  70
  71 :Optional parameters:
  72
  73     :branch: Git branch to fetch for the build. (default: master)
  74     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
  75     :build-timeout: Timeout in minutes before aborting build. (default: 60)
  76     :container-tag-method: Specifies the docker tag-choosing method.
  77         Options are "latest", "git-describe" or "yaml-file".
  78         Option git-describe requires a git tag to exist in the repository.
  79         Option yaml-file requires a file "container-tag.yaml" to exist in the repository.
  80         (default: latest)
  81     :container-tag-yaml-dir: Directory with container-tag.yaml. (default: $DOCKER_ROOT)
  82     :docker-build-args: Additional arguments for the docker build command.
  83     :docker-get-container-tag-script: Pointer to script to handle docker tags.
  84         (default: ../shell/docker-get-container-tag.sh)
  85     :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root)
  86     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
  87     :pre_docker_build_script: Build script to execute before the main verify
  88         builder steps. (default: a string with only a comment)
  89     :post_docker_build_script: Build script to execute after the main verify
  90         builder steps. (default: a string with only a comment)
  91     :stream: Keyword that can be used to represent a release code-name.
  92         Often the same as the branch. (default: master)
  93     :submodule-recursive: Whether to checkout submodules recursively.
  94         (default: true)
  95     :submodule-timeout: Timeout (in minutes) for checkout operation.
  96         (default: 10)
  97
  98     :gerrit_verify_triggers: Override Gerrit Triggers.
  99     :gerrit_trigger_file_paths: Override Gerrit file paths which can be
 100         used to filter which file modifications will trigger a build.
 101     :github_included_regions: Override Github file paths which can be
 102         used to filter which file modifications will trigger a build;
 103         must match parameter gerrit_trigger_file_paths
 104
 105
 106 container-tag.yaml example:
 107
 108 .. code-block:: yaml
 109
 110    ---
 111    tag: 1.0.0
 112
 113 Docker Merge
 114 ------------
 115
 116 Executes a docker build task and publishes the resulting images to a specified Docker registry.
 117
 118 :Template Names:
 119
 120     - {project-name}-docker-merge-{stream}
 121     - gerrit-docker-merge
 122     - github-docker-merge
 123
 124 :Comment Trigger: **remerge** post a comment with the trigger to launch
 125     this job manually. Do not include any other text or vote in the
 126     same comment.
 127
 128 :Required parameters:
 129
 130     :build-node: The node to run build on.
 131     :container-public-registry: Docker registry source with base images.
 132     :container-push-registry: Docker registry target for the deploy action.
 133     :docker-name: Name of the Docker image.
 134     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 135         be configured in defaults.yaml)
 136     :mvn-settings: Maven settings.xml file containing credentials to use.
 137
 138 :Optional parameters:
 139
 140     :branch: Git branch to fetch for the build. (default: master)
 141     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 142     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 143     :container-tag-method: Specifies the docker tag-choosing method.
 144         Options are "latest", "git-describe" or "yaml-file".
 145         Option git-describe requires a git tag to exist in the repository.
 146         Option yaml-file requires a file "container-tag.yaml" to exist in the repository.
 147         (default: latest)
 148     :container-tag-yaml-dir: Directory with container-tag.yaml. (default: $DOCKER_ROOT)
 149     :cron: Cron schedule when to trigger the job. This parameter also
 150         supports multiline input via YAML pipe | character in cases where
 151         one may want to provide more than 1 cron timer. No default. Use
 152         '@daily' to run daily or 'H H * * 0' to run weekly.
 153     :docker-build-args: Additional arguments for the docker build command.
 154     :docker-get-container-tag-script: Pointer to script to handle docker tags.
 155         (default: ../shell/docker-get-container-tag.sh)
 156     :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root)
 157     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 158     :pre_docker_build_script: Build script to execute before the main merge
 159         builder steps. (default: a string with only a comment)
 160     :post_docker_build_script: Build script to execute after the main merge
 161         builder steps. (default: a string with only a comment)
 162     :stream: Keyword that can be used to represent a release code-name.
 163         Often the same as the branch. (default: master)
 164     :submodule-recursive: Whether to checkout submodules recursively.
 165         (default: true)
 166     :submodule-timeout: Timeout (in minutes) for checkout operation.
 167         (default: 10)
 168
 169     :gerrit_merge_triggers: Override Gerrit Triggers.
 170     :gerrit_trigger_file_paths: Override Gerrit file paths which can be
 171         used to filter which file modifications will trigger a build.
 172     :github_included_regions: Override Github file paths which can be
 173         used to filter which file modifications will trigger a build;
 174         must match parameter gerrit_trigger_file_paths
 175
 176 Sample container-tag.yaml File
 177 ------------------------------
 178
 179 .. code-block:: yaml
 180
 181    ---
 182    tag: 1.0.0