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