Retitle and re-scope the system extension authoring guide
Nobody has claimed this yet.
- Dominant language
- MDX
- Stars
- 11
- Forks
- 76
- Avg merge
- 3d 5h
- Merged PRs (30d)
- 26
Description
Problem
The complete guide to authoring a Talos system extension is published as Adding a Kernel Module. Despite the title, that page covers the entire authoring path: creating a package in pkgs, the bldr pkg.yaml, creating the extension, the manifest.yaml, building the installer with imager, and installing on a fresh or existing machine. A kernel module is one worked example of that path, not the scope of it.
Meanwhile the "Author system extensions" section of the System Extensions page is three sentences:
A Talos system extension is a container image with the specific folder structure. System extensions can be built and managed using any tool that produces container images, e.g.
docker build. Sidero Labs maintains a repository of system extensions.
So a reader who wants to build an extension opens the page named for their task, gets three sentences and a pointer to GitHub, and never reaches the guide that would have answered them. This surfaced in user feedback in August: a user could not find extension authoring documentation and is running Talos in VMs as a result.
What to do
- Retitle the kernel-module page to name what it actually covers (something like "Building a system extension"), keeping the kernel module as the worked example. Add a
redirectsentry for the old path. - Cross-link it from the "Author system extensions" section of the System Extensions page, as the primary path rather than the GitHub pointer.
- Bring in the two things that currently live only in the extensions repo README: the
manifest.yamlstructure, and therootfspath allowlist (extension files are confined to a specific set of paths, no special files, no world-writeable files). A reader who follows our guide and then hits an unstated path restriction has to go read the repo anyway, which defeats the point of having the guide. - State the catalog constraint, scoped to the public factory. The public Image Factory at
factory.talos.devbuilds only from the official extension catalog, so a custom extension requires the self-runimagerpath. Boot Assets says this; the extension pages do not, and it is the constraint that determines whether the guide is usable for a given reader at all. Write it as a property of the public factory rather than of Image Factory generally: the enterprise factory has an additive extension catalog that its operator can point at another OCI repository, so the unqualified version of the sentence is false there. That capability is not reachable by a customer today and is not documented anywhere yet, so it stays off this page. Just don't write a sentence we have to come back and correct.
One thing to preserve while generalizing: the page's kernel-specific constraint is real and should stay. Kernel modules have to be built alongside the kernel because they are signed with a key only available during the kernel build. That is a property of kernel modules rather than of extensions generally, so once the page is generalized it needs to read as a special case rather than a universal step.
Diátaxis type: how-to (retitle and expand).
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the current Adding a Kernel Module page and the Author system extensions section of the System Extensions page, then compare the extensions repository README. Retitle and expand the guide, add the old-path redirect and cross-link, and document the manifest structure, rootfs allowlist, public factory catalog constraint, and kernel-module special case. Done means the authoring path is discoverable without relying on the repository README.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100