Rule for building a Container image.

In addition to the base container_image rule, we expose its constituents (attr, outputs, implementation) directly so that others may expose a more specialized build leveraging the same implementation.

Rules

container_image_

Called by the container_image macro with **kwargs, see below

name

A unique name for this target.

architecture

The desired CPU architecture to be used as label in the container image.

base

The base layers on top of which to overlay this layer, equivalent to FROM.

build_layer

cmd

List of commands to execute in the image.

See https://docs.docker.com/engine/reference/builder/#cmd

The behavior between using "" and [] may differ. Please see #1448 for more details.

Set cmd to None, [] or "" will set the Cmd of the image to be null.

This field supports stamp variables.

compression

Compression method for image layer. Currently only gzip is supported.

This affects the compressed layer, which is by the container_push rule. It doesn't affect the layers specified by the layers attribute.

compression_options

Command-line options for the compression tool. Possible values depend on compression method.

This affects the compressed layer, which is used by the container_push rule. It doesn't affect the layers specified by the layers attribute.

create_image_config

creation_time

The image's creation timestamp.

Acceptable formats: Integer or floating point seconds since Unix Epoch, RFC 3339 date/time.

This field supports stamp variables.

If not set, defaults to {BUILD_TIMESTAMP} when stamp = True, otherwise 0

data_path

Root path of the files.

The directory structure from the files is preserved inside the Docker image, 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 starts with "./" (or be ".") but cannot use go up with "..". By default, the data_path attribute is unused, and all files should have no prefix.

debs

Debian packages to extract.

Deprecated: A list of debian packages that will be extracted in the Docker image. Note that this doesn't actually install the packages. Installation needs apt or apt-get which need to be executed within a running container which container_image can't do.

directory

Target directory.

The directory in which to expand the specified files, defaulting to '/'. Only makes sense accompanying one of files/tars/debs.

docker_run_flags

Optional flags to use with docker run command.

Only used when legacy_run_behavior is set to False.

empty_dirs

empty_files

enable_mtime_preservation

entrypoint

List of entrypoints to add in the image.

See https://docs.docker.com/engine/reference/builder/#entrypoint

Set entrypoint to None, [] or "" will set the Entrypoint of the image to be null.

The behavior between using "" and [] may differ. Please see #1448 for more details.

This field supports stamp variables.

env

Dictionary from environment variable names to their values when running the Docker image.

See https://docs.docker.com/engine/reference/builder/#env

For example,

env = {
    "FOO": "bar",
    ...
}, 

The values of this field support make variables (e.g., $(FOO)) and stamp variables; keys support make variables as well.

experimental_tarball_format

The tarball format to use when producing an image .tar file. Defaults to "legacy", which contains uncompressed layers. If set to "compressed", the resulting tarball will contain compressed layers, but is only loadable by newer versions of docker. This is an experimental attribute, which is subject to change or removal: do not depend on its exact behavior.

extract_config

files

File to add to the layer.

A list of files that should be included in the Docker image.

incremental_load_template

label_file_strings

label_files

labels

Dictionary from custom metadata names to their values.

See https://docs.docker.com/engine/reference/builder/#label

You can also put a file name prefixed by '@' as a value. Then the value is replaced with the contents of the file.

Example:

labels = {
    "com.example.foo": "bar",
    "com.example.baz": "@metadata.json",
    ...
},

The values of this field support stamp variables.

launcher

If present, prefix the image's ENTRYPOINT with this file.

Note that the launcher should be a container-compatible (OS & Arch) single executable file without any runtime dependencies (as none of its runfiles will be included in the image).

launcher_args

Optional arguments for the launcher attribute.

Only valid when launcher is specified.

layers

List of container_layer targets.

The data from each container_layer will be part of container image, and the environment variable will be available in the image as well.

legacy_repository_naming

Whether to use the legacy strategy for setting the repository name embedded in the resulting tarball.

e.g. bazel/{target.replace('/', '_')} vs. bazel/{target}

legacy_run_behavior

If set to False, bazel run will directly invoke docker run with flags specified in the docker_run_flags attribute. Note that it defaults to False when using _image rules.

mode

Set the mode of files added by the files attribute.

mtime

null_cmd

null_entrypoint

operating_system

os_version

The desired OS version to be used in the container image config.

portable_mtime

ports

List of ports to expose.

See https://docs.docker.com/engine/reference/builder/#expose

repository

The repository for the default tag for the image.

Images generated by container_image are tagged by default to bazel/package_name:target for a container_image target at //package/name:target.

Setting this attribute to gcr.io/dummy would set the default tag to gcr.io/dummy/package_name:target.

sha256

stamp

If true, enable use of workspace status variables (e.g. BUILD_USER, BUILD_EMBED_LABEL, and custom values set using --workspace_status_command) in tags.

These fields are specified in attributes using Python format syntax, e.g. foo{BUILD_USER}bar.

Symlinks to create in the Docker image.

For example,

symlinks = {
    "/path/to/link": "/path/to/target",
    ...
},

tars

Tar file to extract in the layer.

A list of tar files whose content should be in the Docker image.

user

The user that the image should run as.

See https://docs.docker.com/engine/reference/builder/#user

Because building the image never happens inside a Docker container, this user does not affect the other actions (e.g., adding files).

This field supports stamp variables.

volumes

List of volumes to mount.

See https://docs.docker.com/engine/reference/builder/#volumes

workdir

Initial working directory when running the Docker image.

See https://docs.docker.com/engine/reference/builder/#workdir

Because building the image never happens inside a Docker container, this working directory does not affect the other actions (e.g., adding files).

This field supports stamp variables.


Macros and Functions

container_image

Package a docker image.

Produces a new container image tarball compatible with 'docker load', which is a single additional layer atop 'base'. The goal is to have relatively complete support for building container image, from the Dockerfile spec.

For more information see the 'Config' section of the image specification: https://github.com/opencontainers/image-spec/blob/v0.2.0/serialization.md

Only 'name' is required. All other fields have sane defaults.

container_image(
    name="...",
    visibility="...",

    # The base layers on top of which to overlay this layer,
    # equivalent to FROM.
    base="//another/build:rule",

    # The base directory of the files, defaulted to
    # the package of the input.
    # All files structure relatively to that path will be preserved.
    # A leading '/' mean the workspace root and this path is relative
    # to the current package by default.
    data_path="...",

    # The directory in which to expand the specified files,
    # defaulting to '/'.
    # Only makes sense accompanying one of files/tars/debs.
    directory="...",

    # The set of archives to expand, or packages to install
    # within the chroot of this layer
    files=[...],
    tars=[...],
    debs=[...],

    # The set of symlinks to create within a given layer.
    symlinks = {
        "/path/to/link": "/path/to/target",
        ...
    },

    # Other layers built from container_layer rule
    layers = [":c-lang-layer", ":java-lang-layer", ...]

    # https://docs.docker.com/engine/reference/builder/#entrypoint
    entrypoint="...", or
    entrypoint=[...],            -- exec form
    Set entrypoint to None, [] or "" will set the Entrypoint of the image to
    be null.

    # https://docs.docker.com/engine/reference/builder/#cmd
    cmd="...", or
    cmd=[...],                   -- exec form
    Set cmd to None, [] or "" will set the Cmd of the image to be null.

    # https://docs.docker.com/engine/reference/builder/#expose
    ports=[...],

    # https://docs.docker.com/engine/reference/builder/#user
    # NOTE: the normal directive affects subsequent RUN, CMD,
    # and ENTRYPOINT
    user="...",

    # https://docs.docker.com/engine/reference/builder/#volume
    volumes=[...],

    # https://docs.docker.com/engine/reference/builder/#workdir
    # NOTE: the normal directive affects subsequent RUN, CMD,
    # ENTRYPOINT, ADD, and COPY, but this attribute only affects
    # the entry point.
    workdir="...",

    # https://docs.docker.com/engine/reference/builder/#env
    env = {
        "var1": "val1",
        "var2": "val2",
        ...
        "varN": "valN",
    },

    # Compression method and command-line options.
    compression = "gzip",
    compression_options = ["--fast"],
    experimental_tarball_format = "compressed",
)

This rule generates a sequence of genrules the last of which is named 'name', so the dependency graph works out properly. The output of this rule is a tarball compatible with 'docker save/load' with the structure:

{layer-name}:
layer.tar
VERSION
json
{image-config-sha256}.json
...
manifest.json
repositories
top     # an implementation detail of our rules, not consumed by Docker.

This rule appends a single new layer to the tarball of this form provided via the 'base' parameter.

The images produced by this rule are always named bazel/tmp:latest when loaded (an internal detail). The expectation is that the images produced by these rules will be uploaded using the docker_push rule below.

The implicit output targets are:

  • [name].tar: A full Docker image containing all the layers, identical to what docker save would return. This is only generated on demand.

  • [name].digest: An image digest that can be used to refer to that image. Unlike tags, digest references are immutable i.e. always refer to the same content.

  • [name]-layer.tar: A Docker image containing only the layer corresponding to that target. It is used for incremental loading of the layer.

    Note: this target is not suitable for direct consumption. It is used for incremental loading and non-docker rules should depend on the Docker image ([name].tar) instead.

  • [name]: The incremental image loader. It will load only changed

      layers inside the Docker registry.
    

This rule references the @io_bazel_rules_docker//toolchains/docker:toolchain_type. See How to use the Docker Toolchain for details.

kwargs

Attributes are described by container_image_ above.


image.implementation

Implementation for the container_image rule.

You can write a customized container_image rule by writing something like:

load(
    "@io_bazel_rules_docker//container:container.bzl",
    _container="container",
)

def _impl(ctx):
    ...
    return _container.image.implementation(ctx, ... kwarg overrides ...)

_foo_image = rule(
    attrs = _container.image.attrs + {
        # My attributes, or overrides of _container.image.attrs defaults.
        ...
    },
    executable = True,
    outputs = _container.image.outputs,
    implementation = _impl,
)

ctx

The bazel rule context

name

str, overrides ctx.label.name or ctx.attr.name

base

File, overrides ctx.attr.base and ctx.files.base[0]

files

File list, overrides ctx.files.files

file_map

Dict[str, File], defaults to {}

empty_files

str list, overrides ctx.attr.empty_files

empty_dirs

Dict[str, str], overrides ctx.attr.empty_dirs

directory

str, overrides ctx.attr.directory

entrypoint

str List, overrides ctx.attr.entrypoint

cmd

str List, overrides ctx.attr.cmd

creation_time

str, overrides ctx.attr.creation_time

str Dict, overrides ctx.attr.symlinks

env

str Dict, overrides ctx.attr.env

layers

label List, overrides ctx.attr.layers

compression

str, overrides ctx.attr.compression

compression_options

str list, overrides ctx.attr.compression_options

experimental_tarball_format

str, overrides ctx.attr.experimental_tarball_format

debs

File list, overrides ctx.files.debs

tars

File list, overrides ctx.files.tars

architecture

str, overrides ctx.attr.architecture

operating_system

Operating system to target (e.g. linux, windows)

os_version

Operating system version to target

output_executable

File to use as output for script to load docker image

output_tarball

File, overrides ctx.outputs.out

output_config

File, overrides ctx.outputs.config

output_config_digest

File, overrides ctx.outputs.config_digest

output_digest

File, overrides ctx.outputs.digest

output_layer

File, overrides ctx.outputs.layer

workdir

str, overrides ctx.attr.workdir

null_cmd

bool, overrides ctx.attr.null_cmd

null_entrypoint

bool, overrides ctx.attr.null_entrypoint