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.

container_image_

container_image_(name, architecture, base, build_layer, cmd, compression, compression_options,
                 create_image_config, creation_time, data_path, debs, directory, docker_run_flags,
                 empty_dirs, empty_files, enable_mtime_preservation, entrypoint, env,
                 experimental_tarball_format, extract_config, files, incremental_load_template,
                 label_file_strings, label_files, labels, launcher, launcher_args, layers,
                 legacy_repository_naming, legacy_run_behavior, mode, mtime, null_cmd,
                 null_entrypoint, operating_system, os_version, portable_mtime, ports, repository,
                 sha256, stamp, symlinks, tars, user, volumes, workdir)

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

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
architecture	The desired CPU architecture to be used as label in the container image.	String	optional	"amd64"
base	The base layers on top of which to overlay this layer, equivalent to FROM.	Label	optional	None
build_layer	-	Label	optional	//container:build_tar
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.	List of strings	optional	[]
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.	String	optional	"gzip"
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.	List of strings	optional	[]
create_image_config	-	Label	optional	//container/go/cmd/create_image_config: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	String	optional	""
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.	String	optional	""
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.	List of labels	optional	[]
directory	Target directory. The directory in which to expand the specified files, defaulting to '/'. Only makes sense accompanying one of files/tars/debs.	String	optional	"/"
docker_run_flags	Optional flags to use with `docker run` command. Only used when `legacy_run_behavior` is set to `False`.	String	optional	""
empty_dirs	-	List of strings	optional	[]
empty_files	-	List of strings	optional	[]
enable_mtime_preservation	-	Boolean	optional	False
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.	List of strings	optional	[]
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.	Dictionary: String -> String	optional	{}
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.	String	optional	"legacy"
extract_config	-	Label	optional	//container/go/cmd/extract_config:extract_config
files	File to add to the layer. A list of files that should be included in the Docker image.	List of labels	optional	[]
incremental_load_template	-	Label	optional	//container:incremental_load_template
label_file_strings	-	List of strings	optional	[]
label_files	-	List of labels	optional	[]
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.	Dictionary: String -> String	optional	{}
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).	Label	optional	None
launcher_args	Optional arguments for the `launcher` attribute. Only valid when `launcher` is specified.	List of strings	optional	[]
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.	List of labels	optional	[]
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}`	Boolean	optional	False
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 <lang>_image rules.	Boolean	optional	True
mode	Set the mode of files added by the `files` attribute.	String	optional	"0o555"
mtime	-	Integer	optional	-1
null_cmd	-	Boolean	optional	False
null_entrypoint	-	Boolean	optional	False
operating_system	-	String	optional	"linux"
os_version	The desired OS version to be used in the container image config.	String	optional	""
portable_mtime	-	Boolean	optional	False
ports	List of ports to expose. See https://docs.docker.com/engine/reference/builder/#expose	List of strings	optional	[]
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`.	String	optional	"bazel"
sha256	-	Label	optional	//tools/build_defs/hash: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`.	Boolean	optional	False
symlinks	Symlinks to create in the Docker image. For example, symlinks = { "/path/to/link": "/path/to/target", ... },	Dictionary: String -> String	optional	{}
tars	Tar file to extract in the layer. A list of tar files whose content should be in the Docker image.	List of labels	optional	[]
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.	String	optional	""
volumes	List of volumes to mount. See https://docs.docker.com/engine/reference/builder/#volumes	List of strings	optional	[]
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.	String	optional	""

container_image

container_image(kwargs)

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.

PARAMETERS

Name	Description	Default Value
kwargs	Attributes are described by `container_image_` above.	none

image.implementation

image.implementation(ctx, name, base, files, file_map, empty_files, empty_dirs, directory,
                     entrypoint, cmd, creation_time, symlinks, env, layers, compression,
                     compression_options, experimental_tarball_format, debs, tars, architecture,
                     operating_system, os_version, output_executable, output_tarball, output_config,
                     output_config_digest, output_digest, output_layer, workdir, null_cmd,
                     null_entrypoint)

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,
)

PARAMETERS

Name	Description	Default Value
ctx	The bazel rule context	none
name	str, overrides ctx.label.name or ctx.attr.name	`None`
base	File, overrides ctx.attr.base and ctx.files.base[0]	`None`
files	File list, overrides ctx.files.files	`None`
file_map	Dict[str, File], defaults to {}	`None`
empty_files	str list, overrides ctx.attr.empty_files	`None`
empty_dirs	Dict[str, str], overrides ctx.attr.empty_dirs	`None`
directory	str, overrides ctx.attr.directory	`None`
entrypoint	str List, overrides ctx.attr.entrypoint	`None`
cmd	str List, overrides ctx.attr.cmd	`None`
creation_time	str, overrides ctx.attr.creation_time	`None`
symlinks	str Dict, overrides ctx.attr.symlinks	`None`
env	str Dict, overrides ctx.attr.env	`None`
layers	label List, overrides ctx.attr.layers	`None`
compression	str, overrides ctx.attr.compression	`None`
compression_options	str list, overrides ctx.attr.compression_options	`None`
experimental_tarball_format	str, overrides ctx.attr.experimental_tarball_format	`None`
debs	File list, overrides ctx.files.debs	`None`
tars	File list, overrides ctx.files.tars	`None`
architecture	str, overrides ctx.attr.architecture	`None`
operating_system	Operating system to target (e.g. linux, windows)	`None`
os_version	Operating system version to target	`None`
output_executable	File to use as output for script to load docker image	`None`
output_tarball	File, overrides ctx.outputs.out	`None`
output_config	File, overrides ctx.outputs.config	`None`
output_config_digest	File, overrides ctx.outputs.config_digest	`None`
output_digest	File, overrides ctx.outputs.digest	`None`
output_layer	File, overrides ctx.outputs.layer	`None`
workdir	str, overrides ctx.attr.workdir	`None`
null_cmd	bool, overrides ctx.attr.null_cmd	`None`
null_entrypoint	bool, overrides ctx.attr.null_entrypoint	`None`

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

image.md

image.md

container_image_

container_image

image.implementation

Files

image.md

Latest commit

History

image.md

File metadata and controls

container_image_

container_image

image.implementation