Skip to content

load.md

Latest commit

 

History

History
164 lines (126 loc) · 8.95 KB

load.md

File metadata and controls

164 lines (126 loc) · 8.95 KB
Raw

Public API for loading container images into a daemon.

The image_load rule creates an executable target that loads container images into a local daemon (containerd, Docker, or Podman).

Example

load("@rules_img//img:image.bzl", "image_manifest")
load("@rules_img//img:load.bzl", "image_load")
load("@rules_img//img:layer.bzl", "image_layer")

# Create a simple layer
image_layer(
    name = "app_layer",
    srcs = {
        "/app/hello.txt": "hello.txt",
    },
)

# Build an image
image_manifest(
    name = "my_image",
    base = "@alpine",
    layers = [":app_layer"],
)

# Create a load target with a single tag
image_load(
    name = "load",
    image = ":my_image",
    tag = "my-app:latest",
)

# Load with multiple tags
image_load(
    name = "load_multi",
    image = ":my_image",
    tag_list = ["my-app:latest", "my-app:v1.0.0"],
)

Then run:

# Load the image into your local daemon
bazel run //:load

Platform Selection

When running the load target, you can use the --platform flag to filter which platforms to load from multi-platform images:

# Load all platforms (default)
bazel run //path/to:load_target

# Load only linux/amd64
bazel run //path/to:load_target -- --platform linux/amd64

Note: Docker daemon only supports loading a single platform at a time. If multiple platforms are specified with Docker, an error will be returned.

image_load

load("@rules_img//img:load.bzl", "image_load")

image_load(name, build_settings, daemon, image, stamp, strategy, tag, tag_file, tag_list, tool_cfg)

Loads container images into a local daemon (Docker, containerd, or Podman).

This rule creates an executable target that imports OCI images into your local container runtime. It supports Docker, Podman, and containerd, with intelligent detection of the best loading method for optimal performance.

Key features:

  • Incremental loading: Skips blobs that already exist in the daemon
  • Multi-platform support: Can load entire image indexes or specific platforms
  • Direct containerd integration: Bypasses Docker for faster imports when possible
  • Platform filtering: Use --platform flag at runtime to select specific platforms

The rule produces an executable that can be run with bazel run.

Output groups:

  • tarball: Docker save compatible tarball (only available for single-platform images)

Example:

load("@rules_img//img:load.bzl", "image_load")

# Load a single-platform image with a single tag
image_load(
    name = "load_app",
    image = ":my_app",  # References an image_manifest
    tag = "my-app:latest",
)

# Load with multiple tags
image_load(
    name = "load_multi",
    image = ":my_app",
    tag_list = ["my-app:latest", "my-app:v1.0.0", "my-app:stable"],
)

# Load a multi-platform image
image_load(
    name = "load_multiarch",
    image = ":my_app_index",  # References an image_index
    tag = "my-app:latest",
    daemon = "containerd",  # Explicitly use containerd
)

# Load with dynamic tagging
image_load(
    name = "load_dynamic",
    image = ":my_app",
    tag = "my-app:{{.BUILD_USER}}",  # Template expansion
    build_settings = {
        "BUILD_USER": "//settings:username",
    },
)

Runtime usage:

# Load all platforms
bazel run //path/to:load_app

# Load specific platform only
bazel run //path/to:load_multiarch -- --platform linux/arm64

# Build Docker save tarball
bazel build //path/to:load_app --output_groups=tarball

Performance notes:

  • When Docker uses containerd storage (Docker 23.0+), images are loaded directly into containerd for better performance if the containerd socket is accessible.
  • For older Docker versions, falls back to docker load which requires building a tar file (slower and limited to single-platform images)
  • The --platform flag filters which platforms are loaded from multi-platform images

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
build_settings Build settings to use for template expansion. Keys are setting names, values are labels to string_flag targets. Dictionary: String -> Label optional {}
daemon Container daemon to use for loading the image.

Available options: - auto (default): Uses the global default setting (usually docker) - containerd: Loads directly into containerd namespace. Supports multi-platform images and incremental loading. - docker: Loads via Docker daemon. When Docker uses containerd storage (23.0+), loads directly into containerd. Otherwise falls back to docker load command which is slower and limited to single-platform images. - podman: Loads via Podman daemon using podman load command. Similar to Docker fallback mode, this is slower than containerd and limited to single-platform images. - generic: Loads via a custom container runtime. The loader will invoke the command specified in the LOADER_BINARY environment variable with the load subcommand. For example, if LOADER_BINARY=nerdctl, it will run nerdctl load. Limited to single-platform images. Requires LOADER_BINARY to be set at runtime.

The best performance is achieved with: - Direct containerd access (daemon = "containerd") - Docker 23.0+ with containerd storage enabled and accessible containerd socket		 String optional "auto"
image Image to load. Should provide ImageManifestInfo or ImageIndexInfo. Label required
stamp Whether to use stamping for template expansion. If 'enabled', uses volatile-status.txt and version.txt if present. 'auto' uses the global default setting. String optional "auto"
strategy Strategy for handling image layers during load.

Available strategies: - auto (default): Uses the global default load strategy - eager: Downloads all layers during the build phase. Ensures all layers are available locally before running the load command. - lazy: Downloads layers only when needed during the load operation. More efficient for large images where some layers might already exist in the daemon.		 String optional "auto"
tag Tag to apply when loading the image.

Optional - if omitted, the image is loaded without a tag.

Subject to template expansion.		 String optional ""
tag_file File containing newline-delimited tags to apply when loading the image.

The file should contain one tag per line. Empty lines are ignored. Tags from this file are merged with tags specified via tag or tag_list attributes.

Example file content: 
latest
v1.0.0
stable


Can be combined with tag or tag_list to merge tags from multiple sources. Each tag is subject to template expansion.		 Label optional None
tag_list List of tags to apply when loading the image.

Useful for applying multiple tags in a single load:

tag_list = ["latest", "v1.0.0", "stable"]


Cannot be used together with tag. Can be combined with tag_file to merge tags from both sources. Each tag is subject to template expansion.		 List of strings optional []
tool_cfg Experimental: This attribute may be removed if we find a way to automatically select the correct loader platform based on the context of use. Configuration of the loader executable. By default, the loader executable is always chosen for the host platform, regardless of the value of --platforms. Setting this attribute to 'target' makes the loader match the target platform instead. The "target" option is useful when the "image_load" target is used as a data dependency of an integration test.

Available options: - host (default): Loader executable matches the host platform. - target: Loader executable matches the target platform(s) specified via --platforms.		 String optional "host"