image.md

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

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

oci_image_rule

oci_image_rule(name, annotations, architecture, base, cmd, entrypoint, env, exposed_ports, labels,
               os, resource_set, tars, user, variant, volumes, workdir)

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

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
annotations	A file containing a dictionary of annotations. Each line should be in the form name=value.	Label	optional	None
architecture	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	String	optional	""
base	Label to an oci_image target to use as the base.	Label	optional	None
cmd	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.	Label	optional	None
entrypoint	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. NOTE: Setting this attribute will reset the cmd attribute	Label	optional	None
env	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.	Label	optional	None
exposed_ports	A file containing a comma separated list of exposed ports. (e.g. 2000/tcp, 3000/udp or 4000. No protocol defaults to tcp).	Label	optional	None
labels	A file containing a dictionary of labels. Each line should be in the form name=value.	Label	optional	None
os	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	String	optional	""
resource_set	A predefined function used as the resource_set for actions. Used with --experimental_action_resource_set to reserve more RAM/CPU, preventing Bazel overscheduling resource-intensive actions. By default, Bazel allocates 1 CPU and 250M of RAM. https://github.com/bazelbuild/bazel/blob/058f943037e21710837eda9ca2f85b5f8538c8c5/src/main/java/com/google/devtools/build/lib/actions/AbstractAction.java#L77	String	optional	"default"
tars	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.	List of labels	optional	[]
user	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.	String	optional	""
variant	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.	String	optional	""
volumes	A file containing a comma separated list of volumes. (e.g. /srv/data,/srv/other-data)	Label	optional	None
workdir	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.	String	optional	""

oci_image

oci_image(name, labels, annotations, env, cmd, entrypoint, exposed_ports, volumes, kwargs)

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.

PARAMETERS

Name	Description	Default Value
name	name of resulting oci_image_rule	none
labels	Labels for the image config. See documentation above.	None
annotations	Annotations for the image config. See documentation above.	None
env	Environment variables provisioned by default to the running container. See documentation above.	None
cmd	Command & argument configured by default in the running container. See documentation above.	None
entrypoint	Entrypoint configured by default in the running container. See documentation above.	None
exposed_ports	Exposed ports in the running container. See documentation above.	None
volumes	Volumes for the container. See documentation above.	None
kwargs	other named arguments to oci_image_rule and common rule attributes.	none