Home

Awesome

Bazel rules for OCI container images

Bazel rules based on the Open Containers Initiative: https://opencontainers.org/

Please let us know about your success stories on our adoption discussion! https://github.com/bazel-contrib/rules_oci/discussions/299

Need help? This ruleset has support provided by Aspect Build.

Comparison with rules_docker

This ruleset is not intended as a complete replacement for rules_docker! Many use cases can be accomodated, and we know that many users have completely replaced rules*docker. You can find a migration guide at https://docs.aspect.build/guides/rules_oci_migration. However, some other use cases such as container_run_and*\* rules have no equivalent.

rules_docker was largely unmaintained for 18 months, and as of October 2023 it has been archived. See https://github.com/bazelbuild/rules_docker/discussions/2038. You might still decide to use rules_docker, and perhaps even sign up as a maintainer so that it may be un-archived.

We started from first principles and avoided some pitfalls we learned from rules_docker:

Installation

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 archive_override or git_override. For WORKSPACE, you modify the http_archive call; for example to use commit abc123 with a WORKSPACE file:

  1. 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 like url = "https://github.com/bazel-contrib/rules_oci/archive/abc123.tar.gz"
  2. Replace strip_prefix = "rules_oci-0.1.0" with strip_prefix = "rules_oci-abc123"
  3. 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

Usage

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

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

Construct image layers

Pull and Push

Testing

Signing

[!WARNING]
Signing images is a developer preview, not part of public API yet.

3rd Party Extensions/Tools