Skip to content

load.md

Latest commit

 

History

History
249 lines (193 loc) · 16.9 KB

load.md

File metadata and controls

249 lines (193 loc) · 16.9 KB

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, deploy_tool, 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 with OCI layout (available for both single and multi-platform images). For multi-platform images, the first manifest is used as the default in manifest.json, and all manifests are included in index.json. Alternatively, setting daemon = "tar" (or --@rules_img//img/settings:load_daemon=tar) produces the same format on-the-fly by streaming it to stdout at runtime.

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

# Stream tar to stdout (e.g., pipe to another tool)
bazel run //path/to:load_app --@rules_img//img/settings:load_daemon=tar

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 image 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
  • The tar daemon streams a unified OCI+Docker tar to stdout without loading into any daemon
  • The containerization daemon uses Apple's Containerization framework via container image load

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
build_settings Build settings for template expansion.

Maps template variable names to string_flag targets. These values can be used in tag attributes using {{.VARIABLE_NAME}} syntax (Go template).

See template expansion for more details.		 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 image load command which is slower and limited to single-platform images. - podman: Loads via Podman daemon using podman image load command. Similar to Docker fallback mode, this is slower than containerd and limited to single-platform images. - containerization: Loads via Apple's Containerization framework using container image load. Reads a unified OCI+Docker tar from stdin. - tar: Does not load into any daemon. Instead, streams the unified OCI+Docker tar to stdout. Useful for piping to other tools or saving to a file. - generic: Loads via a custom container runtime. The loader will invoke the command specified in the LOADER_BINARY environment variable with image load subcommands. For example, if LOADER_BINARY=nerdctl, it will run nerdctl image load. 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"
deploy_tool Optional label of a deploy tool target providing DeployToolInfo (created with img_deploy_tool from @rules_img//img:deploy_tool.bzl). When set, overrides tool_cfg. Label optional None
image Image to load. Should provide ImageManifestInfo or ImageIndexInfo. Label required
stamp Controls build stamping for template expansion.

- auto (default): Defers to the global --@rules_img//img/settings:stamp setting. - force: Always stamp if templates contain {{}} placeholders, ignoring Bazel's --stamp flag. - disabled: Never include stamp information.

See template expansion for available stamp variables.		 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"

image_load_spec

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

image_load_spec(name, build_settings, daemon, stamp, strategy, tag, tag_file, tag_list)

Defines load configuration for container images without referencing a specific image.

This rule captures daemon, tag, and strategy settings that can be attached to image_manifest or image_index targets via their load_specs attribute. Template strings using Go template syntax ({{.VAR}}) are accepted but not expanded — expansion happens when the deployment is consumed by the image rule. Note that the template strings {{.image_target_package}} and {{.image_target_name}} are especially useful here.

This enables an inverted dependency pattern: instead of image_load depending on the image, the image itself carries its load configuration, making it directly usable with multi_deploy.

Example:

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

image_load_spec(
    name = "load_config",
    tag = "{{.image_target_package}}/{{.image_target_name}}:latest",
    daemon = "containerd",
)

# Attach to an image:
image_manifest(
    name = "my_app_a",
    base = "@distroless_cc",
    layers = [":app_layer"],
    load_specs = [":load_config"],
)

# Attach to another image:
image_manifest(
    name = "my_app_b",
    base = "@distroless_cc",
    layers = [":app_layer"],
    load_specs = [":load_config"],
)

# Now usable directly in multi_deploy:
multi_deploy(
    name = "deploy",
    operations = [
        ":my_app_a",
        ":my_app_b",
    ],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
build_settings Build settings for template expansion.

Maps template variable names to string_flag targets. These values can be used in tag attributes using {{.VARIABLE_NAME}} syntax (Go template).

See template expansion for more details.		 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 image load command which is slower and limited to single-platform images. - podman: Loads via Podman daemon using podman image load command. Similar to Docker fallback mode, this is slower than containerd and limited to single-platform images. - containerization: Loads via Apple's Containerization framework using container image load. Reads a unified OCI+Docker tar from stdin. - tar: Does not load into any daemon. Instead, streams the unified OCI+Docker tar to stdout. Useful for piping to other tools or saving to a file. - generic: Loads via a custom container runtime. The loader will invoke the command specified in the LOADER_BINARY environment variable with image load subcommands. For example, if LOADER_BINARY=nerdctl, it will run nerdctl image load. 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"
stamp Controls build stamping for template expansion.

- auto (default): Defers to the global --@rules_img//img/settings:stamp setting. - force: Always stamp if templates contain {{}} placeholders, ignoring Bazel's --stamp flag. - disabled: Never include stamp information.

See template expansion for available stamp variables.		 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 []