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