kernelfoundry.eval_pipeline.utils.container

Container runtime abstraction for Docker and Podman.

Functions

get_container_runtime()

Returns the appropriate container runtime class for the current system.

Classes

ContainerRuntime([registry, gpu_type, ...])

Abstract base class for container runtimes.

Docker([registry, gpu_type, allowed_registries])

Container runtime backed by Docker.

Image(runtime, image_id, tag)

Represents a built or resolved container image tied to a specific runtime.

Podman([registry, gpu_type, allowed_registries])

Container runtime backed by Podman (drop-in Docker replacement).
class kernelfoundry.eval_pipeline.utils.container.Image(runtime: ContainerRuntime, image_id: str, tag: str)[source]

Represents a built or resolved container image tied to a specific runtime.

__init__(runtime: ContainerRuntime, image_id: str, tag: str) → None[source]
static default_run_args(workdir: Path | str, workspace_dir: Path | str, gpus: list[int] | str | None = None, kernelfoundry_dir: Path | str | None = None) → dict[source]

Returns a default set of arguments for running a container with this image building and testing kernels.

Parameters:

  • workdir – The working directory to set inside the container.

  • workspace_dir – The host directory to mount as /workspace inside the container, containing the kernel source and test files.

  • gpus – Optional list of GPU indices to make available inside the container, or “all” to make all GPUs available. If not specified, no GPUs will be made available.

  • kernelfoundry_dir – Optional host directory of the kernelfoundry codebase.

Returns:

A dictionary of arguments to pass to the runtime’s get_run_cmd() method

run_cmd(cmd: list[str] | str, timeout: int | None = None, output_inactivity_timeout: float | None = None, end_marker: str | None = None, container_run_args: dict | None = None, **kwargs) → Coroutine[source]

Runs a command in a container from this image.

Parameters:

  • cmd – The command to run inside the container, as a list of strings.

  • timeout – The maximum time to wait for the command to complete.

  • output_inactivity_timeout – Time in seconds to wait for output before considering the process inactive.

  • end_marker – Controls end-of-process monitoring. "pytest" terminates after the pytest summary line (10 s grace). Any other string terminates when that literal appears in output (2 s grace). None disables early termination.

  • container_run_args – Optional dictionary of arguments to pass to the runtime’s get_run_cmd() method without the image argument (e.g. workdir, volumes, env_vars, gpus).

  • **kwargs – Additional keyword arguments to pass to subprocess.Popen

Returns:

Returns a coroutine that, when awaited, runs the command in the container and returns a tuple of (CompletedProcess, termination_message)

push(timeout: int | None = None) → tuple[CompletedProcess, str | None][source]

Pushes the image to its registry.

Parameters:

timeout – The maximum time to wait for the push to complete.

Returns:

A tuple of (CompletedProcess, termination_message)

class kernelfoundry.eval_pipeline.utils.container.ContainerRuntime(registry: str | None = None, gpu_type: str | None = None, allowed_registries: list[str] | None = None)[source]

Abstract base class for container runtimes.

__init__(registry: str | None = None, gpu_type: str | None = None, allowed_registries: list[str] | None = None) → None[source]
Parameters:

  • registry – Optional container registry prefix used when pulling images (e.g. ‘registry.example.com:5000’). When set, image names that are not absolutely qualified with the registry will be automatically prefixed when passed to get_image().

  • gpu_type – Optional GPU type to use when running containers (e.g. ‘nvidia’). If not specified, the GPU type is auto-detected based on the system’s hardware.

  • allowed_registries – Optional list of allowed registry prefixes. If set, any registry used in image names must start with one of these prefixes.

build_image(environment_path: Path | str, dockerfile_path: Path | str | None = 'Dockerfile', image_name: str | None = None, timeout: int | None = None, qualify_name: bool = True) → tuple[Image | None, CompletedProcess, str | None][source]

Builds a container image from a Dockerfile.

Parameters:

  • environment_path – The build context directory.

  • dockerfile_path – The path to the Dockerfile.

  • image_name – The name to give the built image.

  • timeout – The maximum time to wait for the build to complete.

  • qualify_name – Whether to prepend the registry prefix to bare image names.

Returns:

A tuple of (Image or None if build failed, CompletedProcess, termination_message)

get_image(image_name: str) → tuple[Image | None, CompletedProcess, str | None][source]

Looks up an existing image by name, optionally prefixed with the registry.

Parameters:

image_name – The name of the container image. If a registry was provided to the constructor and the name is not already fully qualified, the registry prefix is prepended automatically.

Returns:

An Image object for the latest matching image, or None if no such image exists locally.

get_default_image(language: str, gpu_arch: str, timeout: int | None = None) → tuple[Image | None, CompletedProcess | None, str | None][source]

Gets the default image for the given language and GPU architecture.

Parameters:

  • language – The programming language for which to get the default image.

  • gpu_arch – The GPU architecture for which to get the default image.

Returns:

A tuple of (Image or None if no suitable image could be found or built, CompletedProcess, termination_message)

get_run_cmd(image: Image, workdir: str | None = None, volumes: list[tuple[str, str, str] | tuple[str, str]] | None = None, env_vars: dict[str, str] | None = None, gpus: list[int] | str | None = None, reserved_host_memory_kb: int | None = 4194304) → list[str][source]

Returns the base container run command for the given image.

Parameters:

  • image – The Image to build the run command for.

  • workdir – Optional working directory to set inside the container.

  • volumes – Optional list of tuples specifying volume mounts. Each tuple can be either (host_path, container_path) or (host_path, container_path, mode). E.g. [(“/host/data”, “/container/data”), (“/host/config”, “/container/config”, “ro”)].

  • env_vars – Optional dictionary of environment variables to set inside the container.

  • gpus – Optional list of GPU indices to make available inside the container, or "all" to make all GPUs available.

  • reserved_host_memory_kb – Amount of system memory in kB to leave available for the host. When set, the container memory limit is passed as total system memory minus this reserved amount. Default is 4GB. None disables the memory limit.

Returns:

A list of strings forming the base command, e.g. ['docker', 'run', '--rm', '<image_id>'].

pull_image(image_id: str, timeout: int | None = None, prepend_registry: bool = True) → tuple[Image | None, CompletedProcess, str | None][source]

Pulls a container image by ID or name from a registry.

Parameters:

  • image_id – The image ID or fully-qualified image name to pull.

  • timeout – The maximum time to wait for the pull to complete.

Returns:

A tuple of (Image or None if pull failed, CompletedProcess, termination_message)

class kernelfoundry.eval_pipeline.utils.container.Docker(registry: str | None = None, gpu_type: str | None = None, allowed_registries: list[str] | None = None)[source]

Container runtime backed by Docker.

class kernelfoundry.eval_pipeline.utils.container.Podman(registry: str | None = None, gpu_type: str | None = None, allowed_registries: list[str] | None = None)[source]

Container runtime backed by Podman (drop-in Docker replacement).

kernelfoundry.eval_pipeline.utils.container.get_container_runtime() → type[ContainerRuntime][source]

Returns the appropriate container runtime class for the current system.

Checks for docker first, then podman. Raises RuntimeError if neither is available.

Returns:

The Docker or Podman class.