docs: Describe `/boot/ostree`

People get confused by the sha256 here being different
from the ostree commit hash.

diff --git a/docs/atomic-upgrades.md b/docs/atomic-upgrades.md
index 27e02a7e6b005872c59869dad3e95735173ede8d..75d925e4af45f4c3a700e013d81fc3d52cc03753 100644 (file)
--- a/docs/atomic-upgrades.md
+++ b/docs/atomic-upgrades.md
@@ -142,3 +142,19 @@ so just like `/boot`, it has a version of `0` or `1` appended.
 Each bootloader entry has a special `ostree=` argument which refers to
 one of these symbolic links.  This is parsed at runtime in the
 initramfs.
+
+## The /boot/ostree directory
+
+There is also a `/boot/ostree` directory which is where ostree will
+install kernel data (including the initramfs).  In order to
+deduplicate across deployments, the kernel state is hashed (again
+with sha256), resulting in a directory like `/boot/ostree/<stateroot>-<checksum>`;
+this is what the bootloader entries will use.
+
+However, this is an implementation detail and may change in the
+future.  As a tool which wants to find kernel for a given root, instead look
+in `/usr/lib/modules/$kver`; this is how OSTree itself finds
+the kernel to "deploy" by copying it into `/boot`.
+
+Note that if `/boot` is on the same partition as `/`, then OSTree
+will just hardlink instead of copying.