Container Roles

build-container-image

Build one or more container images.

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

Note

Build and upload roles are forthcoming.

The build-container-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 a registry.

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 or install-podman role to install Docker or Podman before using these roles.

Role Variables

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

The project directory. Serves as the base for build-container-image.container_images.context.

container_filename

The default container filename name to use. Serves as the base for build-container-image.container_images.container_filename. This allows a global overriding of the container filename name, for example when building all images from different folders with similarily named containerfiles.

If omitted, the default depends on the container command used. Typically, this is Dockerfile for docker and Containerfile (with a fallback on Dockerfile) for podman.

container_command
Default: podman

The command to use when building the image (E.g., docker).

container_registry_credentials
Type: dict

This is only required for the upload and promote roles. This is expected to be a Zuul Secret in dictionary form. Each key is the name of a registry, and its value a dictionary with information about that registry.

Example:

container_registry_credentials:
  quay.io:
    username: foo
    password: bar
container_registry_credentials{}.[registry name]
Type: dict

Information about a registry. The key is the registry name, and its value a dict as follows:

container_registry_credentials{}.[registry name]{}.username

The registry username.

container_registry_credentials{}.[registry name]{}.password

The registry password.

container_registry_credentials{}.[registry name]{}.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 }}.*"
container_images
Type: list

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

container_images[].context

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

container_images[].container_filename

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

container_images[].registry

The name of the target registry (E.g., quay.io). Used by the upload and promote roles.

container_images[].repository

The name of the target repository in the registry 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).

container_images[].path

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

container_images[].build_args
Type: list

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

container_images[].target

Optional: the target for a multi-stage build.

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

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

container_images[].siblings
Default: []
Type: list

A list of sibling projects to be copied into {{zuul_work_dir}}/.zuul-siblings. This can be useful to collect multiple projects to be installed within the same Docker context. A -build-arg called ZUUL_SIBLINGS will be added with each sibling project. Note that projects here must be listed in required-projects.

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.

docker_images[].siblings
Default: []
Type: list

A list of sibling projects to be copied into {{zuul_work_dir}}/.zuul-siblings. This can be useful to collect multiple projects to be installed within the same Docker context. A -build-arg called ZUUL_SIBLINGS will be added with each sibling project. Note that projects here must be listed in required-projects.

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_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.

docker_gpg_key
Default: string

The raw content of the upstream docker gpg key, as found here https://download.docker.com/linux/fedora/gpg

docker_distro_packages
Default: list

List of packages to be installed when use_upstream_docker is set to false. The package set is defined by default using distro specific variables. If the package set needs to be changed this option can be overridden as needed.

docker_upstream_distro_required_packages
Default: list

List of packages to be installed when use_upstream_docker is set to true. The package set is defined by default using distro specific variables and contains a list of supporting packages required to be installed prior to installing docker-ce. If the package set needs to be changed this option can be overridden as needed.

docker_upstream_distro_packages
Default: list

List of packages to be installed when use_upstream_docker is set to true. The package set is defined by default using distro specific variables. If the package set needs to be changed this option can be overridden as needed.

docker_download_fqdn
Default: download.docker.com

Add default option to set the docker download fqdn.

docker_mirror_base_url
Default: https://{{ docker_download_fqdn }}/linux/{ubuntu,centos,fedora}

By default this option sets the repository base url. This variable is based on install-docker.docker_download_fqdn. When this option is unset, the role will use distro specific variables which are loaded at the time of execution.

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.

minikube_dns_resolvers
Default: []

List of dns resolvers to configure in k8s. Use this to override the resolvers that are found by default.

kubernetes_runtime
Default: docker

Which kubernetes runtime to use; values are docker or cri-o.

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.

install-podman

Install podman container manager

Role Variables

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.

docker_images[].siblings
Default: []
Type: list

A list of sibling projects to be copied into {{zuul_work_dir}}/.zuul-siblings. This can be useful to collect multiple projects to be installed within the same Docker context. A -build-arg called ZUUL_SIBLINGS will be added with each sibling project. Note that projects here must be listed in required-projects.

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” and “socat” 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” and “socat” 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 container 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.

Role Variables

buildset_registry_root
Default: {{ ansible_user_dir }}/buildset_registry

Path for the registry volumes.

buildset_registry_port
Default: 5000

The port on which the registry should listen.

container_command
Default: docker

The command to use to run the registry container (E.g., podman).

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.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.

docker_images[].siblings
Default: []
Type: list

A list of sibling projects to be copied into {{zuul_work_dir}}/.zuul-siblings. This can be useful to collect multiple projects to be installed within the same Docker context. A -build-arg called ZUUL_SIBLINGS will be added with each sibling project. Note that projects here must be listed in required-projects.

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.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.

buildset_registry_namespaces
Default: ['docker.io', 'quay.io', 'gcr.io']

The namespaces that the buildset registry supports. The buildset registry will be consulted first for images in these namespaces. Any others will be fetched only from their upstream sources.

Add any local or third-party registries necessary here.

The default may change in the future as more general-purpose public registries become known.

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.