Container Registry and Images

This module deals with the container registry that belongs to a Rescale Project. The container registry holds container images, that are later used by Rescale to pull images to run.

Common use cases for this module is to fetch container registry authentication tokens so that new images can be docker pushed to the registry. You can also push docker images using functions on this object, create repositories, and list/delete images from the registry.

class rescalehtc.container_registry.HtcContainerRegistry(project, registry_url, login_method, username, token)

Class that holds information about a container registry. This info is commonly used to docker login, which enables docker push and docker pull of container images.

Use the function rescalehtc.container_registry.get_container_registry() to create this object.

The container registry token should be accessed through the rescalehtc.container_registry.HtcContainerRegistry.get_token() function, as keys may expire and require renewal (handled transparently by this class).

get_images(rescale: HtcSession) → list[str]

List all image names available in this container registry.

push_docker_image(rescale: HtcSession, local_image_name: str, remote_image_name: str | None = None, quiet: bool = False) → str

Helper function to push a local docker image to the remote Rescale container registry. The new remote docker image name is returned, use this name when submitting jobs later.

The docker image must exist locally. If it is a remote image, run docker pull <imagename> first.

This function invokes subprocess to run docker commands. It relies on docker being possible to run as the non-root user, described in https://docs.docker.com/engine/install/linux-postinstall/.

Authentication towards the docker registry happens automatically. Repo creation is also handled automatically.

By default, this function creates a unique remote image name. The name is uniquified with the image hash to avoid problems with reusing existing image tags and slow replication causing older images to be picked. To set your own remote image name, override the remote_image_name field.

This function shows the stdout from the docker subprocess commands being run. To mute these, set quiet=True.

get_image(rescale: HtcSession, image_name: str) → dict

Show information about a container image with a specific name. Currently in the API this only returns a dict with 1 element: “status” : “PENDING” or “READY”, indicating whether the image is ready for use or not.

is_image_ready(rescale: HtcSession, image_name: str) → bool

Returns true if the status of the container image is READY, otherwise false. An image in READY status can be used by rescale jobs.

Use this function after pushing a new container image and before submitting jobs to Rescale. Attempting to start a job with an image in PENDING state causes a HtcException during job submission.

Note that state READY does not guarantee you get the latest image, just that an image with this name is available in the repository.

delete_image(rescale: HtcSession, image_name: str) → bool

Deletes an image from the container registry.

get_repos(rescale: HtcSession) → list[str]

List all container repositories that have been created in this container registry.

create_repo(rescale: HtcSession, container_repo_name: str) → dict

Create a container image repo in this container registry with the specified name.

get_token(rescale: HtcSession) → str

Get a non-expired token for this container registry.

TODO: Handle renewal of container registry tokens when they expire. For now this function just returns the token from when this object was created.

rescalehtc.container_registry.get_container_registry(rescale: HtcSession, project: HtcProject) → HtcContainerRegistry

Get the container registry information needed to us it. This returns information such as the URL to the container registry, and the user name and password used to log into it.

This function returns a HtcContainerRegistry object.