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 tag to label the container image based on the
  23 'container-tag-method' parameter using the global-jjb script
  24 docker-get-container-tag.sh. Use one of the following methods:
  25
  26 If container-tag-method: latest, the literal string 'latest' is used.
  27
  28 If container-tag-method: git-describe, the tag is obtained using the
  29 git describe command on the repository, which requires that the repository
  30 has a git tag. For example, if the most recent tag is 'v0.48.1', this
  31 method yields a string like 'v0.48.1' or 'v0.48.1-25-gaee2dcb'.
  32
  33 If container-tag-method: yaml-file, the tag is obtained from the YAML file
  34 'container-tag.yaml' in the docker-root directory using the top-level entry
  35 'tag'. Alternately specify the directory with the YAML file in parameter
  36 'container-tag-yaml-dir'. An example file appears next.
  37
  38 Example container-tag.yaml file:
  39
  40 .. code-block:: yaml
  41
  42    ---
  43    tag: 1.0.0
  44
  45
  46 Optionally, teams can supply their own script to choose the docker
  47 tag. Pass the shell script path in optional configuration parameter
  48 'docker-get-container-tag-script' which by default is the path to
  49 file docker-get-container-tag.sh. The script must create the file
  50 'env_docker_inject.txt' in the workspace with a line that assigns a
  51 value to shell variable DOCKER_IMAGE_TAG, as shown next.
  52
  53 Example env_docker_inject.txt file:
  54
  55 .. code-block:: shell
  56
  57     DOCKER_IMAGE_TAG=1.0.0
  58
  59
  60 lf-docker-build
  61 ---------------
  62
  63 Calls docker build to build the container.
  64
  65 lf-docker-push
  66 --------------
  67
  68 Calls docker-push.sh script to push docker images.
  69
  70 Job Templates
  71 =============
  72
  73 Docker Verify
  74 -------------
  75
  76 Executes a docker build task to verify that an image can be constructed,
  77 and discards the image upon completion.
  78
  79 :Template Names:
  80
  81     - {project-name}-docker-verify-{stream}
  82     - gerrit-docker-verify
  83     - github-docker-verify
  84
  85 :Comment Trigger: **recheck|reverify** post a comment with one of the
  86     triggers to launch this job manually. Do not include any other
  87     text or vote in the same comment.
  88
  89 :Required parameters:
  90
  91     :build-node: The node to run build on.
  92     :container-public-registry: Docker registry source with base images.
  93     :docker-name: Name of the Docker image.
  94     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
  95         be configured in defaults.yaml)
  96     :mvn-settings: Maven settings.xml file containing Docker credentials.
  97
  98 :Optional parameters:
  99
 100     :branch: Git branch to fetch for the build. (default: master)
 101     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 102     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 103     :container-tag-method: Specifies the docker tag-choosing method.
 104         Options are "latest", "git-describe" or "yaml-file".
 105         Option latest simply applies that string.
 106         Option git-describe uses the string returned by git-describe,
 107         which requires a tag to exist in the repository.
 108         Option yaml-file uses the string from file "container-tag.yaml"
 109         in the repository. (default: latest)
 110     :container-tag-yaml-dir: Directory with container-tag.yaml. (default: $DOCKER_ROOT)
 111     :docker-build-args: Additional arguments for the docker build command.
 112     :docker-get-container-tag-script: Path to script that chooses docker tag.
 113         (default: ../shell/docker-get-container-tag.sh in global-jjb)
 114     :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root)
 115     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 116     :pre_docker_build_script: Build script to execute before the main verify
 117         builder steps. (default: a string with only a comment)
 118     :post_docker_build_script: Build script to execute after the main verify
 119         builder steps. (default: a string with only a comment)
 120     :stream: Keyword that can be used to represent a release code-name.
 121         Often the same as the branch. (default: master)
 122     :submodule-recursive: Whether to checkout submodules recursively.
 123         (default: true)
 124     :submodule-timeout: Timeout (in minutes) for checkout operation.
 125         (default: 10)
 126
 127     :gerrit_verify_triggers: Override Gerrit Triggers.
 128     :gerrit_trigger_file_paths: Override Gerrit file paths which can be
 129         used to filter which file modifications will trigger a build.
 130     :github_included_regions: Override Github file paths which can be
 131         used to filter which file modifications will trigger a build;
 132         must match parameter gerrit_trigger_file_paths
 133
 134
 135 container-tag.yaml example:
 136
 137 .. code-block:: yaml
 138
 139    ---
 140    tag: 1.0.0
 141
 142 Docker Merge
 143 ------------
 144
 145 Executes a docker build task and pushes the resulting image to the specified
 146 Docker registry. If every image is a release candidate, this should use a
 147 staging repository and should also run regularly to check dependencies.
 148
 149 :Template Names:
 150
 151     - {project-name}-docker-merge-{stream}
 152     - gerrit-docker-merge
 153     - github-docker-merge
 154
 155 :Comment Trigger: **remerge** post a comment with the trigger to launch
 156     this job manually. Do not include any other text or vote in the
 157     same comment.
 158
 159 :Required parameters:
 160
 161     :build-node: The node to run build on.
 162     :container-public-registry: Docker registry source with base images.
 163     :container-push-registry: Docker registry target for the push action.
 164     :docker-name: Name of the Docker image.
 165     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 166         be configured in defaults.yaml)
 167     :mvn-settings: Maven settings.xml file containing Docker credentials.
 168
 169 :Optional parameters:
 170
 171     :branch: Git branch to fetch for the build. (default: master)
 172     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 173     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 174     :container-tag-method: Specifies the docker tag-choosing method.
 175         Options are "latest", "git-describe" or "yaml-file".
 176         Option latest simply applies that string.
 177         Option git-describe uses the string returned by git-describe,
 178         which requires a tag to exist in the repository.
 179         Option yaml-file uses the string from file "container-tag.yaml"
 180         in the repository. (default: latest)
 181     :container-tag-yaml-dir: Directory with container-tag.yaml. (default: $DOCKER_ROOT)
 182     :cron: Cron schedule when to trigger the job. This parameter also
 183         supports multiline input via YAML pipe | character in cases where
 184         one may want to provide more than 1 cron timer. Use '@daily' to run
 185         daily or '@weekly' to run weekly.  (default: @weekly)
 186     :docker-build-args: Additional arguments for the docker build command.
 187     :docker-get-container-tag-script: Path to script that chooses docker tag.
 188         (default: ../shell/docker-get-container-tag.sh in global-jjb)
 189     :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root)
 190     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 191     :pre_docker_build_script: Build script to execute before the main merge
 192         builder steps. (default: a string with only a comment)
 193     :post_docker_build_script: Build script to execute after the main merge
 194         builder steps. (default: a string with only a comment)
 195     :stream: Keyword that can be used to represent a release code-name.
 196         Often the same as the branch. (default: master)
 197     :submodule-recursive: Whether to checkout submodules recursively.
 198         (default: true)
 199     :submodule-timeout: Timeout (in minutes) for checkout operation.
 200         (default: 10)
 201
 202     :gerrit_merge_triggers: Override Gerrit Triggers.
 203     :gerrit_trigger_file_paths: Override Gerrit file paths which can be
 204         used to filter which file modifications will trigger a build.
 205     :github_included_regions: Override Github file paths which can be
 206         used to filter which file modifications will trigger a build;
 207         must match parameter gerrit_trigger_file_paths
 208
 209 Sample container-tag.yaml File
 210 ------------------------------
 211
 212 .. code-block:: yaml
 213
 214    ---
 215    tag: 1.0.0