image.md

Rules to build container images from layers.

Use image_manifest to create a single-platform container image, and image_index to compose a multi-platform container image index.

image_index

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

image_index(name, annotations, annotations_file, build_settings, manifests, platforms, stamp)

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:...)
• oci_layout: Complete OCI layout directory with all platform blobs
• oci_tarball: OCI layout packaged as a tar file for downstream use

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
annotations	Arbitrary metadata for the image index. Subject to template expansion.	Dictionary: String -> String	optional	{}
annotations_file	File containing newline-delimited KEY=VALUE annotations for the image index. The file should contain one annotation per line in KEY=VALUE format. Empty lines are ignored. Annotations from this file are merged with annotations specified via the annotations attribute. Example file content: version=1.0.0 build.date=2024-01-15 source.url=https://github.com/... Each annotation is subject to template expansion.	Label	optional	None
build_settings	Build settings for template expansion. Maps template variable names to string_flag targets. These values can be used in the annotations attribute using {{.VARIABLE_NAME}} syntax (Go template). Example: build_settings = { "REGISTRY": "//settings:docker_registry", "VERSION": "//settings:app_version", } See template expansion for more details.	Dictionary: String -> Label	optional	{}
manifests	List of manifests for specific platforms.	List of labels	optional	[]
platforms	(Optional) list of target platforms to build the manifest for. Uses a split transition. If specified, the 'manifests' attribute should contain exactly one manifest.	List of labels	optional	[]
stamp	Enable build stamping for template expansion. Controls whether to include volatile build information: - auto (default): Uses the global stamping configuration - enabled: Always include stamp information (BUILD_TIMESTAMP, BUILD_USER, etc.) if Bazel's "--stamp" flag is set - disabled: Never include stamp information See template expansion for available stamp variables.	String	optional	"auto"

image_manifest

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

image_manifest(name, annotations, annotations_file, base, build_settings, cmd, config_fragment,
               created, entrypoint, env, labels, layers, platform, stamp, stop_signal, 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:...)
• oci_layout: Complete OCI layout directory with blobs
• oci_tarball: OCI layout packaged as a tar file for downstream use

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
annotations	This field contains arbitrary metadata for the manifest. Subject to template expansion.	Dictionary: String -> String	optional	{}
annotations_file	File containing newline-delimited KEY=VALUE annotations for the manifest. The file should contain one annotation per line in KEY=VALUE format. Empty lines are ignored. Annotations from this file are merged with annotations specified via the annotations attribute. Example file content: version=1.0.0 build.date=2024-01-15 source.url=https://github.com/... Each annotation is subject to template expansion.	Label	optional	None
base	Base image to inherit layers from. Should provide ImageManifestInfo or ImageIndexInfo.	Label	optional	None
build_settings	Build settings for template expansion. Maps template variable names to string_flag targets. These values can be used in env, labels, and annotations attributes using {{.VARIABLE_NAME}} syntax (Go template). Example: build_settings = { "REGISTRY": "//settings:docker_registry", "VERSION": "//settings:app_version", } See template expansion for more details.	Dictionary: String -> Label	optional	{}
cmd	Default arguments to the entrypoint of the container. These values act as defaults and may be replaced by any specified when creating a container. If an Entrypoint value is not specified, then the first entry of the Cmd array SHOULD be interpreted as the executable to run.	List of strings	optional	[]
config_fragment	Optional JSON file containing a partial image config, which will be used as a base for the final image config.	Label	optional	None
created	Optional file containing a datetime string (RFC 3339 format) for when the image was created. This is commonly used with Bazel's stamping mechanism to embed the build timestamp.	Label	optional	None
entrypoint	A list of arguments to use as the command to execute when the container starts. These values act as defaults and may be replaced by an entrypoint specified when creating a container.	List of strings	optional	[]
env	Default environment variables to set when starting a container based on this image. Subject to template expansion.	Dictionary: String -> String	optional	{}
labels	This field contains arbitrary metadata for the container. Subject to template expansion.	Dictionary: String -> String	optional	{}
layers	Layers to include in the image. Either a LayerInfo provider or a DefaultInfo with tar files.	List of labels	optional	[]
platform	Optional target platform to build this manifest for. When specified, the image will be built for the provided platform regardless of the current build configuration. This enables building single-platform images for specific architectures. Example: image_manifest( name = "app_arm64", platform = "//platforms:linux_arm64", base = "@ubuntu", layers = [":app_layer"], )	Label	optional	None
stamp	Enable build stamping for template expansion. Controls whether to include volatile build information: - auto (default): Uses the global stamping configuration - enabled: Always include stamp information (BUILD_TIMESTAMP, BUILD_USER, etc.) if Bazel's "--stamp" flag is set - disabled: Never include stamp information See template expansion for available stamp variables.	String	optional	"auto"
stop_signal	This field contains the system call signal that will be sent to the container to exit. The signal can be a signal name in the format SIGNAME, for instance SIGKILL or SIGRTMIN+3.	String	optional	""
user	The username or UID which is a platform-specific structure that allows specific control over which user the process run as. This acts as a default value to use when the value is not specified when creating a container.	String	optional	""
working_dir	Sets the current working directory of the entrypoint process in the container. This value acts as a default and may be replaced by a working directory specified when creating a container.	String	optional	""