From 7a0acbe9b7dee306c038de66861b31bf851a9164 Mon Sep 17 00:00:00 2001 From: Nick Zavaritsky <mejedi@gmail.com> Date: Wed, 23 Oct 2024 19:53:13 +0000 Subject: [PATCH] Document linux_capabilities in builds section --- docs/advanced/linux-capabilities.md | 78 +++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 79 insertions(+) create mode 100644 docs/advanced/linux-capabilities.md diff --git a/docs/advanced/linux-capabilities.md b/docs/advanced/linux-capabilities.md new file mode 100644 index 0000000000..80b70bc131 --- /dev/null +++ b/docs/advanced/linux-capabilities.md @@ -0,0 +1,78 @@ +# Linux Capabilities + +In Linux, capabilities are a way to selectively grant privileges to a running process. + +Docker provides `--cap-add` and `--cap-drop` +[run options](https://docs.docker.com/engine/containers/run/#runtime-privilege-and-linux-capabilities) +to tweak container capabilities, e.g: + +``` +docker run --cap-add bpf hello-world +``` + +If container runs as a non-root user, +capabilities are narrowed by intersecting with *file* capabilities of the +application binary. When building images with a Dockerfile, one +typically uses `setcap` tool to modify file capabilities, e.g: +`setcap FILE bpf=ep`. + +To set file capabilities with `ko`, specify `linux_capabilities` +in builds configuration section in your `.ko.yaml`. Use `setcap` syntax: + +```yaml +builds: +- id: caps + linux_capabilities: bpf=ep +``` +## Alternative spelling + +```yaml +builds: +- id: caps + linux_capabilities: + - cap1 + - cap2 + - cap3 +``` + +A list of capability names is equivalent to `cap1,cap2,cap3=p`. + +## Improving UX in capability-reliant apps + +A capability can be *permitted* (`=p`), or both *permitted* and *effective* (`=ep`). +Effective capabilities are used for permission checks. +A program can promote permitted capability to effective when needed. + +```yaml +builds: +- id: caps + linux_capabilities: bpf,perfmon,net_admin=ep +``` + +Initially, `=ep` might look like a good idea. +There's no need to explicitly promote *permitted* capabilities. +Application takes advantage of *effective* capabilities right away. + +There is a catch though. + +``` +$ docker run --cap-add bpf ko.local/caps.test-4b8f7bca75c467b3d2803e1c087a3287 +exec /ko-app/caps.test: operation not permitted +``` + +When run options request fewer capabilities than specified in file capabilities, +container fails to start. It is hard to tell what went wrong since +`operation not permitted` is a generic error. (Docker is unlikely to improve diagnostics +for this failure case since the check is implemented in Linux kernel.) + + +We suggest to use `=p` instead. This option puts application in charge of verifying and +promoting permitted capabilities to effective. It can produce much better diagnostics: + +``` +$ docker run --cap-add bpf ko.local/caps.test-4b8f7bca75c467b3d2803e1c087a3287 +current capabilities: cap_bpf=p +activating capabilities: cap_net_admin,cap_perfmon,cap_bpf=ep: operation not permitted +``` + +[Sample code](https://go.dev/play/p/uPMzyotkNHg). diff --git a/mkdocs.yml b/mkdocs.yml index 4bfb8b6dd1..0efcc3fff6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,6 +51,7 @@ nav: - advanced/faq.md - advanced/terraform.md - advanced/lambda.md + - advanced/linux-capabilities.md - CLI Reference: - 'ko': reference/ko.md - 'ko apply': reference/ko_apply.md