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
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
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 whatdocker 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 changedlayers 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
symlinks
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