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 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 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.

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

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