README.md

Talos Linux System Extensions

This repo serves as a central place for publishing supported extensions to Talos Linux. Extensions allow for additional functionality on top of the default Talos Linux capabilities. Things like gVisor, GPU support, etc. are good candidates for extensions.

Using Extensions

Extensions in this repo are published as container images. These images can be added to the the Talos Linux boot asset to produce a final boot asset containing a base Talos initramfs and a set of system extensions appended to it.

The extension image is composed of a manifest.yaml file that provides information and compatibility information, as well as a rootfs that contains things like compiled binaries that are bind mounted into the system.

Installing Extensions

In order to find a container reference for a system extension compatible with your Talos Linux version, you can use the following command:

crane export ghcr.io/siderolabs/extensions:v<talos-version> | tar x -O image-digests | grep <extension-name>

For example, to find a compatible version of the gasket-driver extension for Talos v1.5.3, you can run:

$ crane export ghcr.io/siderolabs/extensions:v1.5.3 | tar x -O image-digests | grep gasket-driver
ghcr.io/siderolabs/gasket-driver:97aeba58-v1.5.3@sha256:c786edb356edae3b451cb82d5322f94e54ea0710195181b93ae37ccc8e7ba908

Please always use the pinned digest when referencing an extension image.

All extensions are signed with Google Accounts OIDC issuer matching @siderolabs.com domain, so the image signatures can be verified, for example:

cosign verify --certificate-identity-regexp '@siderolabs\.com$' --certificate-oidc-issuer https://accounts.google.com ghcr.io/siderolabs/extensions:v1.5.3
cosign verify --certificate-identity-regexp '@siderolabs\.com$' --certificate-oidc-issuer https://accounts.google.com ghcr.io/siderolabs/gasket-driver:97aeba58-v1.5.3@sha256:c786edb356edae3b451cb82d5322f94e54ea0710195181b93ae37ccc8e7ba908

Extension Catalog

Container Runtimes

Name	Image	Description	Version Format
crun	ghcr.io/siderolabs/crun	crun container runtime	upstream version
ecr-credential-provider	ghcr.io/siderolabs/ecr-credential-provider	ECR Credential Provider kubelet plugin	upstream version
gvisor	ghcr.io/siderolabs/gvisor	gVisor container runtime	upstream version
kata-containers	ghcr.io/siderolabs/kata-containers	Kata Containers container runtime	upstream version
spin	ghcr.io/siderolabs/spin	Spin container runtime	upstream_version
stargz-snapshotter	ghcr.io/siderolabs/stargz-snapshotter	Stargz Snapshotter container runtime	upstream version
wasmedge	ghcr.io/siderolabs/wasmedge	WasmEdge container runtime	upstream_version

Firmware

Name	Image	Description	Version Format
amd-ucode	ghcr.io/siderolabs/amd-ucode	AMD CPU microcode updates	linux firmware version
bnx2-bnx2x	ghcr.io/siderolabs/bnx2-bnx2x	Broadcom NetXtreme firmware	linux firmware version
chelsio-firmware	ghcr.io/siderolabs/chelsio-firmware	Chelsio NIC firmware	linux firmware version
intel-ice-firmware	ghcr.io/siderolabs/intel-ice-firmware	Intel ICE NIC firmware	linux firmware version
intel-ucode	ghcr.io/siderolabs/intel-ucode	Intel CPU microcode updates	upstream version
qlogic-firmware	ghcr.io/siderolabs/qlogic-firmware	Qlogic firmware	linux firmware version
realtek-firmware	ghcr.io/siderolabs/realtek-firmware	Realtek firmware	linux firmware version

Direct Rendering Manager (DRM)

Name	Image	Description	Version Format
amdgpu	ghcr.io/siderolabs/amdgpu	AMD GPU firmware and drivers	linux firmware version-talos version
i915	ghcr.io/siderolabs/i915	Intel GPU firmware and drivers	linux firmware version-talos version

Drivers

Name	Image	Description	Version Format
chelsio	ghcr.io/siderolabs/chelsio-drivers	Chelsio NIC drivers	talos version
gasket	ghcr.io/siderolabs/gasket-driver	Driver for Google Coral PCIe devices	gasket driver upstream short commit-talos version
mei	ghcr.io/siderolabs/mei	Driver for Intel Management Engine	talos version
nvidia	ghcr.io/siderolabs/nvidia-open-gpu-kernel-modules	NVIDIA OSS Driver	nvidia driver upstream version-talos version
thunderbolt	ghcr.io/siderolabs/thunderbolt	Thunderbolt drivers	talos version
uinput	ghcr.io/siderolabs/uinput	uinput drivers	talos version
usb-modem	ghcr.io/siderolabs/usb-modem-drivers	USB Modem drivers	talos version
v4l-uvc	ghcr.io/siderolabs/v4l-uvc-drivers	USB Video Class (Webcam) drivers	talos version

Digital Video Broadcasting (DVB)

Name	Image	Description	Version Format
dvb-cx23885	ghcr.io/siderolabs/dvb-cx23885	DVB kernel modules + firmware for Hauppage WinTV-quadHD PCIe	talos version

Miscellaneous

Name	Image	Description	Version Format
binfmt-misc	ghcr.io/siderolabs/binfmt-misc	Miscellaneous Binary Format	talos version
glibc	ghcr.io/siderolabs/glibc	glibc	upstream version

Network

Name	Image	Description	Version Format
cloudflared	ghcr.io/siderolabs/cloudflared	Cloudflared	upstream version
lldpd	ghcr.io/siderolabs/lldpd	LLDP	upstream version
tailscale	ghcr.io/siderolabs/tailscale	Tailscale	upstream version

Storage

Name	Image	Description	Version Format
btrfs	ghcr.io/siderolabs/btrfs	BTRFS driver module	talos version
drbd	ghcr.io/siderolabs/drbd	DRBD driver module	upstream version-talos version
iscsi-tools	ghcr.io/siderolabs/iscsi-tools	Open iSCSI tools	v0.1.0
mdadm	ghcr.io/siderolabs/mdadm	manage MD devices tool	upstream version
zfs	ghcr.io/siderolabs/zfs	ZFS driver module	upstream version-talos version

Power

Name	Image	Description	Version Format
nut-client	ghcr.io/siderolabs/nut-client	Network UPS Tools upsmon client	upstream version

Guest Agents

Name	Image	Description	Version Format
metal-agent	ghcr.io/siderolabs/metal-agent	Talos Metal Agent	upstream version
qemu-guest-agent	ghcr.io/siderolabs/qemu-guest-agent	QEMU Guest Agent	upstream version
vmtoolsd-guest-agent	ghcr.io/siderolabs/vmtoolsd-guest-agent	talos-vmtoolsd	upstream version
xe-guest-utilities	ghcr.io/siderolabs/xe-guest-utilities	xe-guest-utilities	upstream version

NVIDIA GPU

Name	Description	Version Format
nvidia-container-toolkit	Tools to run NVIDIA GPU workloads in containers	driver version-toolkit version
nvidia-fabricmanager	NVIDIA fabric manager support for GPU workloads	driver version
nvidia-open-gpu-kernel-modules	NVIDIA driver kernel modules	driver version-talos version

Tools

Name	Description	Version Format
util-linux-tools	Util Linux tools (fstrim and nsenter)	upstream version

Building Extensions

In the current form, building extensions requires the use of our bldr tool. It is highly recommended to take a look at an existing extensions as a template for building your own. The rough flow should look like the following:

• Create a manifest.yaml file that contains information about your system extension. See instructions below for this file.
• Create a pkg.yaml file that details the full flow of downloading, building, installing your application.
• Once you have these, add your extension to the TARGETS list in the Makefile.
• You can now build your extension using make like make <extension-name> PLATFORM=linux/amd64
• If you wish to output the contents of the image and validate your install, you can issue make local-<extension-name> PLATFORM=linux/amd64 DEST=_out. The contents will then be present in the _out directory.

Creating manifest.yaml

The manifest.yaml file should match the following format:

version: v1alpha1
metadata:
  name: <extension name>
  version: <version of the package the extension installs>-<version of the extensions repo (tracks with talos version)>
  author: Andrew Rynhard
  description: |
    <detailed description of the extension/package>
  ## The compatibility section is "optional" but highly recommended to specify a Talos version that
  ## has been tested and known working for this extension.
  compatibility:
    talos:
      version: ">= v1.0.0"

Creating pkg.yaml

Creating a pkg.yaml file is the normal process from bldr. See instructions here for details and examples on this format. Using other existing extensions in this repo for tips is also highly recommended. One important note is that the final directory tree of the generated package should look like this example from the gvisor package:

├── manifest.yaml
└── rootfs
    ├── etc
    │   └── cri
    │       └── conf.d
    │           └── gvisor.part
    └── usr
        └── local
            └── bin
                ├── containerd-shim-runsc-v1
                └── runsc

Note that the manifest.yaml file lives at the root, while all installed files live under /rootfs with the full tree of where they should live on the eventual Talos Linux install.

rootfs Restrictions

The following restrictions are applied to the contents of the rootfs of the system extension:

• no special files (FIFOs, devices, etc.)
• no world-writeable files or directories

Any paths in the rootfs should be contained within the following hierarchies:

• /etc/cri/conf.d/
• /lib/firmware/
• /lib/modules/
• /lib64/ld-linux-x86-64.so.2
• /usr/lib/udev/rules.d/
• /usr/local/
• /usr/share/glvnd/
• /usr/share/egl/
• /etc/vulkan/

Dependency Diagram