ImageService¶

class controller.services.image.ImageService(*, config, node_selector, tolerations, source, node_storage, slack_client=None, logger)¶

Bases: object

Service to track the available images for Jupyter labs.

There are two places that contain a list of known lab images:

The tags in the registry used as an image source. This is the full set of possible images; if it’s not on this list, it can’t be used. These are called the remote images.
The images cached on the Kubernetes cluster nodes. This is the preferred set of images, since spawning one of these images will be fast. These are called the cached images.

The lab controller is configured to prepull certain images to all nodes. That list is based on the registry tags, filtered by the prepuller configuration. This service provides the list of tags that should be prepulled, the ones that have been prepulled, and the full list of available tags. This information is then used by the prepuller to determine what work it needs to do and by the lab controller API to determine which images to display in the menu.

Parameters:

config (PrepullerOptions) – The prepuller configuration, used to determine which tags should be prepulled and some other related information.
node_selector (dict[str, str]) – Node selector rules to determine which nodes are eligible for prepulling.
tolerations (list[Toleration]) – Tolerations used to determine which nodes are eligible for prepulling.
source (ImageSource) – Source of remote images.
node_storage (NodeStorage) – Storage layer for Kubernetes nodes.
slack_client (SlackWebhookClient | None, default: None) – Optional Slack client to use for alerts.
logger (BoundLogger) – Logger for messages.

Methods Summary

`image_for_class`(image_class)	Determine the image by class keyword.
`image_for_reference`(reference)	Determine the image corresponding to a Docker reference.
`image_for_tag_name`(tag_name)	Determine the image corresponding to a tag.
`images`()	All images available for spawning.
`mark_prepulled`(image, node)	Indicate we believe we have prepulled an image to a node.
`menu_images`()	Images that should appear in the menu.
`missing_images_by_node`()	Determine what images need to be cached.
`prepull_status`()	Construct current prepuller status.
`prepuller_wait`()	Wait for a data refresh.
`refresh`()	Refresh data from Docker and Kubernetes.

Methods Documentation

image_for_class(image_class)¶

Determine the image by class keyword.

Only prepulled images can be pulled by class keyword. So, for example, if no releases are prepulled, requesting latest-release will return an error. (However, this will still work before the images have been successfully prepulled.)

Parameters:: image_class (ImageClass) – Class of image requested.
Returns:: Corresponding image.
Return type:: RSPImage
Raises:: UnknownDockerImageError – No available image of the requested class.

async image_for_reference(reference)¶

Determine the image corresponding to a Docker reference.

Parameters:: reference (DockerReference) – Docker reference, which may or may not have a digest.
Returns:: Corresponding image.
Return type:: RSPImage

async image_for_tag_name(tag_name)¶

Determine the image corresponding to a tag.

Assume that the tag is for our configured registry and repository, and construct the corresponding RSPImage.

Parameters:: tag_name (str) – Tag of the image
Return type:: RSPImage
Returns:: Corresponding image.

images()¶

All images available for spawning.

Returns:: Model suitable for returning from the route handler.
Return type:: SpawnerImages

mark_prepulled(image, node)¶

Indicate we believe we have prepulled an image to a node.

This optimistically updates our cached data to indicate that the given node now has that image. This may not be true, in which case we’ll find that out during our next data refresh, but we want to be optimistic and allow this image to appear in the menu as soon as we think all the prepulls have completed.

Parameters:

image (RSPImage) – Image we just prepulled.
node (str) – Node to which we prepulled it.

Return type:

None

menu_images()¶

Images that should appear in the menu.

Returns:: Information required to generate the spawner menu.
Return type:: MenuImages

missing_images_by_node()¶

Determine what images need to be cached.

Returns:: Map of node names to a list of images that should be cached but do not appear to be.
Return type:: dict of list

prepull_status()¶

Construct current prepuller status.

Returns:: Model suitable for returning from a handler.
Return type:: PrepullerStatus

async prepuller_wait()¶

Wait for a data refresh.

This is meant to be called by the prepuller and only supports a single caller. It acts like a single-caller delay gate: each time it’s called, it waits for a data refresh and then clears the event so that the next caller will wait again.

Return type:: None

async refresh()¶

Refresh data from Docker and Kubernetes.

Normally run in a background task, but can be called directly to force an immediate refresh. Does not catch exceptions; the caller must do that if desired.

Return type:: None