Skip to content

Latest commit

 

History

History
125 lines (91 loc) · 9.12 KB

image.md

File metadata and controls

125 lines (91 loc) · 9.12 KB
Raw

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, tars, user, variant, 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. 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 ""
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 ""
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, 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
kwargs other named arguments to oci_image_rule and common rule attributes. none