JohnHammond
/
buildkit
mirror of https://github.com/JohnHammond/buildkit.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2455 from AkihiroSuda/doc-rootless-20211110 

update rootless docs
master
Tõnis Tiigi 2021-11-10 15:14:28 -08:00 committed by GitHub
parent a87b801ca0 57659ca24a
commit f421e24291
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 31 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/buildkitd.toml.md
View File

@ -1,4 +1,4 @@
# /etc/buildkit/buildkitd.toml
# buildkitd.toml
## NAME
@ -11,6 +11,9 @@ The TOML file used to configure the buildkitd daemon settings has a short
list of global settings followed by a series of sections for specific areas
of daemon configuration.
The file path is `/etc/buildkit/buildkitd.toml` for rootful mode,
`~/.config/buildkit/buildkitd.toml` for rootless mode.
## EXAMPLE
The following is a complete **buildkitd.toml** configuration example,

55
docs/rootless.md
View File

@ -5,40 +5,27 @@ Rootless mode allows running BuildKit daemon as a non-root user.
## Distribution-specific hint
Using Ubuntu kernel is recommended.
### Ubuntu
* No preparation is needed.
* `overlayfs` snapshotter is used by default ([Ubuntu-specific kernel patch](https://kernel.ubuntu.com/git/ubuntu/ubuntu-bionic.git/commit/fs/overlayfs?id=3b7da90f28fe1ed4b79ef2d994c81efbc58f1144)).
### Debian GNU/Linux
* Add `kernel.unprivileged_userns_clone=1` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p`
* `fuse-overlayfs` snapshotter is used by default.
* To use `overlayfs` snapshotter (recommended), run `sudo modprobe overlay permit_mounts_in_userns=1` ([Debian-specific kernel patch, introduced in Debian 10](https://salsa.debian.org/kernel-team/linux/blob/283390e7feb21b47779b48e0c8eb0cc409d2c815/debian/patches/debian/overlayfs-permit-mounts-in-userns.patch)). Put the configuration to `/etc/modprobe.d` for persistence.
### Arch Linux
* Add `kernel.unprivileged_userns_clone=1` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p`
* `fuse-overlayfs` snapshotter is used by default if running kernel >= 4.18.
Otherwise only `native` snapshotter can be used.
### Fedora
* If you don't have the latest `runc` (>= v1.0.0-rc91) installed and you have `crun` instead, you need to run `buildkitd` with `--oci-worker-binary=crun`.
* `fuse-overlayfs` snapshotter is used by default.
### RHEL/CentOS 8
* No preparation is needed.
* `fuse-overlayfs` snapshotter is used by default.
### Debian GNU/Linux 10
Add `kernel.unprivileged_userns_clone=1` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p`.
This step is not needed for Debian GNU/Linux 11 and later.
### RHEL/CentOS 7
* Add `user.max_user_namespaces=28633` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p`
* Old releases (<= 7.6) require [extra configuration steps](https://github.com/moby/moby/pull/40076).
* Only `native` snapshotter can be used.
Add `user.max_user_namespaces=28633` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p`.
This step is not needed for RHEL/CentOS 8 and later.
### Fedora, before kernel 5.13
You may have to disable SELinux, or run BuildKit with `--oci-worker-snapshotter=fuse-overlayfs`.
### Container-Optimized OS from Google
* :warning: Currently unsupported. See [#879](https://github.com/moby/buildkit/issues/879).
:warning: Currently unsupported. See [#879](https://github.com/moby/buildkit/issues/879).
## Known limitations
* `fuse-overlayfs` is used instead of `overlayfs` on most distros.
* Using the `overlayfs` snapshotter requires kernel >= 5.11 or Ubuntu kernel.
On kernel >= 4.18, the `fuse-overlayfs` snapshotter is used instead of `overlayfs`.
On kernel < 4.18, the `native` snapshotter is used.
* Network mode is always set to `network.host`.
* No support for `containerd` worker
* No support for `containerd` worker.
("worker" here is a BuildKit term, not a Kubernetes term. Running rootless BuildKit in containerd is fully supported.)
## Running BuildKit in Rootless mode
@ -58,12 +45,24 @@ $ rootlesskit --net=slirp4netns --copy-up=/etc --disable-host-loopback buildkitd
```
## Troubleshooting
If facing an error related to `fuse-overlayfs`, try running `buildkitd` with `--oci-worker-snapshotter=native`:
### Error related to `overlayfs`
Try running `buildkitd` with `--oci-worker-snapshotter=fuse-overlayfs`:
```console
$ rootlesskit buildkitd --oci-worker-snapshotter=fuse-overlayfs
```
### Error related to `fuse-overlayfs`
Try running `buildkitd` with `--oci-worker-snapshotter=native`:
```console
$ rootlesskit buildkitd --oci-worker-snapshotter=native
```
### Error related to `newuidmap` or `/etc/subuid`
See https://rootlesscontaine.rs/getting-started/common/subuid/
## Containerized deployment
### Kubernetes