pull

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

Macros and Functions

oci_pull

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 https://github.com/bazelbuild/bazel/issues/4385

Example usage (generated):

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

oci_pull(
    # repository with this name is created
    name = "",
)

name

Required.

repository with this name is created

image

Optional. Default: None

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.

repository

Optional. Default: None

the image path beneath the registry, such as distroless/static. When set, registry must be set as well.

registry

Optional. Default: None

the remote registry domain, such as gcr.io or docker.io. When set, repository must be set as well.

platforms

Optional. Default: None

for multi-architecture images, a dictionary of the platforms it supports This creates a separate external repository for each platform, avoiding fetching layers.

digest

Optional. Default: None

the digest string, starting with "sha256:", "sha512:", etc. If omitted, instructions for pinning are provided.

tag

Optional. Default: None

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.

reproducible

Optional. Default: True

Set to False to silence the warning about reproducibility when using tag.

is_bzlmod

Optional. Default: False

whether the oci_pull is being called from a module extension