DockerImageSource¶

class controller.services.source.docker.DockerImageSource(config, docker, logger)¶

Bases: ImageSource

Image source using a Docker Registry.

Docker has a very awkward API that makes it expensive to get the hash of an image or to see which tags alias each other. The Docker specialization of the DockerImageSource therefore has to juggle both tag collections (all known tags, possibly without hashes) and image collections (images fully resolved with tags).

Parameters:

config (DockerSourceOptions) – Source configuration specifying the Docker registry and repository.
docker (DockerStorageClient) – Client to query the Docker API for tags.
logger (BoundLogger) – Logger for messages.

Methods Summary

`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.
`mark_prepulled`(image, node)	Optimistically mark an image as prepulled to a node.
`menu_images`()	All known images suitable for display in the spawner menu.
`prepulled_images`(nodes)	All known images with their prepulled status in the API model.
`update_images`(prepull, node_cache)	Update image information and determine what images to prepull.

Methods Documentation

async image_for_reference(reference)¶

Determine the image corresponding to a Docker reference.

If the reference doesn’t contain a digest, this may require a call to the Docker API to determine the digest. The results are intentionally not cached since references without digests indicate we’re pulling an image by tag, and we should therefore always use the latest version.

Parameters:

reference (DockerReference) – Docker reference, which may or may not have a known digest.

Returns:

Corresponding image.

Return type:

RSPImage

Raises:

DockerRegistryError – Raised if retrieving the digest from the Docker Registry failed.
InvalidDockerReferenceError – Raised if the Docker reference doesn’t contain a tag. References without a tag are valid references to Docker, but for our purposes we always want to have a tag to use for debugging, status display inside the lab, etc.
UnknownDockerImageError – Raised if this is not one of the remote images we know about.

async image_for_tag_name(tag_name)¶

Determine the image corresponding to a tag.

Assuming that the tag is for our image source, construct the corresponding RSPImage.

Parameters:

tag_name (str) – Tag of the image

Returns:

Corresponding image.

Return type:

RSPImage

Raises:

UnknownDockerImageError – The requested tag is not found.
DockerRegistryError – Unable to retrieve the digest from the Docker Registry.

mark_prepulled(image, node)¶

Optimistically mark an image as prepulled to a node.

Called by the prepuller after the prepull pod succeeded.

Parameters:

tag_name – Tag of image.
node (str) – Node to which the image was prepulled.
image (RSPImage)

Return type:

None

menu_images()¶

All known images suitable for display in the spawner menu.

Include a full reference with a digest if we have one available. Otherwise, just include the tag.

Returns:: All known images.
Return type:: list of MenuImage

prepulled_images(nodes)¶

All known images with their prepulled status in the API model.

Parameters:: nodes (set[str]) – Nodes on which the image must exist to qualify as prepulled.
Returns:: All known images.
Return type:: list of PrepulledImage

async update_images(prepull, node_cache)¶

Update image information and determine what images to prepull.

Refresh remote tags and images from the Docker registry, find the subset that we’re prepulling, and convert those to images. Resolve aliases and match those with the cached images on nodes to update node presence information.

Parameters:

prepull (PrepullerOptions) – Configuration of what images to prepull.
node_cache (Mapping[str, list[KubernetesNodeImage]]) – Mapping of node names to the list of cached images on that node.

Returns:

New collection of images to prepull.

Return type:

RSPImageCollection

Notes

Getting an image for a tag is an expensive operation, requiring a HEAD call to the Docker API for each image, so we only want to do this for images we care about, namely the images that we’re going to prepull.

The digest is retrieved again on each refresh because it may have changed (Docker registry tags are not immutable).