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

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

Creates a container image layer from files, executables, and directories.

This rule packages files into a layer that can be used in container images. It supports:

• Adding files at specific paths in the image
• Setting file permissions and ownership
• Creating symlinks
• Including executables with their runfiles
• Compression (gzip, zstd) and eStargz optimization

Example:

load("@rules_img//img:layer.bzl", "image_layer", "file_metadata")

# Simple layer with files
image_layer(
    name = "app_layer",
    srcs = {
        "/app/bin/server": "//cmd/server",
        "/app/config.json": ":config.json",
    },
)

# Layer with custom permissions
image_layer(
    name = "secure_layer",
    srcs = {
        "/etc/app/config": ":config",
        "/etc/app/secret": ":secret",
    },
    default_metadata = file_metadata(
        mode = "0644",
        uid = 1000,
        gid = 1000,
    ),
    file_metadata = {
        "/etc/app/secret": file_metadata(mode = "0600"),
    },
)

# Layer with symlinks
image_layer(
    name = "bin_layer",
    srcs = {
        "/usr/local/bin/app": "//cmd/app",
    },
    symlinks = {
        "/usr/bin/app": "/usr/local/bin/app",
    },
)

Creates a container image layer from an existing tar archive.

This rule converts tar files into container image layers, useful for incorporating
pre-built artifacts, third-party distributions, or legacy build outputs.

The rule can:

• Use tar files as-is or recompress them
• Optimize tar contents by deduplicating files
• Add annotations to the layer metadata

Example:

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

# Use an existing tar file as a layer
layer_from_tar(
    name = "third_party_layer",
    src = "@third_party_lib//:lib.tar.gz",
)

# Optimize and recompress
layer_from_tar(
    name = "optimized_layer",
    src = "//legacy:build_output.tar",
    optimize = True,  # Deduplicate contents
    compress = "zstd",  # Use zstd compression
)

# Add metadata annotations
layer_from_tar(
    name = "annotated_layer",
    src = "//vendor:dependencies.tar.gz",
    annotations = {
        "org.opencontainers.image.title": "Vendor Dependencies",
        "org.opencontainers.image.version": "1.2.3",
    },
)

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

This rule creates an executable target that imports OCI images into your local
container runtime. It supports both Docker 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
image_load(
    name = "load_app",
    image = ":my_app",  # References an image_manifest
    tag = "my-app:latest",
)

# 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

Merges multiple deploy operations into a single unified deployment command.

This rule takes multiple operations (typically from image_push or image_load rules)
that provide DeployInfo and merges them into a single command that can deploy all
operations in parallel. This is useful for scenarios where you need to push and/or
load multiple related images as a coordinated deployment.

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

Example:

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

# Individual operations
image_push(
    name = "push_frontend",
    image = ":frontend",
    registry = "gcr.io",
    repository = "my-project/frontend",
    tag = "latest",
)

image_push(
    name = "push_backend",
    image = ":backend",
    registry = "gcr.io",
    repository = "my-project/backend",
    tag = "latest",
)

image_load(
    name = "load_database",
    image = ":database",
    tag = "my-database:latest",
)

# Unified deployment
multi_deploy(
    name = "deploy_all",
    operations = [
        ":push_frontend",
        ":push_backend",
        ":load_database",
    ],
    push_strategy = "lazy",
    load_strategy = "eager",
)

Runtime usage:

# Deploy all operations together
bazel run //path/to:deploy_all

The deploy-merge subcommand will execute all push and load operations in sequence,
allowing for coordinated deployment of related container images.

Pushes container images to a registry.

This rule creates an executable target that uploads OCI images to container registries.
It supports multiple push strategies optimized for different use cases, from simple
uploads to advanced content-addressable storage integration.

Key features:

• Multiple push strategies: Choose between eager, lazy, CAS-based, or BES-integrated pushing
• Template expansion: Dynamic registry, repository, and tag values using build settings
• Stamping support: Include build information in image tags
• Incremental uploads: Skip blobs that already exist in the registry

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

Example:

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

# Simple push to Docker Hub
image_push(
    name = "push_app",
    image = ":my_app",
    registry = "index.docker.io",
    repository = "myorg/myapp",
    tag = "latest",
)

# Push multi-platform image with multiple tags
image_push(
    name = "push_multiarch",
    image = ":my_app_index",  # References an image_index
    registry = "gcr.io",
    repository = "my-project/my-app",
    tag_list = ["latest", "v1.0.0"],
)

# Dynamic push with build settings
image_push(
    name = "push_dynamic",
    image = ":my_app",
    registry = "{{.REGISTRY}}",
    repository = "{{.PROJECT}}/my-app",
    tag = "{{.VERSION}}",
    build_settings = {
        "REGISTRY": "//settings:registry",
        "PROJECT": "//settings:project",
        "VERSION": "//settings:version",
    },
)

# Push with stamping for unique tags
image_push(
    name = "push_stamped",
    image = ":my_app",
    registry = "index.docker.io",
    repository = "myorg/myapp",
    tag = "latest-{{.BUILD_TIMESTAMP}}",
    stamp = "enabled",
)

# Digest-only push (no tag)
image_push(
    name = "push_by_digest",
    image = ":my_app",
    registry = "gcr.io",
    repository = "my-project/my-app",
    # No tag specified - will push by digest only
)

Push strategies:

• eager: Materializes all layers next to push binary. Simple, correct, but may be inefficient.
• lazy: Layers are not stored locally. Missing layers are streamed from Bazel's remote cache.
• cas_registry: Uses content-addressable storage for extreme efficiency. Requires
  CAS-enabled infrastructure.
• bes: Image is pushed as side-effect of Build Event Stream upload. No "bazel run" command needed.
  Requires Build Event Service integration.

See push strategies documentation for detailed comparisons.

Runtime usage:

# Push to registry
bazel run //path/to:push_app

# The push command will output the image digest