Container support¶

VaRA-TS allows you to run experiments in a container. The containers module handles the correct creation of container images. Our container images are structured in multiple stages as follows:

┌───────────────────────────────────┐  \
│             Stage 00              │   |
│ Base Container (e.g., Debian 10)  │   |
│          + dependencies           │   |
└───────────────────────────────────┘   |
                  +                     |
┌───────────────────────────────────┐   |
│             Stage 10              │   |
│         varats/benchbuild         │   |
└───────────────────────────────────┘   |
                  +                      > Base Image
┌───────────────────────────────────┐   |
│             Stage 20              │   |
│    Research Tool (e.g., VaRA)     │   |
└───────────────────────────────────┘   |
                  +                     |
┌───────────────────────────────────┐   |
│             Stage 30              │   |
│          configuration            │   |
└───────────────────────────────────┘  /
                  +
┌───────────────────────────────────┐
│         Project Specific          │
└───────────────────────────────────┘
                  +
┌───────────────────────────────────┐
│        Experiment Specific        │
└───────────────────────────────────┘

Each stage results in its own container image. This allows us to update only some of the stages to save time when only changes to certain stages are required (especially stage 00 can be very time consuming to build). The vara-container tool provides appropriate command line flags to only re-build certain stages.

Base images are built once for each ImageBase with the currently configured research tool using the vara-container tool. Projects must select one of these base images which they are then free to extend with their own project-specific dependencies. The directory structure inside a container looks like the following:

/
├─ app/  # corresponds to the BB build_dir; BB is executed from here
└─ varats_root/  # corresponds to the varats root directory
   ├─ results/        # mount point to <varats-root>/results outside the container
   ├─ BC_files/       # mount point to <varats-root>/benchbuild/BC_files outside the container
   └─ paper_configs/  # mount point to <varats-root>/paper_configs outside the container

The required mount points are specified automatically when creating a BenchBuild config via vara-gen-bbconfig.

Containers module¶

Container related functionality.

class varats.containers.containers.ImageBase(distro, version_number)[source]¶

Bases: Enum

Container image bases that can be used by projects.

DEBIAN_10 = (Distro.DEBIAN, 10)¶

DEBIAN_12 = (Distro.DEBIAN, 12)¶

property distro: Distro¶: Distro of the base image.

property version: int¶: Version number of the distro.

class varats.containers.containers.ImageStage(*values)[source]¶

Bases: Enum

The stages that make up a base image.

STAGE_00_BASE = 0¶

STAGE_10_VARATS = 10¶

STAGE_20_TOOL = 20¶

STAGE_30_CONFIG = 30¶

STAGE_31_CONFIG_DEV = 31¶

class varats.containers.containers.StageBuilder(base, stage, image_name)[source]¶

Bases: object

Context manager for creating a base image stage.

The image is built automatically when exiting the context manager.

varats_root = PosixPath('/varats_root')¶: VaRA-TS root inside the container.

varats_source_mount_target = PosixPath('/varats')¶: VaRA-TS root inside the container.

bb_root = PosixPath('/app')¶: BenchBuild root inside the container.

property base: ImageBase¶

Base image this image is based on.

Returns:: the base image

property stage: ImageStage¶

Stage of the base image that should be built/updated.

Only the given stage and subsequent stages shall be considered.

Returns:: the image stage

property layers: ContainerImage¶

Layers of the container that is being created using this context.

Users of this context can use this object to add new layers.

Returns:: the container layers

property image_name: str¶

Name of the image that is being created.

Returns:: the name of the image that is being created

property tmpdir: Path¶

Temporary directory that can be used during image creation.

Returns:: the path to the temporary directory

varats.containers.containers.create_dev_image(base, build_type)[source]¶

Build a dev image for the given image base and research tool.

A dev image is used to build the research tool in the container environment.

Parameters:

base (ImageBase) – the image base
build_type (BuildType) – the build type for the research tool

Return type:

str

varats.containers.containers.create_base_image(base, first_stage, force_rebuild)[source]¶

Builds the given base image for the current research tool.

Parameters:

base (ImageBase) – the base image to build
first_stage (ImageStage) – the first image stage in the stack that shall be built
force_rebuild (bool) – whether to rebuild existing images

Return type:

None

varats.containers.containers.create_base_images(images=<enum 'ImageBase'>, stage=ImageStage.STAGE_00_BASE, force_rebuild=False)[source]¶

Builds all base images for the current research tool.

Return type:: None

varats.containers.containers.get_base_image(base)[source]¶

Get the requested base image for the current research tool.

Parameters:: base (ImageBase) – the base image to retrieve
Return type:: ContainerImage
Returns:: the requested base image

varats.containers.containers.get_image_name(base, stage, include_tool)[source]¶

Get the name for a container image.

Parameters:

base (ImageBase) – the container’s image base
stage (ImageStage) – the container’s stage
include_tool (bool) – whether to include the research tool name or not

Return type:

str

Returns:

the container’s name

varats.containers.containers.get_dev_image_name(base, stage, build_type)[source]¶

Get the name for a dev-container image.

Parameters:

base (ImageBase) – the container’s image base
stage (ImageStage) – the container’s stage
build_type (BuildType) – the build type for the research tool

Return type:

str

Returns:

the dev-container’s name

varats.containers.containers.delete_base_images(images=<enum 'ImageBase'>, first_stage=ImageStage.STAGE_00_BASE)[source]¶

Deletes the selected base images.

Parameters:

images (Iterable[ImageBase]) – the base images to delete
first_stage (ImageStage) – the first stage in the stack that should be deleted

Return type:

None

varats.containers.containers.delete_dev_images(build_type, images=<enum 'ImageBase'>, first_stage=ImageStage.STAGE_00_BASE)[source]¶

Deletes the selected dev images.

Parameters:

build_type (BuildType) – the build type for the research tool
images (Iterable[ImageBase]) – the dev images to delete
first_stage (ImageStage) – the first stage in the stack that should be deleted

Return type:

None

varats.containers.containers.export_base_image(base)[source]¶

Export the base image to the filesystem.

Return type:: None

varats.containers.containers.export_base_images(images=<enum 'ImageBase'>)[source]¶

Exports the selected base images.

Return type:: None

varats.containers.containers.run_container(image_tag, container_name, build_dir, args)[source]¶

Run a podman container.

Parameters:

image_tag (str) – tag of the image to use for the container
container_name (str) – name for the spawned container
build_dir (Optional[str]) – benchbuild’s build directory
args (Sequence[str]) – arguments that get passed to the container’s entry point

Return type:

None