Bazel rules for OCI container images

Very simple Bazel rules based on the Open Containers Initiative specification:

Status: Unfunded, stable in maintenance mode.

Design Principles

• Keep a tight complexity budget for the project so we are able to commit to effective maintenance without any dedicated funding.

- Use only off-the-shelf, pre-built layer and container manipulation tools. - Use DefaultInfo to hand information between rules, meaning that files and directories are inputs/outputs for each action.

• Stay true to the specification, and only the specification.

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

Comparison with rules_img

As described above, rules_oci is built for maintainability on top of standard container tools. This means it doesn't attempt to make all the optimizations that are possible with rules_img.

For use with remote cache and remote execution, the use of files and directories as action input/output means that lots of bytes are sent over the network. For these cases, we recommend trying rules_img. See https://github.com/bazel-contrib/rulesimg/blob/main/docs/migration-from-rulesoci.md to migrate from rulesoci to rulesimg.

Comparison with rules_docker

This ruleset is not intended as a complete replacement for [rules_docker]. Most use cases can be accomodated, and we know many users who have completely replaced rules_docker. However, some other use cases such as containerrunand\ rules have no equivalent. You might still decide to use rules_docker, and perhaps even volunteer to help maintain it.

You can find a migration guide at ocimigration>.

[rulesdocker]: https://github.com/bazelbuild/rulesdocker

Installation

See the install instructions on the release notes:

To use a commit rather than a release, you can point at any SHA of the repo.

With bzlmod, you can use archiveoverride or gitoverride. For WORKSPACE, you modify the http_archive call; for example to use commit abc123 with a WORKSPACE file:

• Replace url = "https://github.com/bazel-contrib/rulesoci/releases/download/v0.1.0/rulesoci-v0.1.0.tar.gz"

with a GitHub-provided source archive like url = "https://github.com/bazel-contrib/rules_oci/archive/abc123.tar.gz"

• Replace stripprefix = "rulesoci-0.1.0" with stripprefix = "rulesoci-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

Usage

rules_oci does not contain language-specific rules, but we do have limited documentation on how to accomplish typical tasks.

• C/C++
• Go
• Java
• JavaScript
• Python
• Rust
• Scala
• WASM (see https://docs.docker.com/desktop/wasm/)
• Static Content (such as a html/javascript frontend)

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

Public API Docs

Install system packages

• Alpine: we recommend apko> to install apk packages.
• Debian: we recommend distroless> to install deb packages.
• 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.
• ociimage_index Build a multi-architecture OCI compatible container image.
• ociload Loads an ociimage into a container daemon. Can optionally produce a loadable tarball.

Pull and Push

• oci_pull Pull image layers using Bazel's downloader. Falls back to using curl in some cases.
• ocipush Push an ociimage or ociimageindex to a remote registry.

Testing

• We recommend containerstructure_test to run tests

Signing

[!WARNING]

Signing images is a developer preview, not part of public API yet.

• cosignsign: Sign an ociimage using cosign binary at a remote registry.
• cosignattest Add an attachment to an ociimage at a remote registry using cosign.

3rd Party Extensions/Tools

• ociupdate: CLI and basic module extension to help with automating updates to image digests for ECR-based images with immutable tags.
• rules_buildx: Build container images from Dockerfiles using Docker Buildx.