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