Simple layer with files

Public API for container image layer rules.

image_layer

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

image_layer(name, srcs, annotations, annotations_file, compress, create_parent_directories,
            default_metadata, estargz, file_metadata, include_runfiles, media_type, multi_file_layout,
            symlinks, tree_artifact_handling)

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 and any additional default outputs
• 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",
    },
)

Output groups

• mtree: a single mtree text file

ATTRIBUTES

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

layer_from_binary

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

layer_from_binary(name, annotations, annotations_file, binary, compress, create_parent_directories,
                  estargz, include_runfiles, layer_budget, media_type, path, runfiles_path,
                  runfiles_shared_path, runfiles_sharing_mode, tree_artifact_handling)

Creates a container image layer from a *_binary target.

This rule packages a binary executable and its runfiles into a layer, and additionally provides image configuration (entrypoint, cmd, env, working_dir) via ImageLayerConfigInfo. When used as a layer in image_manifest, the configuration is automatically applied to the image with Dockerfile-like semantics.

The binary's args attribute becomes the image cmd, its env attribute (or RunEnvironmentInfo provider) becomes env, and the binary path becomes the entrypoint. When include_runfiles is True (default), the working directory is set to the runfiles root.

In addition to the executable and its runfiles, any other default outputs of the binary target (the rest of DefaultInfo.files) are copied into the layer, each placed at the same location relative to the executable that it has in the source tree.

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.

When the number of groups exceeds what is practical for a container image, use layer_budget to merge groups down to a maximum count. The merge algorithm respects group rank (only merges within the same rank), do_not_merge flags, and weight hints (lighter groups merge first).

Example:

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

# Package a Go binary with its runfiles
layer_from_binary(
    name = "app_layer",
    binary = "//cmd/server",
)

# Use in an image - entrypoint, cmd, env, and working_dir are set automatically
image_manifest(
    name = "image",
    base = "@distroless_base",
    layers = [":app_layer"],
)

# Override the path inside the image
layer_from_binary(
    name = "custom_path_layer",
    binary = "//cmd/server",
    path = "/usr/local/bin/",
)

# Without runfiles (static binary)
layer_from_binary(
    name = "static_layer",
    binary = "//cmd/server",
    path = "/usr/local/bin/server",
    include_runfiles = False,
)

Output groups

• mtree: one mtree text file per produced layer

ATTRIBUTES

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

layer_from_file

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

layer_from_file(name, src, annotations, base_name_annotations, diff_id, diff_id_annotations,
                media_type)

Creates a container image layer from an arbitrary file.

This rule uses any file as a container image layer blob, computing the necessary metadata (digest, size) without any tar-specific processing like compression or optimization.

This is useful for non-tar layer content such as Helm charts, WASM modules, or other OCI artifacts.

If you want to use an existing tar file as a layer, use layer_from_tar instead.

Example:

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

# Use an arbitrary artifact as a layer
layer_from_file(
    name = "artifact_layer",
    src = ":artifact.bin",
    media_type = "application/octet-stream",
    annotations = {
        "org.opencontainers.image.title": "artifact.bin",
    },
)

ATTRIBUTES

layer_from_tar

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

layer_from_tar(name, src, annotations, compress, estargz, media_type, optimize)

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",
    },
)

Output groups

• mtree: a single mtree text file

ATTRIBUTES

file_metadata

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

file_metadata(*, mode, uid, gid, uname, gname, mtime, pax_records)

Creates a JSON-encoded file metadata string for use with image_layer rules.

This function generates JSON metadata that can be used to customize file attributes in container image layers, such as permissions, ownership, and timestamps.

PARAMETERS

RETURNS

JSON-encoded string containing the file metadata.