Generated API documentation for rules that manipulating containers.
Load these from @io_bazel_rules_docker//container:container.bzl
.
Rules
container_bundle
A rule that aliases and saves N images into a single docker save
tarball.
Example usage (generated)
load("@rules_docker//container:container.docs.bzl", "container_bundle")
container_bundle(
# A unique name for this target.
name = "",
)
name
A unique name for this target.
extract_config
image_target_strings
image_targets
images
incremental_load_template
stamp
tar_output
container_flatten
A rule to flatten container images.
Example usage (generated)
load("@rules_docker//container:container.docs.bzl", "container_flatten")
container_flatten(
# A unique name for this target.
name = "",
image = "",
)
name
A unique name for this target.
extract_config
image
incremental_load_template
container_import
A rule that imports a docker image into our intermediate form.
Example usage (generated)
load("@rules_docker//container:container.docs.bzl", "container_import")
container_import(
# A unique name for this target.
name = "",
# The list of layer .tar.gz files in the order they appear in the config.json's layer section,
layers = [],
)
name
A unique name for this target.
base_image_digest
The digest of the image
base_image_registry
The registry from which we pulled the image
base_image_repository
The repository from which we pulled the image
config
A json configuration file containing the image's metadata.
This appears in docker save
tarballs as .json
and is referenced by manifest.json
in the config field.
extract_config
incremental_load_template
layers
The list of layer .tar.gz files in the order they appear in the config.json's layer section,
or in the order that they appear in the Layers
field of the docker save tarballs'
manifest.json
(these may or may not be gzipped).
Note that the layers should each have a different basename.
manifest
repository
sha256
container_layer
A rule that assembles data into a tarball which can be use as in layers attr in container_image rule.
Example usage (generated)
load("@rules_docker//container:container.docs.bzl", "container_layer")
container_layer(
# A unique name for this target.
name = "",
)
name
A unique name for this target.
build_layer
compression
compression_options
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.
empty_dirs
empty_files
enable_mtime_preservation
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.
extract_config
files
File to add to the layer.
A list of files that should be included in the Docker image.
incremental_load_template
mode
Set the mode of files added by the files
attribute.
mtime
operating_system
portable_mtime
sha256
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.
container_load
A repository rule that examines the contents of a docker save tarball and creates a container_import target.
This extracts the tarball amd creates a filegroup of the untarred objects in OCI intermediate layout.
The created target can be referenced as @label_name//image
.
Example usage (generated)
load("@rules_docker//container:container.docs.bzl", "container_load")
container_load(
# A unique name for this repository.
name = "",
# A label targeting a single file which is a compressed or uncompressed tar,
file = "",
# A dictionary from local repository name to global repository name
repo_mapping = {},
)
name
A unique name for this repository.
file
A label targeting a single file which is a compressed or uncompressed tar,
as obtained through docker save IMAGE
.
repo_mapping
A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.
For example, an entry "@foo": "@bar"
declares that, for any time this repository depends on @foo
(such as a dependency on @foo//some:target
, it should actually resolve that dependency within globally-declared @bar
(@bar//some:target
).
container_pull
A repository rule that pulls down a Docker base image in a manner suitable for use with the base
attribute of container_image
.
This is based on google/containerregistry using google/go-containerregistry. It wraps the rulesdocker.go.cmd.puller.puller executable in a Bazel rule for downloading base images without a Docker client to construct new images.
NOTE: container_pull
now supports authentication using custom docker client configuration.
See here for details.
NOTE: Set PULLER_TIMEOUT
env variable to change the default 600s timeout.
NOTE: Set DOCKER_REPO_CACHE
env variable to make the container puller cache downloaded layers at the directory specified as a value to this env variable.
The caching feature hasn't been thoroughly tested and may be thread unsafe.
If you notice flakiness after enabling it, see the warning below on how to workaround it.
NOTE: container_pull
is suspected to have thread safety issues.
To ensure multiple container_pull
(s) don't execute concurrently,
please use the bazel startup flag --loading_phase_threads=1
in your bazel invocation
(typically by adding startup --loading_phase_threads=1
as a line in your .bazelrc
)
Example usage (generated)
load("@rules_docker//container:container.docs.bzl", "container_pull")
container_pull(
# A unique name for this repository.
name = "",
# The registry from which we are pulling.
registry = "",
# A dictionary from local repository name to global repository name
repo_mapping = {},
# The name of the image.
repository = "",
)
name
A unique name for this repository.
architecture
Which CPU architecture to pull if this image refers to a multi-platform manifest list, default 'amd64'.
cpu_variant
Which CPU variant to pull if this image refers to a multi-platform manifest list.
digest
The digest of the image to pull.
docker_client_config
Specifies a custom directory to look for the docker client configuration.
Don't use this directly.
Instead, specify the docker configuration directory using a custom docker toolchain configuration.
Look for the client_config
attribute in docker_toolchain_configure
here for details.
See here
for an example on how to use container_pull after configuring the docker toolchain
When left unspecified (ie not set explicitly or set by the docker toolchain),
docker will use the directory specified via the DOCKER_CONFIG
environment variable.
If DOCKER_CONFIG
isn't set, docker falls back to $HOME/.docker
.
import_tags
Tags to be propagated to generated rules.
os
Which os to pull if this image refers to a multi-platform manifest list.
os_features
Specifies os features when pulling a multi-platform manifest list.
os_version
Which os version to pull if this image refers to a multi-platform manifest list.
platform_features
Specifies platform features when pulling a multi-platform manifest list.
puller_darwin
Exposed to provide a way to test other pullers on macOS
puller_linux_amd64
Exposed to provide a way to test other pullers on Linux
puller_linux_arm64
Exposed to provide a way to test other pullers on Linux
puller_linux_s390x
Exposed to provide a way to test other pullers on Linux
registry
The registry from which we are pulling.
repo_mapping
A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.
For example, an entry "@foo": "@bar"
declares that, for any time this repository depends on @foo
(such as a dependency on @foo//some:target
, it should actually resolve that dependency within globally-declared @bar
(@bar//some:target
).
repository
The name of the image.
tag
The tag
of the Docker image to pull from the specified repository
.
If neither this nor digest
is specified, this attribute defaults to latest
.
If both are specified, then tag
is ignored.
Note: For reproducible builds, use of digest
is recommended.
container_push
Example usage (generated)
load("@rules_docker//container:container.docs.bzl", "container_push")
container_push(
# A unique name for this target.
name = "",
# The form to push: Docker or OCI, default to 'Docker'.
format = "",
# The label of the image to push.
image = "",
# The registry to which we are pushing.
registry = "",
# The name of the image.
repository = "",
# The script template to use.
tag_tpl = "",
windows_paths = false,
)
name
A unique name for this target.
extension
The file extension for the push script.
extract_config
format
The form to push: Docker or OCI, default to 'Docker'.
image
The label of the image to push.
incremental_load_template
registry
The registry to which we are pushing.
repository
The name of the image.
repository_file
The label of the file with repository value. Overrides 'repository'.
skip_unchanged_digest
Only push images if the digest has changed, default to False
stamp
tag
The tag of the image.
tag_file
The label of the file with tag value. Overrides 'tag'.
tag_tpl
The script template to use.
windows_paths
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.
Example usage (generated)
load("@rules_docker//container:container.docs.bzl", "container_image")
container_image(
)
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,
)
Example usage (generated)
load("@rules_docker//container:container.docs.bzl", "image")
image.implementation(
# The bazel rule context
ctx = None,
)
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