Skip to content

docs(sys-ext): add comprehensive end-to-end sysext tutorial - #670

Open
v0idheaven wants to merge 1 commit into
flatcar:mainfrom
v0idheaven:docs/sysext-comprehensive-tutorial
Open

docs(sys-ext): add comprehensive end-to-end sysext tutorial#670
v0idheaven wants to merge 1 commit into
flatcar:mainfrom
v0idheaven:docs/sysext-comprehensive-tutorial

Conversation

@v0idheaven

@v0idheaven v0idheaven commented Aug 6, 2026

Copy link
Copy Markdown

Summary

This PR adds a comprehensive, hands-on six-part sysext tutorial to the docs, addressing flatcar/Flatcar#2295.

The existing sys-ext/_index.md is 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:

  • The difference between built-in, official, and community extensions (#1476)
  • How to build and test a custom extension end-to-end
  • How to deploy it in production and keep it updated

This tutorial fills that gap with working, copy-paste examples at every step.


New pages

File Content
sys-ext/tutorial/_index.md Tutorial landing page with part index
sys-ext/tutorial/understanding-sysext.md What sysext is, the three extension types, how overlays work
sys-ext/tutorial/using-official-extensions.md Enabling release extensions, opting out of built-ins, bakery extensions, verifying status
sys-ext/tutorial/building-custom-extension.md Step-by-step: directory structure, static binary, metadata file, squashfs image, systemd units
sys-ext/tutorial/testing-locally.md QEMU testing via bakery.sh boot, manual setup, debug table for merge failures
sys-ext/tutorial/production-deployment.md Ignition provisioning, checksum verification, systemd-sysupdate auto-updates, baking into images
sys-ext/tutorial/contributing-to-bakery.md Writing a create.sh recipe, smoke tests, PR conventions

Also adds a "New to sysext?" callout at the top of sys-ext/_index.md pointing 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 the extension-release metadata, building the squashfs image with mksquashfs, adding systemd units with Upholds= 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-sysupdate configuration 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

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>
@v0idheaven
v0idheaven requested a review from a team as a code owner August 6, 2026 10:31
Copilot AI lite review requested due to automatic review settings August 6, 2026 10:31

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

sysext tutorial: comprehensive end-to-end guide from concept to custom extension

2 participants