-
Notifications
You must be signed in to change notification settings - Fork 39
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* chore: ignore MODULE.bazel.lock 27242f4 pushed lock version to `12` (my guess is Bazel 8?) plus other changes that e.g. don't match running with `.bazelversion`'s `7.3.1`. Regardless, the `MODULE.bazel.lock` file is still not stable and e.g. just running it in another operating system causes things to change... so let's just ignore it like I did for the `e2e` tests in 70c14c0 * docs: README.md Revamp README adding an improved version of the Bzlmod and `WORKSPACE` snippets that are available in the release page. IMHO the release page should now remove those snippets and point to the README. * docs: revamp apt.macro doc and create apt/extensions doc Split the Bzlmod / `WORKSPACE` docs from `apt.install` macro and remove a bunch of old references. Also mark it all as legacy since the present and future is all Bzlmod. Create apt/extensions docs. Add a whole common section to both docs with (hopefully :) easy-to-follow documentation inspired by my answer to a Slack question (https://bazelbuild.slack.com/archives/CA3NW13MH/p1729804678924819).
- Loading branch information
Showing
9 changed files
with
543 additions
and
146 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,62 +1,168 @@ | ||
| # Bazel rules for fetching Debian packages | ||
| # `rules_distroless` | ||
|
|
||
| This ruleset designed to replace commands such as `apt-get install`, `passwd`, `groupadd`, `useradd`, `update-ca-certificates`. | ||
| Bazel helper rules to aid with some of the steps needed to create a Linux / | ||
| Debian installation. These rules are designed to replace commands such as | ||
| `apt-get install`, `passwd`, `groupadd`, `useradd`, `update-ca-certificates`. | ||
|
|
||
| > [!CAUTION] | ||
| > `rules_distroless` is currently in beta and does not yet offer a stable | ||
| > Public API. However, many users are already successfully using it in | ||
| > production environments. Check [Adopters](#adopters) to see who's already | ||
| > using it. | ||
| > [!NOTE] | ||
| > rules_distroless is an beta software and doesn't have a stable Public API yet, however many are already using it in production. | ||
| > | ||
| > See [Adopters](#adopters) section to see who's already using it. | ||
|
|
||
| # Usage | ||
|
|
||
| Our [examples](/examples) demonstrate how to accomplish typical tasks such as <b>create a new user group</b> or <b>create a new home directory</b>. | ||
| ## Bzlmod (Bazel 6+) | ||
|
|
||
| > [!NOTE] | ||
| > If you are using Bazel 6 you need to enable Bzlmod by adding `common | ||
| > --enable_bzlmod` to `.bazelrc` | ||
| > If you are using Bazel 7+ [it's enabled by default]. | ||
| Add the following to your `MODULE.bazel` file: | ||
|
|
||
| ```starlark | ||
| bazel_dep(name = "rules_distroless", version = "0.3.9") | ||
| ``` | ||
|
|
||
| You can find the latest release version in the [Bazel Central Registry]. | ||
|
|
||
| If you want to use a specific commit (e.g. there are commits in `main` that are | ||
| still not part of a release) you can use one of the few mechanisms that Bazel | ||
| provides to override repos. | ||
|
|
||
| You can use [`git_override`], [`archive_override`], etc (or | ||
| [`local_path_override`] if you want to test a local patch): | ||
| ```starlark | ||
| bazel_dep(name = "rules_distroless", version = "0.3.9") | ||
|
|
||
| git_override( | ||
| module_name = "rules_distroless", | ||
| remote = "https://github.com/GoogleContainerTools/rules_distroless.git", | ||
| commit = "6ccc0307f618e67a9252bc6ce2112313c2c42b7f", | ||
| ) | ||
| ``` | ||
|
|
||
| ## `WORKSPACE` (legacy) | ||
|
|
||
| > [!WARNING] | ||
| > Bzlmod is replacing the legacy `WORKSPACE` system. The `WORKSPACE` file will | ||
| > be disabled by default in Bazel 8 (late 2024) and will be completely removed | ||
| > in Bazel 9 (late 2025). Please migrate to Bzlmod following the steps in the | ||
| > [Bzlmod migration guide]. | ||
| Add the following to your `WORKSPACE` file: | ||
|
|
||
| ```starlark | ||
| REPO = "https://github.com/GoogleContainerTools/rules_distroless" | ||
|
|
||
| VERSION = "0.3.8" | ||
| SHA256 = "6d1d739617e48fc3579781e694d3fabb08fc6c9300510982c01882732c775b8e" | ||
| URL = "{repo}/releases/download/v{v}/rules_distroless-v{v}.tar.gz".format(repo=REPO, v=VERSION) | ||
|
|
||
| load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") | ||
| http_archive( | ||
| name = "rules_distroless", | ||
| sha256 = SHA256, | ||
| strip_prefix = "rules_distroless-{}".format(VERSION), | ||
| url = URL, | ||
| ) | ||
| ``` | ||
|
|
||
| You can find the latest release in the [`rules_distroless` Github releases | ||
| page]. | ||
|
|
||
| If you want to use a specific commit (e.g. there are commits in `main` that are | ||
| still not part of a release) you can change the Github URL pointing it to a | ||
| Github archive, as follows: | ||
|
|
||
| ```starlark | ||
| REPO = "https://github.com/GoogleContainerTools/rules_distroless" | ||
|
|
||
| COMMIT = "6ccc0307f618e67a9252bc6ce2112313c2c42b7f" | ||
| SHA256 = "" | ||
| URL = "{}/archive/{}.tar.gz".format(REPO, COMMIT) | ||
|
|
||
| load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") | ||
| http_archive( | ||
| name = "rules_distroless", | ||
| sha256 = SHA256, | ||
| strip_prefix = "rules_distroless-{}".format(COMMIT), | ||
| url = URL, | ||
| ) | ||
| ``` | ||
|
|
||
| Note that the `SHA256` is initially empty. This is the easiest way to get the | ||
| correct value because Bazel will print a warning message with the hash so you | ||
| can use it to get rid of the warning. | ||
|
|
||
| > [!CAUTION] | ||
| > GitHub source archives don't have a strong guarantee on the sha256 stability. | ||
| > Check Github's [Update on the future stability of source code archives and | ||
| > hashes] for more information. | ||
|
|
||
| # Examples | ||
|
|
||
| The [examples](/examples) demonstrate how to accomplish typical tasks such as | ||
| **create a new user group** or **create a new home directory**: | ||
|
|
||
| - [groupadd](/examples/group) | ||
| - [passwd](/examples/passwd) | ||
| - [useradd --home](/examples/home) | ||
| - [update-ca-certificates](/examples/cacerts) | ||
| - [keytool](/examples/java_keystore) | ||
| - [apt-get install](/examples/debian_snapshot) <i>from Debian repositories.</i> | ||
| - [apt-get install](/examples/ubuntu_snapshot) <i>from Ubuntu repositories.</i> | ||
| - [apt-get install](/examples/debian_snapshot) from Debian repositories. | ||
| - [apt-get install](/examples/ubuntu_snapshot) from Ubuntu repositories. | ||
|
|
||
| We also we have distroless-specific rules that could be useful | ||
| We also have `distroless`-specific rules that could be useful: | ||
|
|
||
| - [flatten](/examples/flatten): <i>flatten multiple `tar` archives.</i> | ||
| - [os_release](/examples/os_release): <i>create a `/etc/os-release` file</i> | ||
| - [locale](/examples/locale): <i>strip `/usr/lib/locale` to be smaller.</i> | ||
| - [dpkg_statusd](/examples/statusd): <i>creates a package database at /var/lib/dpkg/status.d for scanners to discover installed packages.</i> | ||
| - [flatten](/examples/flatten): flatten multiple `tar` archives. | ||
| - [os_release](/examples/os_release): create an `/etc/os-release` file. | ||
| - [locale](/examples/locale): strip `/usr/lib/locale` to be smaller. | ||
| - [dpkg_statusd](/examples/statusd): creates a `/var/lib/dpkg/status.d` | ||
| package database for scanners to discover installed packages. | ||
|
|
||
|
|
||
| # Public API Docs | ||
|
|
||
| - [apt](/docs/apt.md) Repository rule for fetching/installing Debian/Ubuntu packages. | ||
| - [linux](/docs/rules.md) Various rules for creating Linux specific files. | ||
| To read more specific documentation for each of the rules in the repo please | ||
| check the following docs: | ||
|
|
||
| - [apt](/docs/apt.md): repository rule for installing Debian/Ubuntu packages. | ||
| - [apt macro](/docs/apt_macro.md): legacy macro for installing Debian/Ubuntu | ||
| packages. | ||
| - [rules](/docs/rules.md): various helper rules to aid with creating a Linux / | ||
| Debian installation from scratch. | ||
|
|
||
| ## Installation | ||
|
|
||
| See the install instructions on the release notes: <https://github.com/GoogleContainerTools/rules_distroless/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/GoogleContainerTools/rules_distroless/releases/download/v0.1.0/rules_distroless-v0.1.0.tar.gz"` | ||
| with a GitHub-provided source archive like `url = "https://github.com/GoogleContainerTools/rules_distroless/archive/abc123.tar.gz"` | ||
| 1. Replace `strip_prefix = "rules_distroless-0.1.0"` with `strip_prefix = "rules_distroless-abc123"` | ||
| 1. 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> | ||
|
|
||
| # Contributing | ||
| This ruleset is primarily funded to support [Google's `distroless` container | ||
| images]. We may not work on feature requests that do not support this mission. | ||
|
|
||
| This ruleset is primarily funded to support [distroless](github.com/GoogleContainerTools/distroless). We may not work on feature requests that do not support this mission. We will however accept fully tested contributions via pull requests if they align with the project goals (ex. a different compression format) and may reject requests that do not (ex. supporting a non `deb` based packaging format). | ||
|
|
||
| # Adopters | ||
| We will however accept fully tested contributions via pull requests if they | ||
| align with the project goals (e.g. add support for a different compression | ||
| format) and may reject requests that do not (e.g. supporting other packaging | ||
| formats other than `.deb`). | ||
|
|
||
| - distroless: https://github.com/GoogleContainerTools/distroless | ||
| - Arize AI: https://www.arize.com | ||
|
|
||
| > An adopter? Add your company here by sending us a Pull Request. | ||
| # Adopters | ||
| - [Google's `distroless` container images] | ||
| - [Arize AI](https://www.arize.com) | ||
|
|
||
| > [!TIP] | ||
| > Are you using `rules_distroless`? Please send us a Pull Request to add your | ||
| > project or company name here! | ||
|
|
||
| [it's enabled by default]: https://blog.bazel.build/2023/12/11/bazel-7-release.html#bzlmod | ||
| [Bazel Central Registry]: https://registry.bazel.build/modules/rules_distroless | ||
| [`git_override`]: https://bazel.build/versions/6.0.0/rules/lib/globals#git_override | ||
| [`archive_override`]: https://bazel.build/versions/6.0.0/rules/lib/globals#archive_override | ||
| [`local_path_override`]: https://bazel.build/versions/6.0.0/rules/lib/globals#local_path_override | ||
| [Bzlmod migration guide]: https://bazel.build/external/migration | ||
| [`rules_distroless` Github releases page]: https://github.com/GoogleContainerTools/rules_distroless/releases | ||
| [Update on the future stability of source code archives and hashes]: https://github.blog/2023-02-21-update-on-the-future-stability-of-source-code-archives-and-hashes | ||
| [Google's `distroless` container images]: https://github.com/GoogleContainerTools/distroless | ||
| [Arize AI]: https://www.arize.com |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.