diff --git a/README.md b/README.md index b903721e..330af66f 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,36 @@ 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 specified in the Talos Linux machine configuration and, when present, will get extracted and laid down as part of the installation process. -The 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. +These images can be added to the the Talos Linux [boot asset](https://www.talos.dev/latest/talos-guides/install/boot-assets/) to produce a final boot asset containing a base Talos `initramfs` and +a set of [system extensions](https://www.talos.dev/latest/talos-guides/configuration/system-extensions/) appended to it. -## Extension Catalog +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: + +```bash +crane export ghcr.io/siderolabs/extensions:v | tar x -O image-digests | grep +``` + +For example, to find a compatible version of the `gasket-driver` extension for Talos v1.5.3, you can run: + +```bash +$ 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: -All system extensions provided by Sidero Labs can be found in the [ghcr.io registry](https://github.com/orgs/siderolabs/packages?tab=packages&q=repo%3Asiderolabs%2Fextensions). +```bash +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 diff --git a/container-runtime/gvisor/README.md b/container-runtime/gvisor/README.md index 2a9f9806..05aca334 100644 --- a/container-runtime/gvisor/README.md +++ b/container-runtime/gvisor/README.md @@ -1,15 +1,10 @@ # gVisor extension -## Usage +## Installation -Enable the extension in the machine configuration before installing Talos: +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). -```yaml -machine: - install: - extensions: - - image: ghcr.io/siderolabs/gvisor: -``` +## Usage gVisor requires unprivileged user namespace creation, so Talos default setting should be overridden: diff --git a/container-runtime/stargz-snapshotter/README.md b/container-runtime/stargz-snapshotter/README.md index 23c9e675..407f9ee2 100644 --- a/container-runtime/stargz-snapshotter/README.md +++ b/container-runtime/stargz-snapshotter/README.md @@ -1,12 +1,5 @@ # Stargz Snapshotter extension -## Usage +## Installation -Enable the extension in the machine configuration before installing Talos: - -```yaml -machine: - install: - extensions: - - image: ghcr.io/siderolabs/stargz-snapshotter: -``` +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). diff --git a/drivers/chelsio/README.md b/drivers/chelsio/README.md index 1c3fe2aa..643d226e 100644 --- a/drivers/chelsio/README.md +++ b/drivers/chelsio/README.md @@ -2,7 +2,9 @@ ## Installation -Add the extension to your machine config. +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). + +## Usage Provides: @@ -11,11 +13,4 @@ Provides: * `cxgb4` * `cxgb4vf` -```yaml -machine: - install: - extensions: - - image: ghcr.io/siderolabs/chelsio-drivers: -``` - These modules should be auto-loaded by udev based on the NIC present. diff --git a/drivers/gasket/README.md b/drivers/gasket/README.md index f254edf0..2d804600 100644 --- a/drivers/gasket/README.md +++ b/drivers/gasket/README.md @@ -2,18 +2,9 @@ ## Installation -Add the extension to your machine config and enable the modules: +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). -```yaml -machine: - install: - extensions: - - image: ghcr.io/siderolabs/gasket-driver: - kernel: - modules: - - name: gasket - - name: apex -``` +## Usage By default, the device will be owned by UID and GID `0` and is only accessible by root. If you need to change this, you may do this by adding udev rules to your machine configuration like this, @@ -32,7 +23,7 @@ You can verify the modules are enabled by reading the `/proc/modules` where it _ For example: -``` +```bash ❯ talosctl -n 192.168.32.5 read /proc/modules apex 20480 - - Live 0xffffffffc01c9000 (O) gasket 94208 - - Live 0xffffffffc01aa000 (O) @@ -42,7 +33,7 @@ In addition, if you actually have Coral module installed, you should be able to For example: -``` +```bash ❯ talosctl -n 192.168.32.5 ls -l /dev/apex_0 NODE MODE UID GID SIZE(B) LASTMOD NAME 192.168.32.5 Dcrw-rw---- 0 44 0 Sep 10 18:15:52 apex_0 diff --git a/drivers/thunderbolt/README.md b/drivers/thunderbolt/README.md index b968b8ef..89ce64f2 100644 --- a/drivers/thunderbolt/README.md +++ b/drivers/thunderbolt/README.md @@ -2,14 +2,16 @@ ## Installation -Add the extension to your machine config and enable the `thunderbolt` module. If you need Thunderbolt/USB4 networking, +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). + +## Usage + +Enable the `thunderbolt` module in Talos machine config. +If you need Thunderbolt/USB4 networking, enable `thunderbolt_net` module as well. ```yaml machine: - install: - extensions: - - image: ghcr.io/siderolabs/thunderbolt: kernel: modules: - name: thunderbolt diff --git a/drivers/usb-modem/README.md b/drivers/usb-modem/README.md index 040b2e69..50c2e37b 100644 --- a/drivers/usb-modem/README.md +++ b/drivers/usb-modem/README.md @@ -1,15 +1,17 @@ # usb-modem-drivers extension + ## Installation -Add the extension to your machine config and enable the modules, your modem might not require +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). + +## Usage + +Enable the modules in Talos Linux machine configuration, your modem might not require all of them, so feel free to remove the ones that are not needed: ```yaml machine: - install: - extensions: - - image: ghcr.io/siderolabs/usb-modem-drivers: kernel: modules: - name: usbserial @@ -59,10 +61,10 @@ or ``` ❯ talosctl -n 192.168.32.5 dmesg # look for lines like these: - kern: info: [2023-06-07T16:40:10.189868521Z]: usbcore: registered new interface driver usbhid - kern: info: [2023-06-07T16:40:10.190066521Z]: option 6-1.2:1.3: GSM modem (1-port) converter detected - kern: info: [2023-06-07T16:40:10.265654521Z]: usb 6-1.2: GSM modem (1-port) converter now attached to ttyUSB7 - kern: info: [2023-06-07T16:40:10.280291521Z]: qmi_wwan 6-1.2:1.4: cdc-wdm1: USB WDM device + kern: info: [2023-06-07T16:40:10.189868521Z]: usbcore: registered new interface driver usbhid + kern: info: [2023-06-07T16:40:10.190066521Z]: option 6-1.2:1.3: GSM modem (1-port) converter detected + kern: info: [2023-06-07T16:40:10.265654521Z]: usb 6-1.2: GSM modem (1-port) converter now attached to ttyUSB7 + kern: info: [2023-06-07T16:40:10.280291521Z]: qmi_wwan 6-1.2:1.4: cdc-wdm1: USB WDM device ``` ## Configurtion diff --git a/examples/hello-world-service/README.md b/examples/hello-world-service/README.md index 48120cb1..9aac8d6c 100644 --- a/examples/hello-world-service/README.md +++ b/examples/hello-world-service/README.md @@ -2,16 +2,11 @@ This repository is an example of an extension service. -## Usage +## Installation -Enable the extension in the machine configuration before installing Talos: +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). -```yaml -machine: - install: - extensions: - - image: ghcr.io/siderolabs/hello-world-service: -``` +## Usage Once this example extension is installed, it will provide simple HTTP server which responds with a message on port 80: diff --git a/guest-agents/qemu-guest-agent/README.md b/guest-agents/qemu-guest-agent/README.md index bdb4b0cd..38f2a652 100644 --- a/guest-agents/qemu-guest-agent/README.md +++ b/guest-agents/qemu-guest-agent/README.md @@ -1,15 +1,9 @@ # qemu-guest-agent extension -## Usage -Enable the extension in the machine configuration before installing Talos: +## Installation -```yaml -machine: - install: - extensions: - - image: ghcr.io/siderolabs/qemu-guest-agent: -``` +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). ## Testing diff --git a/guest-agents/xe-guest-utilities/README.md b/guest-agents/xe-guest-utilities/README.md index 59c269d3..d3d30fbc 100644 --- a/guest-agents/xe-guest-utilities/README.md +++ b/guest-agents/xe-guest-utilities/README.md @@ -4,18 +4,7 @@ Adds xe-guest-utilities as system extensions. ## Installation -Simplest install -``` -machine: - install: - extensions: - - image: ghcr.io/siderolabs/xe-guest-utilities:8.3.0 -``` - -``` -> talosctl apply -n node myconfig.yaml -> talosctl upgrade -n node -``` +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). ## Configuration diff --git a/misc/binfmt-misc/README.md b/misc/binfmt-misc/README.md index 378e7b5b..1ebc276d 100644 --- a/misc/binfmt-misc/README.md +++ b/misc/binfmt-misc/README.md @@ -4,13 +4,14 @@ Miscellaneous Binary Format is a capability of the Linux kernel that allows arbi ## Installation -Add the extension to your machine config and enable the modules. +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). + +## Usage + +Enable the kernel module in Talos machine config: ```yaml machine: - install: - extensions: - - image: ghcr.io/siderolabs/binfmt-misc: kernel: modules: - name: binfmt_misc diff --git a/network/tailscale/README.md b/network/tailscale/README.md index 09fc45c7..167cfa62 100644 --- a/network/tailscale/README.md +++ b/network/tailscale/README.md @@ -6,12 +6,12 @@ with tailscale ## Installation -Simplest install -``` +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). + +## Usage + +```yaml machine: - install: - extensions: - - image: ghcr.io/siderolabs/tailscale:1.44.0 files: - content: | TS_AUTHKEY= @@ -20,7 +20,7 @@ machine: op: create ``` -``` +```bash > talosctl apply -n node myconfig.yaml > talosctl upgrade -n node ``` diff --git a/nvidia-gpu/nvidia-container-toolkit/README.md b/nvidia-gpu/nvidia-container-toolkit/README.md index ff3bc2b5..57b501f1 100644 --- a/nvidia-gpu/nvidia-container-toolkit/README.md +++ b/nvidia-gpu/nvidia-container-toolkit/README.md @@ -1,15 +1,12 @@ # NVIDIA Container toolkit extension -## Usage -Enable the extension in the machine configuration before installing Talos: +## Installation -```yaml -machine: - install: - extensions: - - image: ghcr.io/siderolabs/nvidia-container-toolkit: -``` +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). + + +## Usage The following NVIDIA modules needs to be loaded, so add this to the talos config: diff --git a/power/nut-client/README.md b/power/nut-client/README.md index 4c94b433..83bfef03 100644 --- a/power/nut-client/README.md +++ b/power/nut-client/README.md @@ -1,21 +1,15 @@ # nut-client extension -## Usage +## Installation -Enable the extension in the machine configuration before installing Talos: +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). -```yaml -machine: - install: - extensions: - - image: ghcr.io/siderolabs/nut-client: -``` +## Usage -Configure the extension via .machine.files -You must replace upsmonHost and upsmonPasswd to match configuration on your nut server. +Configure the extension via `.machine.files`. +You must replace upsmonHost and upsmonPasswd to match configuration on your nut server. See [upsd.users](https://networkupstools.org/docs/man/upsd.users.html) man page for details. - On Talos SHUTDOWNCMD must be `/sbin/poweroff` ```yaml diff --git a/storage/btrfs/README.md b/storage/btrfs/README.md index 6d683683..221420a2 100644 --- a/storage/btrfs/README.md +++ b/storage/btrfs/README.md @@ -4,13 +4,14 @@ This extension provides kernel modules needed to mount btrfs filesystems. ## Installation -Add the extension to your machine config and enable the modules. +See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions). + +## Usage + +Enable the module in Talos machine config: ```yaml machine: - install: - extensions: - - image: ghcr.io/siderolabs/btrfs: kernel: modules: - name: btrfs