1 -
# Bazel rules for fetching Debian packages
1 +
# `rules_distroless`
2 2 3 -
This ruleset designed to replace commands such as `apt-get install`, `passwd`, `groupadd`, `useradd`, `update-ca-certificates`.
3 +
Bazel helper rules to aid with some of the steps needed to create a Linux /
4 +
Debian installation. These rules are designed to replace commands such as
5 +
`apt-get install`, `passwd`, `groupadd`, `useradd`, `update-ca-certificates`.
6 + 7 +
> [!CAUTION]
8 +
> `rules_distroless` is currently in beta and does not yet offer a stable
9 +
> Public API. However, many users are already successfully using it in
10 +
> production environments. Check [Adopters](#adopters) to see who's already
11 +
> using it.
4 12 5 -
> [!NOTE]
6 -
> rules_distroless is an beta software and doesn't have a stable Public API yet, however many are already using it in production.
7 -
>
8 -
> See [Adopters](#adopters) section to see who's already using it.
9 13 10 14
# Usage
11 15 12 -
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>.
16 +
## Bzlmod (Bazel 6+)
17 + 18 +
> [!NOTE]
19 +
> If you are using Bazel 6 you need to enable Bzlmod by adding `common
20 +
> --enable_bzlmod` to `.bazelrc`
21 +
> If you are using Bazel 7+ [it's enabled by default].
22 + 23 +
Add the following to your `MODULE.bazel` file:
24 + 25 +
```starlark
26 +
bazel_dep(name = "rules_distroless", version = "0.3.9")
27 +
```
28 + 29 +
You can find the latest release version in the [Bazel Central Registry].
30 + 31 +
If you want to use a specific commit (e.g. there are commits in `main` that are
32 +
still not part of a release) you can use one of the few mechanisms that Bazel
33 +
provides to override repos.
34 + 35 +
You can use [`git_override`], [`archive_override`], etc (or
36 +
[`local_path_override`] if you want to test a local patch):
37 +
```starlark
38 +
bazel_dep(name = "rules_distroless", version = "0.3.9")
39 + 40 +
git_override(
41 +
module_name = "rules_distroless",
42 +
remote = "https://github.com/GoogleContainerTools/rules_distroless.git",
43 +
commit = "6ccc0307f618e67a9252bc6ce2112313c2c42b7f",
44 +
)
45 +
```
46 + 47 +
## `WORKSPACE` (legacy)
48 + 49 +
> [!WARNING]
50 +
> Bzlmod is replacing the legacy `WORKSPACE` system. The `WORKSPACE` file will
51 +
> be disabled by default in Bazel 8 (late 2024) and will be completely removed
52 +
> in Bazel 9 (late 2025). Please migrate to Bzlmod following the steps in the
53 +
> [Bzlmod migration guide].
54 + 55 +
Add the following to your `WORKSPACE` file:
56 + 57 +
```starlark
58 +
REPO = "https://github.com/GoogleContainerTools/rules_distroless"
59 + 60 +
VERSION = "0.3.8"
61 +
SHA256 = "6d1d739617e48fc3579781e694d3fabb08fc6c9300510982c01882732c775b8e"
62 +
URL = "{repo}/releases/download/v{v}/rules_distroless-v{v}.tar.gz".format(repo=REPO, v=VERSION)
63 + 64 +
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
65 +
http_archive(
66 +
name = "rules_distroless",
67 +
sha256 = SHA256,
68 +
strip_prefix = "rules_distroless-{}".format(VERSION),
69 +
url = URL,
70 +
)
71 +
```
72 + 73 +
You can find the latest release in the [`rules_distroless` Github releases
74 +
page].
75 + 76 +
If you want to use a specific commit (e.g. there are commits in `main` that are
77 +
still not part of a release) you can change the Github URL pointing it to a
78 +
Github archive, as follows:
79 + 80 +
```starlark
81 +
REPO = "https://github.com/GoogleContainerTools/rules_distroless"
82 + 83 +
COMMIT = "6ccc0307f618e67a9252bc6ce2112313c2c42b7f"
84 +
SHA256 = ""
85 +
URL = "{}/archive/{}.tar.gz".format(REPO, COMMIT)
86 + 87 +
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
88 +
http_archive(
89 +
name = "rules_distroless",
90 +
sha256 = SHA256,
91 +
strip_prefix = "rules_distroless-{}".format(COMMIT),
92 +
url = URL,
93 +
)
94 +
```
95 + 96 +
Note that the `SHA256` is initially empty. This is the easiest way to get the
97 +
correct value because Bazel will print a warning message with the hash so you
98 +
can use it to get rid of the warning.
99 + 100 +
> [!CAUTION]
101 +
> GitHub source archives don't have a strong guarantee on the sha256 stability.
102 +
> Check Github's [Update on the future stability of source code archives and
103 +
> hashes] for more information.
104 + 105 + 106 +
# Examples
107 + 108 +
The [examples](/examples) demonstrate how to accomplish typical tasks such as
109 +
**create a new user group** or **create a new home directory**:
13 110 14 111
- [groupadd](/examples/group)
15 112
- [passwd](/examples/passwd)
16 113
- [useradd --home](/examples/home)
17 114
- [update-ca-certificates](/examples/cacerts)
18 115
- [keytool](/examples/java_keystore)
19 -
- [apt-get install](/examples/debian_snapshot) <i>from Debian repositories.</i>
20 -
- [apt-get install](/examples/ubuntu_snapshot) <i>from Ubuntu repositories.</i>
116 +
- [apt-get install](/examples/debian_snapshot) from Debian repositories.
117 +
- [apt-get install](/examples/ubuntu_snapshot) from Ubuntu repositories.
21 118 22 -
We also we have distroless-specific rules that could be useful
119 +
We also have `distroless`-specific rules that could be useful:
23 120 24 -
- [flatten](/examples/flatten): <i>flatten multiple `tar` archives.</i>
25 -
- [os_release](/examples/os_release): <i>create a `/etc/os-release` file</i>
26 -
- [locale](/examples/locale): <i>strip `/usr/lib/locale` to be smaller.</i>
27 -
- [dpkg_statusd](/examples/statusd): <i>creates a package database at /var/lib/dpkg/status.d for scanners to discover installed packages.</i>
121 +
- [flatten](/examples/flatten): flatten multiple `tar` archives.
122 +
- [os_release](/examples/os_release): create an `/etc/os-release` file.
123 +
- [locale](/examples/locale): strip `/usr/lib/locale` to be smaller.
124 +
- [dpkg_statusd](/examples/statusd): creates a `/var/lib/dpkg/status.d`
125 +
package database for scanners to discover installed packages.
28 126 29 127 30 128
# Public API Docs
31 129 32 -
- [apt](/docs/apt.md) Repository rule for fetching/installing Debian/Ubuntu packages.
33 -
- [linux](/docs/rules.md) Various rules for creating Linux specific files.
130 +
To read more specific documentation for each of the rules in the repo please
131 +
check the following docs:
34 132 133 +
- [apt](/docs/apt.md): repository rule for installing Debian/Ubuntu packages.
134 +
- [apt macro](/docs/apt_macro.md): legacy macro for installing Debian/Ubuntu
135 +
packages.
136 +
- [rules](/docs/rules.md): various helper rules to aid with creating a Linux /
137 +
Debian installation from scratch.
35 138 36 -
## Installation
37 - 38 -
See the install instructions on the release notes: <https://github.com/GoogleContainerTools/rules_distroless/releases>
39 - 40 -
To use a commit rather than a release, you can point at any SHA of the repo.
41 - 42 -
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:
43 - 44 -
1. Replace `url = "https://github.com/GoogleContainerTools/rules_distroless/releases/download/v0.1.0/rules_distroless-v0.1.0.tar.gz"`
45 -
with a GitHub-provided source archive like `url = "https://github.com/GoogleContainerTools/rules_distroless/archive/abc123.tar.gz"`
46 -
1. Replace `strip_prefix = "rules_distroless-0.1.0"` with `strip_prefix = "rules_distroless-abc123"`
47 -
1. Update the `sha256`. The easiest way to do this is to comment out the line, then Bazel will
48 -
print a message with the correct value.
49 - 50 -
> Note that GitHub source archives don't have a strong guarantee on the sha256 stability, see
51 -
> <https://github.blog/2023-02-21-update-on-the-future-stability-of-source-code-archives-and-hashes>
52 139 53 140
# Contributing
141 +
This ruleset is primarily funded to support [Google's `distroless` container
142 +
images]. We may not work on feature requests that do not support this mission.
54 143 55 -
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).
56 - 57 -
# Adopters
144 +
We will however accept fully tested contributions via pull requests if they
145 +
align with the project goals (e.g. add support for a different compression
146 +
format) and may reject requests that do not (e.g. supporting other packaging
147 +
formats other than `.deb`).
58 148 59 -
- distroless: https://github.com/GoogleContainerTools/distroless
60 -
- Arize AI: https://www.arize.com
61 149 62 -
> An adopter? Add your company here by sending us a Pull Request.
150 +
# Adopters
151 +
- [Google's `distroless` container images]
152 +
- [Arize AI](https://www.arize.com)
153 + 154 +
> [!TIP]
155 +
> Are you using `rules_distroless`? Please send us a Pull Request to add your
156 +
> project or company name here!
157 + 158 + 159 +
[it's enabled by default]: https://blog.bazel.build/2023/12/11/bazel-7-release.html#bzlmod
160 +
[Bazel Central Registry]: https://registry.bazel.build/modules/rules_distroless
161 +
[`git_override`]: https://bazel.build/versions/6.0.0/rules/lib/globals#git_override
162 +
[`archive_override`]: https://bazel.build/versions/6.0.0/rules/lib/globals#archive_override
163 +
[`local_path_override`]: https://bazel.build/versions/6.0.0/rules/lib/globals#local_path_override
164 +
[Bzlmod migration guide]: https://bazel.build/external/migration
165 +
[`rules_distroless` Github releases page]: https://github.com/GoogleContainerTools/rules_distroless/releases
166 +
[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
167 +
[Google's `distroless` container images]: https://github.com/GoogleContainerTools/distroless
168 +
[Arize AI]: https://www.arize.com
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4