pull.md

A repository rule to pull image layers using Bazel's downloader.

Typical usage in WORKSPACE.bazel:

load("@rules_oci//oci:pull.bzl", "oci_pull")

# A single-arch base image
oci_pull(
    name = "distroless_java",
    digest = "sha256:161a1d97d592b3f1919801578c3a47c8e932071168a96267698f4b669c24c76d",
    image = "gcr.io/distroless/java17",
)

# A multi-arch base image
oci_pull(
    name = "distroless_static",
    digest = "sha256:c3c3d0230d487c0ad3a0d87ad03ee02ea2ff0b3dcce91ca06a1019e07de05f12",
    image = "gcr.io/distroless/static",
    platforms = [
        "linux/amd64",
        "linux/arm64",
    ],
)

Now you can refer to these as a base layer in BUILD.bazel. The target is named the same as the external repo, so you can use a short label syntax:

oci_image(
    name = "app",
    base = "@distroless_static",
    ...
)

oci_pull

oci_pull(name, image, repository, registry, platforms, digest, tag, reproducible, is_bzlmod)

Repository macro to fetch image manifest data from a remote docker registry.

To use the resulting image, you can use the @wkspc shorthand label, for example if name = "distroless_base", then you can just use base = "@distroless_base" in rules like oci_image.

This shorthand syntax is broken on the command-line prior to Bazel 6.2. See bazelbuild/bazel#4385

PARAMETERS

Name	Description	Default Value
name	repository with this name is created	none
image	the remote image, such as gcr.io/bazel-public/bazel. A tag can be suffixed with a colon, like debian:latest, and a digest can be suffixed with an at-sign, like debian@sha256:e822570981e13a6ef1efcf31870726fbd62e72d9abfdcf405a9d8f566e8d7028. Exactly one of image or {registry,repository} should be set.	None
repository	the image path beneath the registry, such as distroless/static. When set, registry must be set as well.	None
registry	the remote registry domain, such as gcr.io or docker.io. When set, repository must be set as well.	None
platforms	for multi-architecture images, a dictionary of the platforms it supports This creates a separate external repository for each platform, avoiding fetching layers.	None
digest	the digest string, starting with "sha256:", "sha512:", etc. If omitted, instructions for pinning are provided.	None
tag	a tag to choose an image from the registry. Exactly one of tag and digest must be set. Since tags are mutable, this is not reproducible, so a warning is printed.	None
reproducible	Set to False to silence the warning about reproducibility when using tag.	True
is_bzlmod	whether the oci_pull is being called from a module extension	False