How to build a Talos system extension

System Extensions are the primary way to extend Talos Linux beyond the bare minimum files and services to run Kubernetes. Hardware drivers, low level services, and extra executables are reasons you may need to add or create systems extensions.

You can add extensions managed by Sidero Labs to Talos Linux easily from the image factory, but how can you create your own? Let’s look at the process and different types of extensions you may want to consider.

What is a System Extension?

System extensions are just container images with a specific file and folder structure. You can build the container however you want, but they should be structured with the following structure.

/manifest.yaml /rootfs/<your files>

That’s it. If you wanted to build a system extension that added a file that said “HELLO” to the root of your file system you could create the two required files and put them in a container with this Dockerfile.

cat << EOF > manifest.yaml version: v1alpha1 metadata: name: hello version: 1.0 author: Justin Garrison description: | Simple text file EOF cat << EOF > ./Dockerfile FROM scratch ADD manifest.yaml / ADD hello /rootfs/hello EOF

Now you can build and push the container image to a registry.

Note: this example is using a public, temporary container registry called ttl.sh. Sidero is not affiliated with the registry and you should not publish private information to a public registry. This is only used as an example.

EXT_IMAGE=$(uuidgen) docker build -t ttl.sh/${EXT_IMAGE}:1h . docker push ttl.sh/${EXT_IMAGE}:1h

Now you can create a Talos Linux installer with your extension using imager.

docker run -t --rm -v "${PWD}/_out":/out \ ghcr.io/siderolabs/imager:v1.10.2 installer \ --system-extension-image ttl.sh/${EXT_IMAGE}:1h

Now you have a raw image file in the _out/ directory. You can load this installer into Docker (it’s a container image) and then push it to a registry.

INSTALLER_IMAGE=$(uuidgen) docker load -i ./_out/installer-amd64.tar docker tag ghcr.io/siderolabs/installer-base:v1.10.2 \ ttl.sh/${INSTALLER_IMAGE}:1h docker push ttl.sh/${INSTALLER_IMAGE}:1h

Now you can upgrade Talos Linux using the installer image you just created.

talosctl upgrade -i ttl.sh/${INSTALLER_IMAGE}:1h

Or you can provide it as the installer image for a new machine config.

talosctl gen config --install-image ttl.sh/${INSTALLER_IMAGE}:1h \ cluster https://${IP}:6443

You can check the extension is installed by querying the API or listing the filesystem.

talosctl get extensions NODE NAMESPACE TYPE ID VERSION NAME VERSION ${IP} runtime ExtensionStatus 0 1 hello 1.0 talosctl ls / NODE NAME ${IP} . ${IP} .extra ${IP} bin ${IP} boot ${IP} dev ${IP} etc ${IP} hello talosctl read /hello HELLO

Congratulations, you’ve just made the most basic system extension and installed it on a Talos Linux node.

There are other things to consider for system extensions that we won’t cover in this blog post.

• Creating an extension service
• Creating an extension with kernel modules
• Running your own image factory

If you’re interested in building a service, we recommend you check out the extension repo which has examples of all of these use cases.

Never miss an update! Sign up to receive our monthly newsletter.