docs: update documentation on installing extensions

Remove deprecated `.machine.install.extensions`, point to Talos
documentation.

Once Image Factory is live, we can point to it.

Signed-off-by: Andrey Smirnov <andrey.smirnov@siderolabs.com>

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<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:
+
+```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
 

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:<VERSION>
-```
+## Usage
 
 gVisor requires unprivileged user namespace creation, so Talos default setting
 should be overridden:

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:<VERSION>
-```
+See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions).

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:<VERSION>
-```
-
 These modules should be auto-loaded by udev based on the NIC present.

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:<VERSION>
-  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

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:<VERSION>
   kernel:
     modules:
       - name: thunderbolt

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:<VERSION>
   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

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:<VERSION>
-```
+## Usage
 
 Once this example extension is installed, it will provide simple HTTP server which responds with a message on port 80:
 

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:<VERSION>
-```
+See [Installing Extensions](https://github.com/siderolabs/extensions#installing-extensions).
 
 ## Testing
 

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
 

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:<VERSION>
   kernel:
     modules:
       - name: binfmt_misc

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=<your auth key>
@@ -20,7 +20,7 @@ machine:
       op: create
 ```
 
-```
+```bash
 > talosctl apply -n node myconfig.yaml
 > talosctl upgrade -n node
 ```

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:<VERSION>
-```
+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:
 

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:<VERSION>
-```
+## 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

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:<VERSION>
   kernel:
     modules:
       - name: btrfs