Container Roles

build-docker-image

Build one or more docker images.

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

The build-docker-image role is designed to be used in check and gate pipelines and simply builds the images. It can be used to verify that the build functions, or it can be followed by the use of subsequent roles to upload the images to Docker Hub.

The upload-docker-image role uploads the images to Docker Hub, but only with a single tag corresponding to the change ID. This role is designed to be used in a job 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 role 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.

Use the install-docker role to install Docker before using this role.

Role Variables

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

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

docker_dockerfile
Default: Dockerfile

The default Dockerfile name to use. Serves as the base for build-docker-image.docker_images.dockerfile. This allows a global overriding of Dockerfile name, for example when building all images from different folders with similarily named dockerfiles.

docker_credentials
Type: dict

This is only required for the upload and promote roles. This is expected to be a Zuul Secret with two 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 }}.*"
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[].dockerfile

The filename of the dockerfile, present in the context folder, used for building the image. Provide this if you are using a non-standard filename for a specific image.

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.

deploy-openshift

Deploy openshift using oc cluster up.

install-docker

An ansible role to install docker and configure it to use mirrors if available.

Role Variables

mirror_fqdn
Default: {{ zuul_site_mirror_fqdn }}

The base host for mirror servers.

docker_mirror

URL to override the generated docker hub mirror url based on install-docker.mirror_fqdn.

use_upstream_docker
Default: True

By default this role adds repositories to install docker from upstream docker. Set this to False to use the docker that comes with the distro.

docker_update_channel
Default: stable

Which update channel to use for upstream docker. The two choices are stable, which is the default and updates quarterly, and edge which updates monthly.

docker_version
Default: undefined

Declare this with the version of the docker package to install. Undefined will install the latest. This will look something like 18.06.1~ce~3-0~ubuntu. Only supported when using upstream docker repos.

docker_insecure_registries
Default: undefined

Declare this with a list of insecure registries to define the registries which are allowed to communicate with HTTP only or HTTPS with no valid certificate.

install-kubernetes

An ansible role to install kubernetes.

Role Variables

install_kubernetes_with_cluster
Default: True

If true, installs a Minikube cluster.

minikube_version
Default: latest

The version of Minikube to install.

install-openshift

Setup openshift requirements and pull the container images. The deploy-openshift role can be used to start the services.

This role only works on CentOS.

Role Variables

origin_repo
Default: centos-release-openshift-origin39

The origin repository.

origin_version
Default: v3.9.0

The origin version.

promote-docker-image

Promote one or more previously uploaded docker images.

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

The build-docker-image role is designed to be used in check and gate pipelines and simply builds the images. It can be used to verify that the build functions, or it can be followed by the use of subsequent roles to upload the images to Docker Hub.

The upload-docker-image role uploads the images to Docker Hub, but only with a single tag corresponding to the change ID. This role is designed to be used in a job 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 role 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.

Use the install-docker role to install Docker before using this role.

Role Variables

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

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

docker_dockerfile
Default: Dockerfile

The default Dockerfile name to use. Serves as the base for build-docker-image.docker_images.dockerfile. This allows a global overriding of Dockerfile name, for example when building all images from different folders with similarily named dockerfiles.

docker_credentials
Type: dict

This is only required for the upload and promote roles. This is expected to be a Zuul Secret with two 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 }}.*"
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[].dockerfile

The filename of the dockerfile, present in the context folder, used for building the image. Provide this if you are using a non-standard filename for a specific image.

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.

pull-from-intermediate-registry

Pull artifacts from the intermediate registry

This role will pull any artifacts built for changes ahead of this change which have been placed in an intermediate registry into the buildset registry for this buildset.

Run this in a trusted pre-playbook at the start of a job (which, in the case of multiple dependent jobs in a buildset, should be at the root of the job dependency graph).

This requires the run-buildset-registry role already applied. It also requires an externally managed “intermediate” registry operating for the use of Zuul, and it requires “skopeo” to be installed on the Zuul executors.

Role Variables

buildset_registry

Information about the registry, as returned by run-buildset-registry.

buildset_registry.host

The host (IP address) of the registry.

buildset_registry.port

The port on which the registry is listening.

buildset_registry.username

The username used to access the registry via HTTP basic auth.

buildset_registry.password

The password used to access the registry via HTTP basic auth.

buildset_registry.cert

The (self-signed) certificate used by the registry.

intermediate_registry

Information about the registry. This is expected to be provided as a secret.

intermediate_registry.host

The host (IP address) of the registry.

intermediate_registry.port

The port on which the registry is listening.

intermediate_registry.username

The username used to access the registry via HTTP basic auth.

intermediate_registry.password

The password used to access the registry via HTTP basic auth.

push-to-intermediate-registry

Push artifacts to the intermediate registry

This role will push any images built by build-docker-image into an intermediate registry.

Run this in a trusted post-playbook at the end of a job after the image build.

This requires the run-buildset-registry role already applied. It also requires an externally managed “intermediate” registry operating for the use of Zuul, and it requires “skopeo” to be installed on the Zuul executors.

Role Variables

buildset_registry

Information about the registry, as returned by run-buildset-registry.

buildset_registry.host

The host (IP address) of the registry.

buildset_registry.port

The port on which the registry is listening.

buildset_registry.username

The username used to access the registry via HTTP basic auth.

buildset_registry.password

The password used to access the registry via HTTP basic auth.

buildset_registry.cert

The (self-signed) certificate used by the registry.

intermediate_registry

Information about the registry. This is expected to be provided as a secret.

intermediate_registry.host

The host (IP address) of the registry.

intermediate_registry.port

The port on which the registry is listening.

intermediate_registry.username

The username used to access the registry via HTTP basic auth.

intermediate_registry.password

The password used to access the registry via HTTP basic auth.

docker_images
Type: list

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

docker_images[].repository

The name of the target repository for the image.

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

A list of tags to be added to the image.

run-buildset-registry

Runs a docker registry for the use of this buildset.

This may be used for a single job running on a single node, or it may be used at the root of a job graph so that multiple jobs running for a single change can share the registry. Two registry endpoints are provided – one is a local registry, the second is an upstream proxy.

Role Variables

buildset_registry_root
Default: {{ ansible_user_dir }}/buildset_registry

Path for the registry volumes.

Return Values

buildset_registry

Information about the registry.

buildset_registry.host

The host (IP address) of the registry.

buildset_registry.port

The port on which the registry is listening.

buildset_registry.proxy_port

The port on which the proxy is listening.

buildset_registry.username

The username used to access the registry via HTTP basic auth.

buildset_registry.password

The password used to access the registry via HTTP basic auth.

buildset_registry.cert

The (self-signed) certificate used by the registry.

upload-docker-image

Upload one or more docker images.

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

The build-docker-image role is designed to be used in check and gate pipelines and simply builds the images. It can be used to verify that the build functions, or it can be followed by the use of subsequent roles to upload the images to Docker Hub.

The upload-docker-image role uploads the images to Docker Hub, but only with a single tag corresponding to the change ID. This role is designed to be used in a job 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 role 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.

Use the install-docker role to install Docker before using this role.

Role Variables

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

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

docker_dockerfile
Default: Dockerfile

The default Dockerfile name to use. Serves as the base for build-docker-image.docker_images.dockerfile. This allows a global overriding of Dockerfile name, for example when building all images from different folders with similarily named dockerfiles.

docker_credentials
Type: dict

This is only required for the upload and promote roles. This is expected to be a Zuul Secret with two 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 }}.*"
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[].dockerfile

The filename of the dockerfile, present in the context folder, used for building the image. Provide this if you are using a non-standard filename for a specific image.

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.

use-buildset-registry

Adds a buildset registry to the docker configuration.

Use this role on any host which should use the buildset registry.

Role Variables

buildset_registry

Information about the registry, as returned by run-buildset-registry.

buildset_registry.host

The host (IP address) of the registry.

buildset_registry.port

The port on which the registry is listening.

buildset_registry.proxy_port

The port on which the registry proxy is listening.

buildset_registry.username

The username used to access the registry via HTTP basic auth.

buildset_registry.password

The password used to access the registry via HTTP basic auth.

buildset_registry.cert

The (self-signed) certificate used by the registry.

buildset_registry_docker_user
Default: {{ ansible_user }}

The system user to configure to use the docker registry. The docker configuration file for this user will be updated. By default, the user Ansible is running as.

use-docker-mirror

Configure docker to use mirrors if available.

Role Variables

mirror_fqdn
Default: {{ zuul_site_mirror_fqdn }}

The base host for mirror servers.

docker_mirror

URL to override the generated docker hub mirror url based on install-docker.mirror_fqdn.

docker_insecure_registries
Default: undefined

Declare this with a list of insecure registries to define the registries which are allowed to communicate with HTTP only or HTTPS with no valid certificate.