Container interface: document exposing the host's os-release

bluca · bluca · commit 34e0d56ce23f · 2020-06-23T12:57:05.000+01:00
In order to allow applications to detect the host OS version or other
metadata, ask container managers to expose the os-release files as
read-only bind mounts.
For systemd-nspawn, we will also expose ID, BUILD_ID, VERSION_ID and
VARIANT_ID as lowercase environment variables prefixed by the
container_host_ string.
diff --git a/docs/CONTAINER_INTERFACE.md b/docs/CONTAINER_INTERFACE.md
@@ -121,6 +121,16 @@ manager, please consider supporting the following interfaces.
    `container_ttys=pts/7 pts/8 pts/14` it will spawn three additional login
    gettys on ptys 7, 8, and 14.
 
+4. To allow applications to detect the OS version and other metadata of the host
+   running the container manager, if this is considered desirable, please parse
+   the host's `/etc/os-release` and set a `$container_host_<key>=<VALUE>`
+   environment variable for the ID fields described by the [os-release
+   interface](https://www.freedesktop.org/software/systemd/man/os-release.html), eg:
+   `$container_host_id=debian`
+   `$container_host_build_id=2020-06-15`
+   `$container_host_variant_id=server`
+   `$container_host_version_id=10`
+
 ## Advanced Integration
 
 1. Consider syncing `/etc/localtime` from the host file system into the
diff --git a/man/os-release.xml b/man/os-release.xml
@@ -339,6 +339,13 @@
     name in order to avoid name clashes. Applications
     reading this file must ignore unknown fields. Example:
     <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para>
+
+    <para>Container and sandbox runtime managers may make the host's
+    identification data available to applications by providing the host's
+    <filename>/etc/os-release</filename> and
+    <filename>/usr/lib/os-release</filename> as respectively
+    <filename>/run/host/etc/os-release</filename> and
+    <filename>/run/host/usr/lib/os-release</filename>.</para>
   </refsect1>
 
   <refsect1>
