Bazel rules for OCI containers
A lot of companies have already done a successful migration from
rules_docker. Please let us know about yours on our adoption discussion!
Need help? This ruleset has support provided by https://aspect.dev.
We started 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.
See the install instructions on the release notes: 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.
With bzlmod, you can use
WORKSPACE, you modify the
http_archive call; for example to use commit
abc123 with a
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 like
url = "https://github.com/bazel-contrib/rules_oci/archive/abc123.tar.gz"
strip_prefix = "rules_oci-0.1.0"with
strip_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.
- WASM (see https://docs.docker.com/desktop/wasm/)
[!NOTE] 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.
Choosing between zot or crane as the local registry
rules_oci supports two different registry implementation for the temporary storage within actions spawned by bazel.
- By default we recommend using
zotas it stores blobs on disk, however it doesn't support
craneis a better alternative as it supports both
Dockerformats which is required to make images with
Dockermedia types work. However, it might not support everything that zot does.
Public API Docs
Build Base images
- Alpine: we recommend https://github.com/chainguard-dev/rules_apko to install apk packages using Chainguard's apko.
- Debian: The
.debfiles, which are already archives that may be used directly as image layers. See
/examples/debin this repository. This solution is incomplete since
aptdoes some other tasks which you may need. See https://github.com/bazel-contrib/rules_oci/issues/375 for details.
- RHEL/CentOS/Amazon Linux: we don't have any support for this yet. Please consider donating to the project!
Construct image layers
- 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_imagethat can be loaded by runtimes.
Pull and Push
- oci_pull Pull image layers using Bazel's downloader. Falls back to using
curlin some cases.
- oci_push Push an
oci_image_indexto a remote registry.
- We recommend container_structure_test to run tests against an
driver="docker") or an
Signing images is a developer preview, not part of public API yet.