From 42571bd1fbb716b3ac51fff257ee4771ae312469 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Wed, 10 Apr 2024 09:47:24 -0400 Subject: [PATCH] docs: Add a new bootc-runtime.md Let's clarify this more; it's touched on in the main docs but worth elaborating on. Signed-off-by: Colin Walters --- docs/src/SUMMARY.md | 1 + docs/src/building/bootc-runtime.md | 47 ++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 docs/src/building/bootc-runtime.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index fb1f6229..8361818d 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -9,6 +9,7 @@ # Building images - [Building images](building/guidance.md) +- [Container runtime vs bootc runtime](building/bootc-runtime.md) - [Users, groups, SSH keys](building/users-and-groups.md) - [Secrets](building/secrets.md) - [Management Services](building/management-services.md) diff --git a/docs/src/building/bootc-runtime.md b/docs/src/building/bootc-runtime.md new file mode 100644 index 00000000..f2c85ce2 --- /dev/null +++ b/docs/src/building/bootc-runtime.md @@ -0,0 +1,47 @@ + +# Container runtime vs "bootc runtime" + +Fundamentally, `bootc` reuses the [OCI image format](https://github.com/opencontainers/image-spec) +as a way to transport serialized filesystem trees with included metadata such as a `version` +label, etc. + +However, `bootc` generally ignores the [Container configuration](https://github.com/opencontainers/image-spec/blob/main/config.md) +section at runtime today. + +Container runtimes like `podman` and `docker` of course *will* interpret this metadata +when running a bootc container image as a container. + +## Labels + +A key aspect of OCI is the ability to use standardized (or semi-standardized) +labels. The are stored and rendered by `bootc`; especially the +`org.opencontainers.image.version` label. + +## Example ignored runtime metadata, and recommendations + +### `ENTRYPOINT` and `CMD` (OCI: `Entrypoint`/`Cmd`) + +Ignored by bootc. + +It's recommended for bootc containers to set `CMD /sbin/init`; but this is not required. + +The booted host system will launch from the bootloader, to the kernel+initramfs and +real root however it is "physically" configured inside the image. Typically +today this is using [systemd](https://systemd.io/) in both the initramfs +and at runtime; but this is up to how you build the image. + +### `ENV` (OCI: `Env`) + +Ignored by bootc; to configure the global system environment you can +change the systemd configuration. (Though this is generally not a good idea; +instead it's usually better to change the environment of individual services) + +### `EXPOSE` (OCI: `exposedPorts`) + +Ignored by bootc; it is agnostic to how the system firewall and network +function at runtime. + +### `USER` (OCI: `User`) + +Ignored by bootc; typically you should configure individual services inside +the bootc container to run as unprivileged users instead. \ No newline at end of file