X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=blobdiff_plain;f=docs%2Fjjb%2Flf-docker-jobs.rst;h=0a6fcc9a7c4b729d72c304385b13fb6b6c294c37;hb=35e5c8dbf87dc8657bfa1c2631d641f56d81ed07;hp=fd2319584b361fd9aea17f05644e764202839937;hpb=d88144f9f1d5a04989726ab5755c40db5cbc0803;p=releng%2Fglobal-jjb.git diff --git a/docs/jjb/lf-docker-jobs.rst b/docs/jjb/lf-docker-jobs.rst index fd231958..0a6fcc9a 100644 --- a/docs/jjb/lf-docker-jobs.rst +++ b/docs/jjb/lf-docker-jobs.rst @@ -19,8 +19,45 @@ Macros lf-docker-get-container-tag --------------------------- -Calls docker-get-git-describe.sh or docker-get-yaml-tag.sh (depending on the -'docker-use-params-from' condition) to obtain the tag to build. +Chooses a tag to label the container image based on the +'container-tag-method' parameter using the global-jjb script +docker-get-container-tag.sh. Use one of the following methods: + +If ``container-tag-method: latest``, uses the literal string ``latest``. + +If ``container-tag-method: stream``, uses the value of the variable ``stream``. + +If ``container-tag-method: git-describe``, reads the tag from the +``git describe`` command on the repository, which requires that the repository +has a git tag. For example, if the most recent tag is 'v0.48.1', this +method yields a string like 'v0.48.1' or 'v0.48.1-25-gaee2dcb'. + +If ``container-tag-method: yaml-file``, reads the tag from the YAML file +``container-tag.yaml`` in the docker-root directory using the top-level entry +'tag'. Alternately specify the directory with the YAML file in parameter +'container-tag-yaml-dir'. An example file appears next. + +Example container-tag.yaml file: + +.. code-block:: yaml + + --- + tag: 1.0.0 + + +Optionally, teams can supply their own script to choose the docker +tag. Pass the shell script path in optional configuration parameter +'docker-get-container-tag-script' which by default is the path to +file docker-get-container-tag.sh. The script must create the file +'env_docker_inject.txt' in the workspace with a line that assigns a +value to shell variable DOCKER_IMAGE_TAG, as shown next. + +Example env_docker_inject.txt file: + +.. code-block:: shell + + DOCKER_IMAGE_TAG=1.0.0 + lf-docker-build --------------- @@ -38,7 +75,8 @@ Job Templates Docker Verify ------------- -Executes a docker build task. +Executes a docker build task to verify an test image build and discards the +test image upon completion. :Template Names: @@ -46,33 +84,42 @@ Executes a docker build task. - gerrit-docker-verify - github-docker-verify -:Comment Trigger: recheck|reverify +:Comment Trigger: **recheck|reverify** post a comment with one of the + triggers to launch this job manually. Do not include any other + text or vote in the same comment. :Required parameters: :build-node: The node to run build on. :container-public-registry: Docker registry source with base images. :docker-name: Name of the Docker image. - :docker-use-params-from: Used to select the source of the tag information. - Options are "git-describe-params" or "yaml-file-params". (yaml-file-params - expects the tag to be defined in a local file "container-tag.yaml"). - :jenkins-ssh-credential: Credential to use for SSH. (Generally should - be configured in defaults.yaml) - :mvn-settings: Maven settings.xml file containing credentials to use. + :jenkins-ssh-credential: Credential to use for SSH. (Generally configured + in defaults.yaml) + :mvn-settings: Maven settings.xml file containing Docker credentials. :Optional parameters: :branch: Git branch to fetch for the build. (default: master) :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7) :build-timeout: Timeout in minutes before aborting build. (default: 60) - :docker-build-args: Additional arguments for the docker build command. - :docker-root: Path of the Dockerfile within the repo. + :container-tag-method: Specifies the docker tag-choosing method. + Options are "latest", "git-describe" or "yaml-file". + Option latest uses the "latest" tag. + Option git-describe uses the string returned by git-describe, + which requires a tag to exist in the repository. + Option yaml-file uses the string from file "container-tag.yaml" + in the repository. (default: latest) + :container-tag-yaml-dir: Directory with container-tag.yaml. (default: $DOCKER_ROOT) + :docker-build-args: Arguments for the docker build command. + :docker-get-container-tag-script: Path to script that chooses docker tag. + (default: ../shell/docker-get-container-tag.sh in global-jjb) + :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root) :git-url: URL clone project from. (default: $GIT_URL/$PROJECT) - :pre_docker_build_script: Optional build script to execute before the main verify - builder steps. - :post_docker_build_script: Optional build script to execute after the main verify - builder steps. - :stream: Keyword that can be used to represent a release code-name. + :pre_docker_build_script: Build script to execute before the main verify + builder steps. (default: "") + :post_docker_build_script: Build script to execute after the main verify + builder steps. (default: "") + :stream: Keyword that represents a release code-name. Often the same as the branch. (default: master) :submodule-recursive: Whether to checkout submodules recursively. (default: true) @@ -80,11 +127,11 @@ Executes a docker build task. (default: 10) :gerrit_verify_triggers: Override Gerrit Triggers. - :gerrit_trigger_file_paths: Override Gerrit file paths which can be - used to filter which file modifications will trigger a build. - :github_included_regions: Override Github file paths which can be - used to filter which file modifications will trigger a build; - must match parameter gerrit_trigger_file_paths + :gerrit_trigger_file_paths: Override Gerrit file paths to filter which file + modifications will trigger a build. + :github_included_regions: Override Github file paths to filter which file + modifications will trigger a build; must match parameter + gerrit_trigger_file_paths container-tag.yaml example: @@ -97,7 +144,9 @@ container-tag.yaml example: Docker Merge ------------ -Executes a docker build task and publishes the resulting images to a specified Docker registry. +Executes a docker build task and pushes the resulting image to the specified +Docker registry. If every image is a release candidate, this should use a +staging repository and occassionally run to check dependencies. :Template Names: @@ -105,34 +154,47 @@ Executes a docker build task and publishes the resulting images to a specified D - gerrit-docker-merge - github-docker-merge -:Comment Trigger: remerge +:Comment Trigger: **remerge** post a comment with the trigger to launch + this job manually. Do not include any other text or vote in the + same comment. :Required parameters: :build-node: The node to run build on. :container-public-registry: Docker registry source with base images. - :container-push-registry: Docker registry target for the deploy action. + :container-push-registry: Docker registry target for the push action. :docker-name: Name of the Docker image. - :docker-use-params-from: Used to select the source of the tag information. - Options are "git-describe-params" or "yaml-file-params". (yaml-file-params - expects the tag to be defined in a local file "container-tag.yaml"). - :jenkins-ssh-credential: Credential to use for SSH. (Generally should - be configured in defaults.yaml) - :mvn-settings: Maven settings.xml file containing credentials to use. + :jenkins-ssh-credential: Credential to use for SSH. (Generally configured + in defaults.yaml) + :mvn-settings: Maven settings.xml file containing Docker credentials. :Optional parameters: :branch: Git branch to fetch for the build. (default: master) :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7) :build-timeout: Timeout in minutes before aborting build. (default: 60) - :docker-build-args: Additional arguments for the docker build command. - :docker-root: Path of the Dockerfile within the repo. + :container-tag-method: Specifies the docker tag-choosing method. + Options are "latest", "git-describe" or "yaml-file". + Option latest uses the "latest" tag. + Option git-describe uses the string returned by git-describe, + which requires a tag to exist in the repository. + Option yaml-file uses the string from file "container-tag.yaml" + in the repository. (default: latest) + :container-tag-yaml-dir: Directory with container-tag.yaml. (default: $DOCKER_ROOT) + :cron: Cron schedule when to trigger the job. This parameter also + supports multiline input via YAML pipe | character in cases where + one may want to provide more than 1 cron timer. Use '@daily' to run + daily or '@weekly' to run weekly. (default: @weekly) + :docker-build-args: Arguments for the docker build command. + :docker-get-container-tag-script: Path to script that chooses docker tag. + (default: ../shell/docker-get-container-tag.sh in global-jjb) + :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root) :git-url: URL clone project from. (default: $GIT_URL/$PROJECT) - :pre_docker_build_script: Optional build script to execute before the main merge - builder steps. - :post_docker_build_script: Optional build script to execute after the main merge - builder steps. - :stream: Keyword that can be used to represent a release code-name. + :pre_docker_build_script: Build script to execute before the main merge + builder steps. (default: "") + :post_docker_build_script: Build script to execute after the main merge + builder steps. (default: "") + :stream: Keyword that represents a release code-name. Often the same as the branch. (default: master) :submodule-recursive: Whether to checkout submodules recursively. (default: true) @@ -140,15 +202,72 @@ Executes a docker build task and publishes the resulting images to a specified D (default: 10) :gerrit_merge_triggers: Override Gerrit Triggers. - :gerrit_trigger_file_paths: Override Gerrit file paths which can be - used to filter which file modifications will trigger a build. - :github_included_regions: Override Github file paths which can be - used to filter which file modifications will trigger a build; - must match parameter gerrit_trigger_file_paths + :gerrit_trigger_file_paths: Override Gerrit file paths to filter which file + modifications will trigger a build. + :github_included_regions: Override GitHub file paths to filter which file + modifications will trigger a build; must match parameter + gerrit_trigger_file_paths -container-tag.yaml example: +Sample container-tag.yaml File +------------------------------ .. code-block:: yaml --- tag: 1.0.0 + +Docker Snyk CLI +--------------- + +Builds the code, downloads and runs a Snyk CLI scan of the code into the Snyk dashboard. + +:Template Names: + + - {project-name}-docker-snyk-cli-{stream} + - gerrit-docker-snyk-cli + - github-docker-snyk-cli + +:Comment Trigger: run-snyk + +:Required parameters: + + :build-node: The node to run build on. + :container-public-registry: Docker registry source with base images. + :docker-name: Name of the Docker image. + :jenkins-ssh-credential: Credential to use for SSH. (Generally configured + in defaults.yaml) + :mvn-settings: Maven settings.xml file containing Docker credentials. + :snyk-token-credential-id: Snyk API token to communicate with Jenkins. + :snyk-org-credential-id: Snyk organization ID. + +:Optional parameters: + + :branch: Git branch to fetch for the build. (default: master) + :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7) + :build-timeout: Timeout in minutes before aborting build. (default: 60) + :container-tag-method: Specifies the docker tag-choosing method. + Options are "latest", "git-describe" or "yaml-file". + Option latest uses the "latest" tag. + Option git-describe uses the string returned by git-describe, + which requires a tag to exist in the repository. + Option yaml-file uses the string from file "container-tag.yaml" + in the repository. (default: latest) + :container-tag-yaml-dir: Directory with container-tag.yaml. (default: $DOCKER_ROOT) + :docker-build-args: Arguments for the docker build command. + :docker-get-container-tag-script: Path to script that chooses docker tag. + (default: ../shell/docker-get-container-tag.sh in global-jjb) + :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root) + :git-url: URL clone project from. (default: $GIT_URL/$PROJECT) + :pre_docker_build_script: Build script to execute before the main verify + builder steps. (default: "") + :post_docker_build_script: Build script to execute after the main verify + builder steps. (default: "") + :snyk-cli-options: Snyk CLI options. (default: '') + :stream: Keyword that represents a release code-name. + Often the same as the branch. (default: master) + :submodule-recursive: Whether to checkout submodules recursively. + (default: true) + :submodule-timeout: Timeout (in minutes) for checkout operation. + (default: 10) + + :gerrit_snyk_triggers: Override Gerrit Triggers.