Package the Go binary with a distroless base

Rules to build container images from layers.

Use image_from_binary to package any *_binary target into a container image, image_manifest to create a single-platform container image from layers, and image_index to compose a multi-platform container image index.

INHERIT_FROM_BASE is a sentinel that can be used as (or inside) the user, working_dir, stop_signal, entrypoint, and cmd attributes of image_manifest / image_from_binary to explicitly inherit that config field from the base image.

image_index

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

image_index(name, annotations, annotations_file, build_settings, load_specs, manifests, platforms,
            push_specs, stamp, subject)

Creates a multi-platform OCI image index from platform-specific manifests.

This rule combines multiple single-platform images (created by image_manifest) into a multi-platform image index. The index allows container runtimes to automatically select the appropriate image for their platform.

The rule supports two usage patterns:

1. Explicit manifests: Provide pre-built manifests for each platform
2. Platform transitions: Provide one manifest target and a list of platforms

The rule produces:

• OCI image index JSON file
• An optional OCI layout directory or tar (via output groups)
• ImageIndexInfo provider for use by image_push

Example (explicit manifests):

image_index(
    name = "multiarch_app",
    manifests = [
        ":app_linux_amd64",
        ":app_linux_arm64",
        ":app_darwin_amd64",
    ],
)

Example (platform transitions):

image_index(
    name = "multiarch_app",
    manifests = [":app"],
    platforms = [
        "//platform:linux-x86_64",
        "//platform:linux-aarch64",
    ],
)

Output groups:

• digest: Digest of the image (sha256:...)
• root_blob: The index JSON blob file
• oci_layout: Complete OCI layout directory with all platform blobs
• oci_tarball: OCI layout packaged as a tar file for downstream use
• sparse_oci_layout: Sparse OCI layout directory (without layer blobs, only layer descriptors)

ATTRIBUTES

version=1.0.0
build.date=2024-01-15
source.url=https://github.com/...

build_settings = {
"REGISTRY": "//settings:docker_registry",
"VERSION": "//settings:app_version",
}

image_manifest

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

image_manifest(name, annotations, annotations_file, artifact_type, base, build_settings, cmd,
               config_fragment, config_media_type, created, entrypoint, env, env_file, label_files,
               labels, layers, load_specs, platform, push_specs, stamp, stop_signal, subject, user,
               working_dir)

Builds a single-platform OCI container image from a set of layers.

This rule assembles container images by combining:

• Optional base image layers (from another image_manifest or image_index)
• Additional layers created by image_layer rules
• Image configuration (entrypoint, environment, labels, etc.)

The rule produces:

• OCI manifest and config JSON files
• An optional OCI layout directory or tar (via output groups)
• ImageManifestInfo provider for use by image_index or image_push

Example:

image_manifest(
    name = "my_app",
    base = "@distroless_cc",
    layers = [
        ":app_layer",
        ":config_layer",
    ],
    entrypoint = ["/usr/bin/app"],
    env = {
        "APP_ENV": "production",
    },
)

Output groups:

• descriptor: OCI descriptor JSON file
• digest: Digest of the image (sha256:...)
• root_blob: The manifest JSON blob file
• oci_layout: Complete OCI layout directory with blobs
• oci_tarball: OCI layout packaged as a tar file for downstream use
• sparse_oci_layout: Sparse OCI layout directory (without layer blobs, only layer descriptors)
• mtree: a single mtree text file describing the image's filesystem, merged (in layer order) from per-layer mtrees. Layers built by rules_img layer rules reuse their own mtree; for any other layer -- pulled/imported base-image layers, or raw tars added directly via DefaultInfo -- an mtree is rendered on the fly from the layer's tar blob. A layer is skipped on a best-effort basis only when its blob is unavailable (shallow/lazy layers) or is not a tar (empty layers, non-tar artifact blobs), so a skipped layer means the merged mtree reflects only a subset of the image. Only produced when at least one layer contributes an mtree.

ATTRIBUTES

version=1.0.0
build.date=2024-01-15
source.url=https://github.com/...

build_settings = {
"REGISTRY": "//settings:docker_registry",
"VERSION": "//settings:app_version",
}

{
"config": {
"ExposedPorts": {
"8080/tcp": {}
}
}
}

org.opencontainers.image.version=1.0.0
org.opencontainers.image.authors=team@example.com

image_load_spec(
name = "load_config",
tag = "my-app:latest",
)

image_manifest(
name = "my_app",
base = "@distroless_cc",
layers = [":app_layer"],
load_specs = [":load_config"],
)

multi_deploy(
name = "deploy",
operations = [":my_app"],
)

image_manifest(
name = "app_arm64",
platform = "//platforms:linux_arm64",
base = "@ubuntu",
layers = [":app_layer"],
)

image_push_spec(
name = "push_config",
registry = "gcr.io",
repository = "my-project/my-app",
tag = "latest",
)

image_manifest(
name = "my_app",
base = "@distroless_cc",
layers = [":app_layer"],
push_specs = [":push_config"],
)

multi_deploy(
name = "deploy",
operations = [":my_app"],
)

image_optimize

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

image_optimize(name, compress, estargz, image)

Rewrites every available layer in an image manifest or image index.

This rule applies image-wide layer transformations, such as recompressing every layer as eStargz. It is intentionally explicit because it requires every input layer blob to be available to Bazel. Images that were pulled shallowly will fail analysis instead of downloading missing base-image layers.

Example:

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

image_optimize(
    name = "base_estargz",
    image = "@ubuntu//:image",
    estargz = "enabled",
)

ATTRIBUTES

image_from_binary

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

image_from_binary(*, name, annotations, annotations_file, artifact_type, aspect_hints, base, binary,
                  build_settings, cmd, compatible_with, config_fragment, config_media_type, created,
                  deprecation, entrypoint, env, env_file, exec_compatible_with,
                  exec_group_compatible_with, exec_properties, features, include_runfiles, kind,
                  label_files, labels, layer_budget, layers, load_specs, package_metadata, path,
                  platforms, push_specs, restricted_to, stamp, stop_signal, subject, tags,
                  target_compatible_with, testonly, toolchains, user, visibility, working_dir)

Packages a *_binary target into a container image.

This is a convenience macro that combines layer_from_binary and image_manifest (or image_index) into a single target. It is the simplest way to containerize any Bazel *_binary target (Go, C++, Python, Java, Rust, etc.).

The binary's args, env, and runfiles are automatically extracted and applied to the image configuration:

• entrypoint is set to the binary's path inside the image
• cmd is populated from the binary's args attribute
• env is populated from the binary's env attribute (or RunEnvironmentInfo provider)
• working_dir is set to the binary's runfiles root

If the binary provides RunfilesGroupInfo (from rules_runfiles_group), the runfiles are split into separate layers based on the groups. This allows for better caching: stable layers (interpreter, stdlib) change infrequently and can be shared, while the application code layer changes with each build. The resolution protocol respects RunfilesGroupTransformInfo and RunfilesGroupMetadataInfo from the binary's aspect_hints.

All image_manifest attributes (base, env, labels, annotations, etc.) are inherited and forwarded to the underlying image_manifest. The binary layer is always appended as the last layer, after any layers specified in the layers attribute.

Example:

load("@rules_go//go:def.bzl", "go_binary")
load("@rules_img//img:image.bzl", "image_from_binary")

go_binary(
    name = "server",
    srcs = ["main.go"],
    env = {"GIN_MODE": "release"},
)

# Package the Go binary with a distroless base
image_from_binary(
    name = "app_image",
    binary = ":server",
    base = "@distroless_base",
)

# Custom path and additional layers
image_from_binary(
    name = "full_image",
    binary = "//cmd/server",
    base = "@ubuntu",
    path = "/usr/local/bin/",
    layers = [":config_layer"],
    env = {"LOG_LEVEL": "info"},
)

# Multi-platform image
image_from_binary(
    name = "multiarch_image",
    binary = "//cmd/server",
    base = "@distroless_base",
    platforms = [
        "//:linux_amd64",
        "//:linux_arm64",
    ],
)

Targets created:

• <name>.layer: The layer_from_binary containing the executable and its runfiles
• <name> (or <name>.manifest + <name> for multi-platform): The image manifest/index

ATTRIBUTES

version=1.0.0
build.date=2024-01-15
source.url=https://github.com/...

build_settings = {
"REGISTRY": "//settings:docker_registry",
"VERSION": "//settings:app_version",
}

{
"config": {
"ExposedPorts": {
"8080/tcp": {}
}
}
}

org.opencontainers.image.version=1.0.0
org.opencontainers.image.authors=team@example.com

image_load_spec(
name = "load_config",
tag = "my-app:latest",
)

image_manifest(
name = "my_app",
base = "@distroless_cc",
layers = [":app_layer"],
load_specs = [":load_config"],
)

multi_deploy(
name = "deploy",
operations = [":my_app"],
)

image_push_spec(
name = "push_config",
registry = "gcr.io",
repository = "my-project/my-app",
tag = "latest",
)

image_manifest(
name = "my_app",
base = "@distroless_cc",
layers = [":app_layer"],
push_specs = [":push_config"],
)

multi_deploy(
name = "deploy",
operations = [":my_app"],
)