Docker Jobs

build-docker-image

Build a docker image.

This is one of a collection of jobs which are designed to work together to build, upload, and promote docker images in a gating context:

The build-docker-image job is designed to be used in a check pipeline and simply builds the images to verify that the build functions.

The upload-docker-image job builds and uploads the images to Docker Hub, but only with a single tag corresponding to the change ID. This job is designed in a gate pipeline so that the build produced by the gate is staged and can later be promoted to production if the change is successful.

The promote-docker-image job is designed to be used in a promote pipeline. It requires no nodes and runs very quickly on the Zuul executor. It simply re-tags a previously uploaded image for a change with whatever tags are supplied by build-docker-image.docker_images.tags. It also removes the change ID tag from the repository in Docker Hub, and removes any similar change ID tags more than 24 hours old. This keeps the repository tidy in the case that gated changes fail to merge after uploading their staged images.

They all accept the same input data, principally a list of dictionaries representing the images to build. YAML anchors can be used to supply the same data to all three jobs.

Job Variables

zuul_work_dir
Default: {{ zuul.project.src_dir }}

The project directory. Serves as the base for build-docker-image.docker_images.context.

docker_images
Type: list

A list of images to build. Each item in the list should have:

docker_images[].context

The docker build context; this should be a directory underneath build-docker-image.zuul_work_dir.

docker_images[].repository

The name of the target repository in dockerhub for the image. Supply this even if the image is not going to be uploaded (it will be tagged with this in the local registry).

docker_images[].path

Optional: the directory that should be passed to docker build. Useful for building images with a Dockerfile in the context directory but a source repository elsewhere.

docker_images[].build_args
Type: list

Optional: a list of values to pass to the docker --build-arg parameter.

docker_images[].target

Optional: the target for a multi-stage build.

docker_images[].tags
Default: ['latest']
Type: list

A list of tags to be added to the image when promoted.

upload-docker-image

Build and upload a docker image.

This is one of a collection of jobs which are designed to work together to build, upload, and promote docker images in a gating context:

The build-docker-image job is designed to be used in a check pipeline and simply builds the images to verify that the build functions.

The upload-docker-image job builds and uploads the images to Docker Hub, but only with a single tag corresponding to the change ID. This job is designed in a gate pipeline so that the build produced by the gate is staged and can later be promoted to production if the change is successful.

The promote-docker-image job is designed to be used in a promote pipeline. It requires no nodes and runs very quickly on the Zuul executor. It simply re-tags a previously uploaded image for a change with whatever tags are supplied by build-docker-image.docker_images.tags. It also removes the change ID tag from the repository in Docker Hub, and removes any similar change ID tags more than 24 hours old. This keeps the repository tidy in the case that gated changes fail to merge after uploading their staged images.

They all accept the same input data, principally a list of dictionaries representing the images to build. YAML anchors can be used to supply the same data to all three jobs.

Job Variables

zuul_work_dir
Default: {{ zuul.project.src_dir }}

The project directory. Serves as the base for build-docker-image.docker_images.context.

docker_images
Type: list

A list of images to build. Each item in the list should have:

docker_images[].context

The docker build context; this should be a directory underneath build-docker-image.zuul_work_dir.

docker_images[].repository

The name of the target repository in dockerhub for the image. Supply this even if the image is not going to be uploaded (it will be tagged with this in the local registry).

docker_images[].path

Optional: the directory that should be passed to docker build. Useful for building images with a Dockerfile in the context directory but a source repository elsewhere.

docker_images[].build_args
Type: list

Optional: a list of values to pass to the docker --build-arg parameter.

docker_images[].target

Optional: the target for a multi-stage build.

docker_images[].tags
Default: ['latest']
Type: list

A list of tags to be added to the image when promoted.

docker_credentials
Type: dict

This is expected to be a Zuul Secret with these keys:

docker_credentials{}.username

The Docker Hub username.

docker_credentials{}.password

The Docker Hub password.

docker_credentials{}.repository

Optional; if supplied this is a regular expression which restricts to what repositories the image may be uploaded. The following example allows projects to upload images to repositories within an organization based on their own names:

repository: "^myorgname/{{ zuul.project.short_name }}.*"
promote-docker-image

Retag a previously-uploaded docker image.

This is one of a collection of jobs which are designed to work together to build, upload, and promote docker images in a gating context:

The build-docker-image job is designed to be used in a check pipeline and simply builds the images to verify that the build functions.

The upload-docker-image job builds and uploads the images to Docker Hub, but only with a single tag corresponding to the change ID. This job is designed in a gate pipeline so that the build produced by the gate is staged and can later be promoted to production if the change is successful.

The promote-docker-image job is designed to be used in a promote pipeline. It requires no nodes and runs very quickly on the Zuul executor. It simply re-tags a previously uploaded image for a change with whatever tags are supplied by build-docker-image.docker_images.tags. It also removes the change ID tag from the repository in Docker Hub, and removes any similar change ID tags more than 24 hours old. This keeps the repository tidy in the case that gated changes fail to merge after uploading their staged images.

They all accept the same input data, principally a list of dictionaries representing the images to build. YAML anchors can be used to supply the same data to all three jobs.

Job Variables

zuul_work_dir
Default: {{ zuul.project.src_dir }}

The project directory. Serves as the base for build-docker-image.docker_images.context.

docker_images
Type: list

A list of images to build. Each item in the list should have:

docker_images[].context

The docker build context; this should be a directory underneath build-docker-image.zuul_work_dir.

docker_images[].repository

The name of the target repository in dockerhub for the image. Supply this even if the image is not going to be uploaded (it will be tagged with this in the local registry).

docker_images[].path

Optional: the directory that should be passed to docker build. Useful for building images with a Dockerfile in the context directory but a source repository elsewhere.

docker_images[].build_args
Type: list

Optional: a list of values to pass to the docker --build-arg parameter.

docker_images[].target

Optional: the target for a multi-stage build.

docker_images[].tags
Default: ['latest']
Type: list

A list of tags to be added to the image when promoted.

docker_credentials
Type: dict

This is expected to be a Zuul Secret with these keys:

docker_credentials{}.username

The Docker Hub username.

docker_credentials{}.password

The Docker Hub password.

docker_credentials{}.repository

Optional; if supplied this is a regular expression which restricts to what repositories the image may be uploaded. The following example allows projects to upload images to repositories within an organization based on their own names:

repository: "^myorgname/{{ zuul.project.short_name }}.*"