Implementation:Bentoml BentoML OCIBuilder Base

Knowledge Sources	Bentoml_BentoML
Domains	Container, OCI
Last Updated	2026-02-13 15:00 GMT

Overview

Provides the base class and argument construction utilities for all OCI container image builders in BentoML, including Docker, Buildx, Buildah, BuildKit, Podman, and nerdctl.

Description

The base module defines the foundational abstractions for BentoML's container builder system:

Arguments -- A specialized list subclass that provides construct_args, a singledispatch method for building CLI argument lists. It handles:
- tuple/list arguments by expanding to repeated --opt value pairs
- str/PathLike arguments by resolving absolute paths and appending --opt value
- bool arguments by appending --opt as a flag when True

OCIBuilder -- An attrs-based abstract class representing an OCI container builder. Key attributes:
- binary -- Path to the container tool executable
- env -- Environment variables passed to the build subprocess
- build_cmd -- The build sub-command sequence (default: ["build"])
- enable_buildkit -- Whether BuildKit is enabled

Key methods:

- create (static) -- Factory method that produces a FrozenOCIBuilder instance with injected health check and build argument construction functions, used by backend registration.
- health (abstract) -- Checks whether the builder tool is available and functional.
- construct_build_args (abstract) -- Produces the CLI arguments specific to each backend.
- build -- Executes the full build command, merging environment variables, streaming logs when BuildKit is disabled, and raising BentoMLException on failure.
- stream_logs -- Runs the subprocess with threaded stdout/stderr reading to avoid pipe deadlocks, logging output in real time.

FrozenOCIBuilder -- A dynamically created subclass of OCIBuilder with slots for construct_build_args and health, allowing these to be set as instance attributes by the factory method.

Direct instantiation of OCIBuilder is prevented; users must use container.get_backend() instead.

Usage

Use this module as the base for implementing or extending OCI container builder backends in BentoML. All concrete backends (docker, buildx, buildah, buildctl, nerdctl, podman) build upon this base.

Code Reference

Source Location

Repository: Bentoml_BentoML
File: src/bentoml/_internal/container/base.py
Lines: 1-237

Signature

class Arguments(list):
    def construct_args(self, args: t.Any, opt: str = "") -> None: ...

@attr.define(repr=False, init=False)
class OCIBuilder:
    binary: str
    env: dict[str, str]
    build_cmd: t.Sequence[str]
    enable_buildkit: bool

    @staticmethod
    def create(binary: str, build_cmd: t.Sequence[str] | None = None, enable_buildkit: bool = True, env: dict[str, str] | None = None, *, health: t.Callable[[], bool], construct_build_args: t.Callable[..., list[str]]) -> FrozenOCIBuilder: ...
    def health(self) -> bool: ...
    def construct_build_args(self, **kwargs: t.Any) -> t.Sequence[str]: ...
    def build(self, **attrs: t.Any) -> bytes | None: ...
    def stream_logs(self, cmds: t.Sequence[str], *, env: dict[str, str], cwd: PathType) -> subprocess.CompletedProcess[bytes]: ...

Import

from bentoml._internal.container.base import OCIBuilder, Arguments

I/O Contract

Inputs

Name	Type	Required	Description
binary	str	Yes	Path or name of the container tool binary
build_cmd	Sequence[str] or None	No	Sub-command for building (default: ["build"])
enable_buildkit	bool	No	Enable BuildKit support (default: True)
env	dict[str, str] or None	No	Environment variables for the build process
context_path	str	Yes	Build context directory path (for build method)
_run_as_root	bool	No	Whether to prefix command with sudo (for build method)

Outputs

Name	Type	Description
bytes or None	bytes or None	Build output bytes (from build method)
bool	bool	Health check result (from health method)
Arguments	list[str]	Constructed CLI argument list (from construct_build_args)

Usage Examples

from bentoml._internal.container.base import OCIBuilder

# Create a custom backend via the factory method
builder = OCIBuilder.create(
    binary="docker",
    build_cmd=["build"],
    enable_buildkit=True,
    env={"DOCKER_BUILDKIT": "1"},
    health=lambda: True,
    construct_build_args=lambda **kwargs: ["--tag", kwargs.get("tag", "latest"), "."],
)

# Check health
if builder.health():
    # Build an image
    output = builder.build(context_path="/path/to/context", tag="myimage:latest")

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment