Document sysext in elemental's context #270
Conversation
dharmit
force-pushed
the
sysext-elemental
branch
from
3cc05ad to
cef86f8
Compare
dharmit
force-pushed
the
sysext-elemental
branch
2 times, most recently
from
8c282b4 to
5d56c7b
Compare
dharmit
force-pushed
the
sysext-elemental
branch
from
5d56c7b to
8b42989
Compare
docs/systemd-system-extensions.md
Outdated
| like system extensions, Kubernetes definitions and firstboot configs to generate a ISO or RAW file which can be used | ||
| to boot a VM from. | ||
|
|
||
| `elemental3ctl` is a lower level tool that can do various things like installing an OS (packaged as OCI image) on |
There was a problem hiding this comment.
other than being lower level, it is the tool that is embedded on the installed system for operations on the node.
elemental3 is the tool that is used by the deployer (better role name to be found) on another system that might not actually be Elemental OS based.
There was a problem hiding this comment.
it is the tool that is embedded on the installed system for operations on the node.
Does that mean it can be used to upgrade (elemental3ctl upgrade) the OS from within its own shell environment?
Elemental OS
Is that the term we use for the immutable OS? Asking because I find it weird to write "immutable OS" in this doc.
There was a problem hiding this comment.
Does that mean it can be used to upgrade (
elemental3ctl upgrade) the OS from within its own shell environment?
Yes. (partially today, better eventually in the future)
Elemental OS
Is that the term we use for the immutable OS? Asking because I find it weird to write "immutable OS" in this doc.
no, unfortunately we're not allowed to invent our own operating system name. I think immutable OS is the best way we can describe it without resorting to "immutable version of openSUSE Tumbleweed" (better name to be found)" similar.
dharmit
force-pushed
the
sysext-elemental
branch
from
23d9c19 to
d311352
Compare
|
@atanasdinov can you suggest what sections of sysext from "Building Linux Image" we want to cover in the dedicated doc being created in this PR? I think, at least everything under Configuring through a system extension image could be in the doc of its own if we are creating such a doc. Anything else that you think could go into it? |
dharmit
force-pushed
the
sysext-elemental
branch
from
d311352 to
7d6b130
Compare
dharmit
force-pushed
the
sysext-elemental
branch
from
7d6b130 to
20b511a
Compare
| - `elemental3ctl` | ||
|
|
||
| `elemental3` is a higher level tool that takes as its input an OCI image containing ISO artifact, adds to it payload | ||
| like system extensions, Kubernetes definitions and firstboot configs, and generates an ISO or RAW file which can be |
There was a problem hiding this comment.
| like system extensions, Kubernetes definitions and firstboot configs, and generates an ISO or RAW file which can be | |
| such as system extensions, Kubernetes definitions, first-boot configs, and generates an ISO or RAW file which can be |
There was a problem hiding this comment.
English isn't my primary language, so I can't formulate my thoughts here, but here's an attempt.
IMO, system extensions, Kubernetes definitions, and first-boot configs is one thing in the context of this sentence, and then and generates an ISO or RAW file is the additional thing. So, the extra , in your suggestion system extensions, Kubernetes definitions, and first-boot config doesn't seem accurate based on how I understand the language.
Not sure if that made sense. 😂
There was a problem hiding this comment.
Hey, english is not my primary language either, so we're both tapping in the dark. I forgot to edit out the "and" in my suggestion. I updated the suggestion, hope you can agree with it. if not, it's okay the way it is right now also, not a big issue.
| target system, upgrading such OS from an OCI image, manage kernel modules on a system, unpack an OCI image, build | ||
| an installation media (generally an ISO file) from an OS image (packaged as OCI image), and more. | ||
|
|
||
| Think of `elemental3ctl` as a Linux-only tool in the sense that it helps do operations on a Linux OS image, whereas |
There was a problem hiding this comment.
| Think of `elemental3ctl` as a Linux-only tool in the sense that it helps do operations on a Linux OS image, whereas | |
| `elemental3ctl` as performs operations on a running image based Linux OS, whereas |
There was a problem hiding this comment.
What I originally wrote was offputting. I wasn't sure and hoped a review would help. But this still feels not too right.
Maybe something like:
| Think of `elemental3ctl` as a Linux-only tool in the sense that it helps do operations on a Linux OS image, whereas | |
| `elemental3ctl` is a runtime management tool that helps deploy an OS image on disk, as well as helps manage such an installation by performing upgrades, managing kernel modules, perform factory reset, etc. |
There was a problem hiding this comment.
I like your suggestion. works for me 👍
Co-authored-by: Dirk Mueller <dmueller@suse.com>
dharmit
force-pushed
the
sysext-elemental
branch
from
32cab9a to
4a59f56
Compare
|
|
||
| ## What is a system extension? | ||
|
|
||
| System extension images (or sysext images) can be disk image files or simple folders that get loaded by |
There was a problem hiding this comment.
| When a system extension image is deactivated, the `/usr` and `/opt` mountpoints are disassembled, thus revealing the | ||
| unmodified original host version of hierarchy. | ||
|
|
||
| Merging or activating makes the system extension's resources suddenly appear below `/usr` and `/opt` as if they were |
There was a problem hiding this comment.
| Merging or activating makes the system extension's resources suddenly appear below `/usr` and `/opt` as if they were | |
| Merging or activating makes the system extension's resources appear below `/usr` and `/opt` as if they were |
| a package manager like `zypper` which can be used to install additional packages. System extensions help extend the | ||
| functionality and usability of those immutable OSes. | ||
|
|
||
| ## elemental project and system extension |
There was a problem hiding this comment.
I'm not sure about this whole section TBH, or at least if it fits here. I think it would be better at the bottom once everything related to sysext has been already explained.
There was a problem hiding this comment.
Agreed. I'd suggest to have a Common Extensions instead where we cover that elemental3ctl and RKE2 are packaged and shipped as extensions with some context for them, but elemental3 description does not belong in this document.
There was a problem hiding this comment.
Perhaps "How are systemd extensions used in Elemental?" would be a good middleground.
| ### Installing RPMs in a system extension image | ||
| The Elemental project's repository contains an example that can be run directly to understand this. Check out the |
| Here there are three `mkosi.conf` files. Relative to `examples/tools-sysext` below is the brief purpose of each of | ||
| these files: |
There was a problem hiding this comment.
| Here there are three `mkosi.conf` files. Relative to `examples/tools-sysext` below is the brief purpose of each of | |
| these files: |
| @@ -0,0 +1,186 @@ | |||
| # systemd system extensions (sysext) in elemental | |||
There was a problem hiding this comment.
| # systemd system extensions (sysext) in elemental | |
| # System extensions (systemd-sysext) in Elemental |
| @@ -0,0 +1,186 @@ | |||
| # systemd system extensions (sysext) in elemental | |||
|
|
|||
| This chapter covers what a system extension (a.k.a. sysext) is, why it's relevant for elemental, and how elemental | |||
There was a problem hiding this comment.
Please capitalise all "Elemental" occurrences.
| This chapter covers what a system extension (a.k.a. sysext) is, why it's relevant for elemental, and how elemental | |
| This chapter covers what a system extension (a.k.a. sysext) is, why it's relevant for Elemental, and how Elemental |
| a package manager like `zypper` which can be used to install additional packages. System extensions help extend the | ||
| functionality and usability of those immutable OSes. | ||
|
|
||
| ## elemental project and system extension |
There was a problem hiding this comment.
Agreed. I'd suggest to have a Common Extensions instead where we cover that elemental3ctl and RKE2 are packaged and shipped as extensions with some context for them, but elemental3 description does not belong in this document.
| `/usr` and `/opt` contents of the system extension image with that of the underlying host system. | ||
|
|
||
| When a system extension image is deactivated, the `/usr` and `/opt` mountpoints are disassembled, thus revealing the | ||
| unmodified original host version of hierarchy. |
There was a problem hiding this comment.
| unmodified original host version of hierarchy. | |
| unmodified original host version of the filesystem hierarchy. |
| - `elemental3` | ||
| - `elemental3ctl` | ||
|
|
||
| `elemental3` is a higher-level tool that takes as its input an OCI image containing ISO artifact, adds payloads |
There was a problem hiding this comment.
| `elemental3` is a higher-level tool that takes as its input an OCI image containing ISO artifact, adds payloads | |
| `elemental3` is a higher-level tool that takes as its input an OCI image containing an ISO artifact, adds payloads |
| like system extensions, Kubernetes definitions and firstboot configs, and generates an ISO or RAW file which can be | ||
| used to boot a VM. | ||
|
|
||
| `elemental3ctl` is a lower-level tool that can do various things like installing an OS (packaged as an OCI image) on |
There was a problem hiding this comment.
| `elemental3ctl` is a lower-level tool that can do various things like installing an OS (packaged as an OCI image) on | |
| `elemental3ctl` is a lower-level tool that can do various things like installing an OS (packaged as an OCI image) on a |
| 1. By embedding a binary | ||
| 2. By installing an RPM | ||
|
|
||
| ### Embedding a binary in system extension image |
There was a problem hiding this comment.
| ### Embedding a binary in system extension image | |
| ### Embedding a binary in a system extension image |
|
|
||
| ### Embedding a binary in system extension image | ||
|
|
||
| In this section, we will install the `kubectl` binary as system extension on an existing ISO package as OCI image. |
There was a problem hiding this comment.
| In this section, we will install the `kubectl` binary as system extension on an existing ISO package as OCI image. | |
| In this section, we will install the `kubectl` binary as a system extension on an existing ISO package as OCI image. |
| ``` | ||
| The presence of the `mkosi.images` directory indicates that the configuration is meant for multiple images. | ||
| Here there are three `mkosi.conf` files. Relative to `examples/tools-sysext` below is the brief purpose of each of |
There was a problem hiding this comment.
| Here there are three `mkosi.conf` files. Relative to `examples/tools-sysext` below is the brief purpose of each of | |
| Here there are three `mkosi.conf` files, relative to `examples/tools-sysext`. Below is a brief summary of the purpose of each of |
| Here there are three `mkosi.conf` files. Relative to `examples/tools-sysext` below is the brief purpose of each of | ||
| these files: | ||
| - `mkosi.conf`: This is the global `mkosi` configuration file which contains distribution level configuration. |
There was a problem hiding this comment.
| - `mkosi.conf`: This is the global `mkosi` configuration file which contains distribution level configuration. | |
| - `mkosi.conf`: This is the global `mkosi` configuration file which contains distribution-level configuration. |
| This system extension can be used as an overlay during the OS installation process, following the steps in the next | ||
| section. | ||
| ### Preparing the system extension image as an overlay |
There was a problem hiding this comment.
on my initial reading, this section feels a bit out of place because it doesn't talk about why an overlay is needed or where it is being used.
I think we maybe we should keep that in the building-linux-image and simply drop it from here.
| ``` | ||
| The resulting system extension will be available in the `mkosi.output/` directory as `tools-1.0_1.0_x86-64.raw`. | ||
| This system extension can be used as an overlay during the OS installation process, following the steps in the next |
There was a problem hiding this comment.
needs to be updated depending on the resolution of the comment below. I think we could just leave it at a generic context of saying something along the lines of
Such systemd extensions can be included as an overlay in the Elemental customization process.
dirkmueller
left a comment
dirkmueller
left a comment
There was a problem hiding this comment.
In general I'm fine with the work you put into this, thanks a ton. I have a few suggestions inline, feel free to consider them or not. Only thing I'd like to get changed is removing "immutable OS" and replacing it with "image based OS". not that I think one is better over the other but that's the language we agreed with product management and marketing so we need to stick with it. 👍 otherwise.
5 participants
The idea behind this PR is to extract system extension related documentation from the "Building a Linux Virtual Machine Image with Elemental" document and have a dedicated file for it.