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.

Give Talos Linux a Try

So what are you waiting for? Head over to the image factory and build a custom image to get started. If there are extensions you need, you can build them as easily as building a container.

If there are extensions that should be available to everyone send us a PR. All images that come from the image factory are signed by Sidero and built with a Talos Linux release. This makes sure you can trust where they come from and they’re compatible with each Talos release.