container.md

March 3, 2023 · View on GitHub

Generated API documentation for rules that manipulating containers.

Load these from @io_bazel_rules_docker//container:container.bzl.

container_bundle

container_bundle(name, experimental_tarball_format, extract_config, image_target_strings,
                 image_targets, images, incremental_load_template, stamp, tar_output)

A rule that aliases and saves N images into a single docker save tarball.

This can be consumed in 2 different ways:

The output tarball could be used for docker load to load all images to docker daemon.
The emitted BundleInfo provider could be consumed by contrib/push-all.bzl rules to create an executable target which tag and push multiple images to a container registry.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
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
image_target_strings	-	List of strings	optional	[]
image_targets	-	List of labels	optional	[]
images	-	Dictionary: String -> String	optional	{}
incremental_load_template	-	Label	optional	//container:incremental_load_template
stamp	Whether to encode build information into the output. Possible values: - `@io_bazel_rules_docker//stamp:always`: Always stamp the build information into the output, even in [--nostamp][stamp] builds. This setting should be avoided, since it potentially causes cache misses remote caching for any downstream actions that depend on it. - `@io_bazel_rules_docker//stamp:never`: Always replace build information by constant values. This gives good build result caching. - `@io_bazel_rules_docker//stamp:use_stamp_flag`: Embedding of build information is controlled by the [--[no]stamp][stamp] flag. Stamped binaries are not rebuilt unless their dependencies change. [stamp]: https://docs.bazel.build/versions/main/user-manual.html#flag--stamp	Label	optional	@io_bazel_rules_docker//stamp:use_stamp_flag
tar_output	-	Label	optional

container_flatten

container_flatten(name, extract_config, image, incremental_load_template)

A rule to flatten container images.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
extract_config	-	Label	optional	//container/go/cmd/extract_config:extract_config
image	-	Label	required
incremental_load_template	-	Label	optional	//container:incremental_load_template

container_import

container_import(name, base_image_digest, base_image_registry, base_image_repository, config,
                 extract_config, incremental_load_template, layers, manifest, repository, sha256)

A rule that imports a docker image into our intermediate form.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
base_image_digest	The digest of the image	String	optional	""
base_image_registry	The registry from which we pulled the image	String	optional	""
base_image_repository	The repository from which we pulled the image	String	optional	""
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.	Label	optional	None
extract_config	-	Label	optional	//container/go/cmd/extract_config:extract_config
incremental_load_template	-	Label	optional	//container: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.	List of labels	required
manifest	-	Label	optional	None
repository	-	String	optional	"bazel"
sha256	-	Label	optional	//container/go/cmd/sha256:sha256

container_layer

container_layer(name, build_layer, compression, compression_options, data_path, debs, directory,
                empty_dirs, empty_files, enable_mtime_preservation, env, extract_config, files,
                incremental_load_template, mode, mtime, operating_system, portable_mtime, sha256,
                symlinks, tars)

A rule that assembles data into a tarball which can be use as in layers attr in container_image rule.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
build_layer	-	Label	optional	//container:build_tar
compression	-	String	optional	"gzip"
compression_options	-	List of strings	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	"/"
empty_dirs	-	List of strings	optional	[]
empty_files	-	List of strings	optional	[]
enable_mtime_preservation	-	Boolean	optional	False
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	{}
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
mode	Set the mode of files added by the `files` attribute.	String	optional	"0o555"
mtime	-	Integer	optional	-1
operating_system	-	String	optional	"linux"
portable_mtime	-	Boolean	optional	False
sha256	-	Label	optional	//container/go/cmd/sha256:sha256
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	[]

container_load

container_load(name, file, repo_mapping)

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.

ATTRIBUTES

Name	Description	Type	Mandatory
name	A unique name for this repository.	Name	required
file	A label targeting a single file which is a compressed or uncompressed tar, as obtained through `docker save IMAGE`.	Label	required
repo_mapping	A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>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`).	Dictionary: String -> String	required

container_pull

container_pull(name, architecture, cpu_variant, cred_helpers, digest, docker_client_config,
               import_tags, os, os_features, os_version, platform_features, puller_darwin,
               puller_linux_amd64, puller_linux_arm64, puller_linux_s390x, registry, repo_mapping,
               repository, tag, timeout)

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 for all container_pull targets.

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)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
architecture	Which CPU architecture to pull if this image refers to a multi-platform manifest list, default 'amd64'.	String	optional	"amd64"
cpu_variant	Which CPU variant to pull if this image refers to a multi-platform manifest list.	String	optional	""
cred_helpers	Labels to a list of credential helper binaries that are configured in `docker_client_config`. More about credential helpers: https://docs.docker.com/engine/reference/commandline/login/#credential-helpers	List of labels	optional	[]
digest	The digest of the image to pull.	String	optional	""
docker_client_config	Specifies a Bazel label of the config.json file. 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`.	Label	optional	None
import_tags	Tags to be propagated to generated rules.	List of strings	optional	[]
os	Which os to pull if this image refers to a multi-platform manifest list.	String	optional	"linux"
os_features	Specifies os features when pulling a multi-platform manifest list.	List of strings	optional	[]
os_version	Which os version to pull if this image refers to a multi-platform manifest list.	String	optional	""
platform_features	Specifies platform features when pulling a multi-platform manifest list.	List of strings	optional	[]
puller_darwin	Exposed to provide a way to test other pullers on macOS	Label	optional	@go_puller_darwin//file:downloaded
puller_linux_amd64	Exposed to provide a way to test other pullers on Linux	Label	optional	@go_puller_linux_amd64//file:downloaded
puller_linux_arm64	Exposed to provide a way to test other pullers on Linux	Label	optional	@go_puller_linux_arm64//file:downloaded
puller_linux_s390x	Exposed to provide a way to test other pullers on Linux	Label	optional	@go_puller_linux_s390x//file:downloaded
registry	The registry from which we are pulling.	String	required
repo_mapping	A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>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`).	Dictionary: String -> String	required
repository	The name of the image.	String	required
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.	String	optional	"latest"
timeout	Timeout in seconds to fetch the image from the registry. This attribute will be overridden by the PULLER_TIMEOUT environment variable, if it is set.	Integer	optional	0

container_push

container_push(name, extension, extract_config, format, image, incremental_load_template,
               insecure_repository, registry, repository, repository_file, skip_unchanged_digest,
               stamp, tag, tag_file, tag_tpl, windows_paths)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
extension	The file extension for the push script.	String	optional	""
extract_config	-	Label	optional	//container/go/cmd/extract_config:extract_config
format	The form to push: Docker or OCI, default to 'Docker'.	String	required
image	The label of the image to push.	Label	required
incremental_load_template	-	Label	optional	//container:incremental_load_template
insecure_repository	Whether the repository is insecure or not (http vs https)	Boolean	optional	False
registry	The registry to which we are pushing.	String	required
repository	The name of the image.	String	required
repository_file	The label of the file with repository value. Overrides 'repository'.	Label	optional	None
skip_unchanged_digest	Check if the container registry already contain the image's digest. If yes, skip the push for that image. Default to False. Note that there is no transactional guarantee between checking for digest existence and pushing the digest. This means that you should try to avoid running the same container_push targets in parallel.	Boolean	optional	False
stamp	Whether to encode build information into the output. Possible values: - `@io_bazel_rules_docker//stamp:always`: Always stamp the build information into the output, even in [--nostamp][stamp] builds. This setting should be avoided, since it potentially causes cache misses remote caching for any downstream actions that depend on it. - `@io_bazel_rules_docker//stamp:never`: Always replace build information by constant values. This gives good build result caching. - `@io_bazel_rules_docker//stamp:use_stamp_flag`: Embedding of build information is controlled by the [--[no]stamp][stamp] flag. Stamped binaries are not rebuilt unless their dependencies change. [stamp]: https://docs.bazel.build/versions/main/user-manual.html#flag--stamp	Label	optional	@io_bazel_rules_docker//stamp:use_stamp_flag
tag	The tag of the image.	String	optional	"latest"
tag_file	The label of the file with tag value. Overrides 'tag'.	Label	optional	None
tag_tpl	The script template to use.	Label	required
windows_paths	-	Boolean	required

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, user, null_cmd,
                     null_entrypoint, tag_name, labels, label_files, label_file_strings)

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,
    cfg = _container.image.cfg,
)

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`
user	str, overrides ctx.attr.user	`None`
null_cmd	bool, overrides ctx.attr.null_cmd	`None`
null_entrypoint	bool, overrides ctx.attr.null_entrypoint	`None`
tag_name	str, overrides ctx.attr.tag_name	`None`
labels	str Dict, overrides ctx.attr.labels	`None`
label_files	File list, overrides ctx.attr.label_files	`None`
label_file_strings	str list, overrides ctx.attr.label_file_strings	`None`