image

To load these rules, add this to the top of your BUILD file:

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

Rules

oci_image_rule

Build an OCI compatible container image.

Note, most users should use the wrapper macro instead of this rule directly. See oci_image.

It takes number of tar files as layers to create image filesystem. For incrementality, use more fine-grained tar files to build up the filesystem, and choose an order so that less-frequently changed files appear earlier in the list.

oci_image(
    # do not sort
    tars = [
        "rootfs.tar",
        "appfs.tar",
        "libc6.tar",
        "passwd.tar",
    ]
)

To base an oci_image on another oci_image, the base attribute can be used.

oci_image(
    base = "//sys:base",
    tars = [
        "appfs.tar"
    ]
)

To combine env with environment variables from the base, bash style variable syntax can be used.

oci_image(
    name = "base",
    env = {"PATH": "/usr/bin"}
)

oci_image(
    name = "app",
    base = ":base",
    env = {"PATH": "/usr/local/bin:$PATH"}
)

Example usage (generated):

load("@rules_oci//oci:defs.bzl", "oci_image_rule")

oci_image_rule(
    # A unique name for this target.
    name = "",
)

name

Required name.

A unique name for this target.

annotations

Optional label. Default: None

A file containing a dictionary of annotations. Each line should be in the form name=value.

architecture

Optional string. Default: ""

The CPU architecture which the binaries in this image are built to run on. eg: arm64, arm, amd64, s390x. See $GOARCH documentation for possible values: https://go.dev/doc/install/source#environment

base

Optional label. Default: None

Label to an oci_image target to use as the base.

cmd

Optional label. Default: None

A file containing a comma separated list to be used as the command & args of the container. These values act as defaults and may be replaced by any specified when creating a container.

entrypoint

Optional label. Default: None

A file containing a comma separated list to be used as the entrypoint to execute when the container starts. These values act as defaults and may be replaced by an entrypoint specified when creating a container.

env

Optional label. Default: None

A file containing the default values for the environment variables of the container. These values act as defaults and are merged with any specified when creating a container. Entries replace the base environment variables if any of the entries has conflicting keys. To merge entries with keys specified in the base, ${KEY} or $KEY syntax may be used.

labels

Optional label. Default: None

A file containing a dictionary of labels. Each line should be in the form name=value.

os

Optional string. Default: ""

The name of the operating system which the image is built to run on. eg: linux, windows. See $GOOS documentation for possible values: https://go.dev/doc/install/source#environment

tars

Optional list of labels. Default: []

    List of tar files to add to the image as layers.

Do not sort this list; the order is preserved in the resulting image. Less-frequently changed files belong in lower layers to reduce the network bandwidth required to pull and push.

The authors recommend dive to explore the layering of the resulting image.

user

Optional string. Default: ""

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. For Linux based systems, all of the following are valid: user, uid, user:group, uid:gid, uid:group, user:gid. If group/gid is not specified, the default group and supplementary groups of the given user/uid in /etc/passwd from the container are applied.

variant

Optional string. Default: ""

The variant of the specified CPU architecture. eg: v6, v7, v8. See: https://github.com/opencontainers/image-spec/blob/main/image-index.md#platform-variants for more.

workdir

Optional string. Default: ""

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.

Macros and Functions

oci_image

Macro wrapper around oci_image_rule.

Allows labels and annotations to be provided as a dictionary, in addition to a text file. See https://github.com/opencontainers/image-spec/blob/main/annotations.md

Label/annotation/env can by configured using either dict(key->value) or a file that contains key=value pairs (one per line). The file can be preprocessed using (e.g. using jq) to supply external (potentially not deterministic) information when running with --stamp flag. See the example in /examples/labels/BUILD.bazel.

Produces a target [name].digest, whose default output is a file containing the sha256 digest of the resulting image. This is similar to the same-named target created by rules_docker's container_image macro.

Example usage (generated):

load("@rules_oci//oci:defs.bzl", "oci_image")

oci_image(
    # name of resulting oci_image_rule
    name = "",
)

name

Required.

name of resulting oci_image_rule

labels

Optional. Default: None

Labels for the image config. See documentation above.

annotations

Optional. Default: None

Annotations for the image config. See documentation above.

env

Optional. Default: None

Environment variables provisioned by default to the running container. See documentation above.

cmd

Optional. Default: None

Command & argument configured by default in the running container. See documentation above.

entrypoint

Optional. Default: None

Entrypoint configured by default in the running container. See documentation above.

kwargs

Optional.

other named arguments to oci_image_rule and common rule attributes.