This is a "barebones" alternative to rules_docker.
We start from first principles and avoided some pitfalls we learned in maintaining that repo:
- Use a toolchain consisting of off-the-shelf, pre-built layer and container manipulation tools.
- Don't write language-specific rules, as we cannot be experts on all languages, nor can users deal with the versioning issues that come with dependencies we would be forced to take on the rules for those languages.
- Don't be docker-specific, now that it has a commercial license and other container runtimes exist (podman for example).
- Use our toolchain hermetically: don't assume there is a docker pre-installed on the machine.
- Keep a tight complexity budget for the project so we are able to commit to effective maintenance.
Need help? This ruleset has support provided by https://aspect.dev.
- Bazel >= 6.2.0 with
--enable_bzlmod
: start from https://registry.bazel.build/modules/rules_oci - Others: Copy the WORKSPACE snippet into your
WORKSPACE
file from a release: https://github.com/bazel-contrib/rules_oci/releases
To use a commit rather than a release, you can point at any SHA of the repo.
For example to use commit abc123
:
- Replace
url = "https://github.com/bazel-contrib/rules_oci/releases/download/v0.1.0/rules_oci-v0.1.0.tar.gz"
with a GitHub-provided source archive likeurl = "https://github.com/bazel-contrib/rules_oci/archive/abc123.tar.gz"
- Replace
strip_prefix = "rules_oci-0.1.0"
withstrip_prefix = "rules_oci-abc123"
- Update the
sha256
. The easiest way to do this is to comment out the line, then Bazel will print a message with the correct value.
Note that GitHub source archives don't have a strong guarantee on the sha256 stability, see https://github.blog/2023-02-21-update-on-the-future-stability-of-source-code-archives-and-hashes
rules_oci does not contain language-specific rules, but we do have limited documentation on how to accomplish typical tasks, and how to migrate from the language-specific rules in rules_docker.
Your language not listed above? Please contribute engineering resources or financially through our Sponsor link!
There are some generic examples of usage in the examples folder.
Note that these examples rely on the setup code in the /WORKSPACE
file in the root of this repo.
rules_oci supports two different registry implementation for the temporary storage within actions spawned by bazel.
- By default we recommend using
zot
as it stores blobs on disk, however it doesn't supportDocker
-format images. crane
is memory hungry as it stores blobs in memory, leading to high memory usage. However it supports bothOCI
andDocker
formats which is quite useful for usingDocker
images pulled from the registries such as DockerHub.
- oci_image Build an OCI compatible container image.
- oci_image_index Build a multi-architecture OCI compatible container image.
- oci_tarball Creates tarball from
oci_image
that can be loaded by runtimes.
- oci_pull Pulls image layers using Bazel's downloader.
- oci_push Push an oci_image or oci_image_index to a remote registry.
- We recommend container_structure_test to run tests against an
oci_image
oroci_tarball
target.