claudiouzelac/bazel_rules_container

Open Container Initiative Image Format support for Bazel

Rules

• Overview
• container_image
• container_layer
• container_layer_from_tar

---

Overview

These rules are used for building OCI images.

The container_image rule constructs a tarball which conforms to v0.2.0 of the OCI Image Specification. Currently Docker is the only container runtime which is able to load these images.

Each image can contain multiple layers which can be created via the container_layer rule.

container_image

container_image(name, base, cmd, config_file, entrypoint, env, image_name, image_tag, layers, ports, user, volumes, workdir)

Creates an image which conforms to the OCI Image Serialization specification.

More information on the specification is available at https://github.com/opencontainers/image-spec/blob/v0.2.0/serialization.md.

By default this rule builds partial images which can be loaded into a container runtime via bazel run. To build a standalone image build with .tar at the end if the name. The resulting tarball is compatible with docker load and has the structure:

{image-config-sha256}:
  {layer-sha256}.tar
{image-config-sha256}.json
...
manifest.json

Outputs

%{name}.tar	A container image that contains all partial images which can be loaded standalone by the container runtime.
%{name}.partial.tar	A partial container image that contains no parent images. Used when running the rule to only load changed images into the container runtime.

Attributes

name	Name; Required A unique name for this rule.
base	Label; Optional The base container image on top of which this image will built upon, equivalent to FROM in a Dockerfile.
cmd	List of strings; Optional A command to execute when the image is run.
config_file	Label; Optional Use an existing container configuration file.
entrypoint	List of strings; Optional The entrypoint of the command when the image is run.
env	Dictionary mapping strings to string; Optional Dictionary from environment variable names to their values when running the container. env = { "FOO": "bar", ... }
image_name	String; Optional The name of the image which is used when it is loaded into a container runtime. If not provided it will default to bazel/package_name.
image_tag	String; Optional The tag applied to the image when it is loaded into a container runtime. If not provided it will default to target.
layers	List of labels; Optional List of layers created by container_layer that make up this image.
ports	List of strings; Optional List of ports to expose.
user	String; Optional The user that the image should run as. Because building the image never happens inside a container, this user does not affect the other actions (e.g., adding files).
volumes	List of strings; Optional List of volumes to mount.
workdir	String; Optional Initial working directory when running the container. Because building the image never happens inside a container, this working directory does not affect the other actions (e.g., adding files).

Examples

load("@bazel_rules_container//container:container.bzl", "container_layer", "container_image")

container_layer(
    name = "jessie_layer",
    tars = [":jessie_tar"],
)
container_image(
    name = "jessie",
    layers = [":jessie_layer"],
)

# Using the `nodejs_files` layer from the `container_layer` example
container_image(
    name = "nodejs",
    layers = [":nodejs_files"],
)

container_layer

container_layer(name, data_path, debs, directory, files, mode, symlinks, tars)

Create a tarball that can be used as a layer in a container image.

Outputs

%{name}.layer

The tarball that represents a container layer

Attributes

name	Name; Required A unique name for this rule.
data_path	String; Optional The directory structure from the files is preserved inside the layer but a prefix path determined by data_path is removed from the directory structure. This path can be absolute from the workspace root if starting with a / or relative to the rule's directory. A relative path may start with "./" (or be ".") but cannot go up with "..". By default, the data_path attribute is unused and all files are supposed to have no prefix.
debs	List of labels; Optional A list of Debian packages that will be extracted into the layer.
directory	String; Optional The directory in which to expand the specified files, defaulting to '/'. Only makes sense accompanying one of files/tars/debs.
files	List of labels; Optional A list of files that should be included in the layer.
mode	String; Optional Set the mode of files added by the files attribute.
symlinks	Dictionary mapping strings to string; Optional Symlinks between files in the layer { "/path/to/link": "/path/to/target" }
tars	List of labels; Optional A list of tar files whose content should be in the layer.

Examples

load("@bazel_rules_container//container:container.bzl", "container_layer")

filegroup(
    name = "nodejs_debs",
    srcs = [
        "nodejs.deb",
        "libgdbm3.deb",
        "perl.deb",
        "perl_modules.deb",
        "rlwrap.deb",
    ],
)

container_layer(
    name = "nodejs_files",
    debs = [":nodejs_debs"],
    symlinks = { "/usr/bin/node": "/usr/bin/nodejs" },
)

container_layer_from_tar

container_layer_from_tar(name, tar)

Uses an existing tarball as a layer in a container image.

Outputs

%{name}.layer

The tarball represented as a container layer

Attributes

name	Name; Required A unique name for this rule.
tar	Label; Required A tar file that will be the layer.

Examples

load("@bazel_rules_container//container:container.bzl", "container_layer_from_tar")

genrule(
  name = "jessie_tar",
  srcs = ["@debian_jessie//file"],
  outs = ["jessie_extracted.tar"],
  cmd = "cat $< | xzcat >$@",
)

container_layer_from_tar(
    name = "jessie",
    tar = ":jessie_tar",
)

Pull a container from a registry

Rules

• container_pull

## container_pull

container_pull(name, image_name, image_reference, image_tag, registry)

Pulls an image from a container registry.

If you use a registry that requires authentication, set up a local registry that proxies it by following: https://blog.docker.com/2015/10/registry-proxy-cache-docker-open-source/

Attributes

name	Name; Required A unique name for this rule.
image_name	String; Required The name of the image to pull.
image_reference	String; Required The sha256 digest of the image.
image_tag	String; Optional The tag of the image, only used for tagging not for pulling.
registry	String; Required The url of the container registry.

Examples

load("@bazel_rules_container//container:pull.bzl", "container_pull")

container_pull(
  name = "debian_jessie",
  registry = "http://docker-registry:5000",
  image_name = "debian",
  image_tag = "8.5",
  image_reference = "ffb60fdbc401b2a692eef8d04616fca15905dce259d1499d96521970ed0bec36",
)

Container testing

Rules

• Overview
• container_test

---

Overview

Based on Jsonnet jsonnet_to_json_test

container_test

container_test(name, daemon, env, error, files, golden, image, mem_limit, regex, test, volume_files, volume_mounts)

Experimental container testing.

Does not work with sandboxing enabled.

Attributes

name	Name; Required A unique name for this rule.
daemon	Boolean; Optional Whether to run the container as a daemon or execute the test inside.
env	Dictionary mapping strings to string; Optional Dictionary from environment variable names to their values when running the container. env = { "FOO": "bar", ... }
error	Integer; Optional The expected error code.
files	List of labels; Optional Any files that the test script might require.
golden	Label; Optional The expected output.
image	Label; Optional The image to run tests on.
mem_limit	String; Optional Memory limit to add to the container.
regex	Boolean; Optional Set to 1 if golden contains a regex to match against the output.
test	Label; Optional Test script to run.
volume_files	List of labels; Optional List of files to mount.
volume_mounts	List of strings; Optional List of mount points that match volume_mounts.

Examples

load("@bazel_rules_container//container:test.bzl", "container_test")

container_test(
    name = "nodejs",
    size = "small",
    files = [
        "project/index.js",
        "project/package.json",
    ],
    golden = "output.txt",
    image = "//nodejs",
    test = "test.sh",
)