Skip to content

Latest commit

 

History

History
525 lines (392 loc) · 45.6 KB

container.md

File metadata and controls

525 lines (392 loc) · 45.6 KB

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 Default
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_push_index

 container_push_index(name, extension, extract_config, format, images, incremental_load_template,
                      registry, repository, repository_file, skip_unchanged_digest, stamp, tag,
                      tag_file, tag_tpl, windows_paths)
 

Push a docker image for multiple platforms.

This rule will push all given image manifests, and then the manifest list, aka the fat manifest, with the definition of all image platforms.

An image platform must follow the format: [<os>/][<arch>][/<variant>].

Example of the images attribute value:

{
    ":my_image_amd64": "linux/amd64",
    ":my_image_arm64": "linux/arm64/v8",
    ":my_image_ppc64le": "linux/ppc64le",
}
  • if <os> is missing, linux will be used.
  • if <arch> is missing, amd64 will be used.
  • <os> and <arch> are mandatories to define the <variant>.

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
images The list of all images to push.

The value of each entries is the platform of the container image.
Dictionary: Label -> String required
incremental_load_template - Label optional //container:incremental_load_template
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)

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