docs(sys-ext): add comprehensive end-to-end sysext tutorial - #670
Open
v0idheaven wants to merge 1 commit into
Open
docs(sys-ext): add comprehensive end-to-end sysext tutorial#670v0idheaven wants to merge 1 commit into
v0idheaven wants to merge 1 commit into
Conversation
Add a six-part hands-on tutorial covering the full systemd-sysext
lifecycle on Flatcar, from first concepts to contributing upstream:
Part 1 - Understanding sysext
What systemd-sysext is, why Flatcar uses it, and a clear explanation
of the three extension types (built-in, official, community) which
users consistently find confusing (see flatcar/Flatcar#1476).
Part 2 - Using official extensions
Enabling release extensions via enabled-sysext.conf, Butane config
examples, opting out of built-in extensions, community bakery
extensions, verifying status, and reloading at runtime.
Part 3 - Building your first custom extension
Step-by-step: directory structure, static binary download, writing
the extension-release metadata file, building a squashfs image,
adding systemd units with Upholds= drop-ins.
Part 4 - Testing locally
Using bakery.sh boot for one-command local testing, manual QEMU
setup, and a debugging reference table covering common merge errors.
Part 5 - Production deployment
Ignition provisioning with checksum verification, deploying multiple
extensions, auto-updates with systemd-sysupdate, and baking
extensions into custom Flatcar images.
Part 6 - Contributing to sysext-bakery
Turn a custom extension into a reusable bakery recipe: create.sh
implementation, smoke tests, PR conventions, and what happens after
the PR is merged.
Also adds a callout at the top of sys-ext/_index.md pointing new users
to the tutorial.
Closes flatcar/Flatcar#2295
Signed-off-by: v0idheaven <dahiyavarun2007@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a comprehensive, hands-on six-part sysext tutorial to the docs, addressing flatcar/Flatcar#2295.
The existing
sys-ext/_index.mdis a solid reference page but does not serve as a learning path. New users especially those coming from traditional Linux distros consistently get confused about three things:This tutorial fills that gap with working, copy-paste examples at every step.
New pages
sys-ext/tutorial/_index.mdsys-ext/tutorial/understanding-sysext.mdsys-ext/tutorial/using-official-extensions.mdsys-ext/tutorial/building-custom-extension.mdsys-ext/tutorial/testing-locally.mdbakery.sh boot, manual setup, debug table for merge failuressys-ext/tutorial/production-deployment.mdsystemd-sysupdateauto-updates, baking into imagessys-ext/tutorial/contributing-to-bakery.mdcreate.shrecipe, smoke tests, PR conventionsAlso adds a "New to sysext?" callout at the top of
sys-ext/_index.mdpointing users to the tutorial.What each part covers
Part 1 - Understanding sysext
Explains the read-only overlay model, why Flatcar uses sysext, and gives a clear side-by-side comparison of the three extension types with concrete examples of when to use each.
Part 2 - Using official extensions
Covers
enabled-sysext.conf, Butane config examples, opting out of built-in docker/containerd, provisioning bakery extensions,systemd-sysext status, and runtime reload.Part 3 - Building a custom extension
Full walkthrough packaging
jq(a static binary) as a sysext: directory layout, downloading the binary, writing theextension-releasemetadata, building the squashfs image withmksquashfs, adding systemd units withUpholds=drop-ins.Part 4 - Testing locally
One-command testing via
bakery.sh boot, manual QEMU setup with an HTTP server and Ignition config, and a debugging reference table covering the most common merge errors and how to fix them.Part 5 - Production deployment
Ignition provisioning with SHA-512 checksum verification, deploying multiple extensions,
systemd-sysupdateconfiguration for automatic updates, and baking extensions into custom Flatcar images.Part 6 - Contributing to sysext-bakery
Implementing
create.sh, adding smoke tests, bakery conventions (no/usr/sbin, static binaries,Upholds=drop-ins), opening a PR, and what happens after merge.Closes flatcar/Flatcar#2295