Using overlays

About overlays

Overlays customize a Talos Linux boot image by integrating with the installation steps. They let users add boot assets, like those needed for single-board computers, provide extra kernel arguments, or include custom configurations specific to that overlay and not part of the default Talos installation. Overlays are similar to extensions but are used to modify the installation process rather than the root filesystem. They are often used to customize the installation process for single board computers (SBCs) such as the Raspberry Pi.

Using overlays

In this example, we’ll create an image using an overlay for a Raspberry Pi 4b SBC. Beware that you cannot use the resulting image with other SBCs. Please be aware, that compatibility with certain SBCs is limited to the platforms supported by Talos and read about the current limitations, as stated in the FAQ section.

UI

Prerequisites:

• Successfully authenticated in the UI of a STEC instance.

Steps:

1. Follow the generic image creation steps, as described in the getting started guide.

2. In the step that allows you to select an overlay image, choose the one called rpi_generic.

   

3. Follow the remaining image creation steps. The resulting review should indicate, that your overlay is included in the image. It’ll be part of any installation medium generated from this image. Click the “create” button to create the image.

   

4. The rest of the process is identical to the regular image creation procedure.

CLI

Prerequisites:

• Successfully authenticated with a STEC instance.
• Kubeconfig for the STEC instance is exported in your terminal session.
• Tools: a generic Linux bash terminal, kubectl.

Steps:

1. Follow the generic image creation steps, as described in the getting started guide.

2. At the step where you have to create an EdgeImage manifest file, make sure to add the Raspberry Pi overlay called rpi_generic using its image siderolabs/sbc-raspberrypi.

   > cat <<EOF | kubectl apply -f -
   apiVersion: edge.stackit.cloud/v1alpha1
   kind: EdgeImage
   metadata:
   name: olyfoo
   namespace: default
   spec:
   schematic: |
   customization:
   extraKernelArgs: []
   systemExtensions:
   officialExtensions: []
   overlay:
   image: siderolabs/sbc-raspberrypi
         name: rpi_generic
   talosVersion: v1.10.5-stackit.v0.21.0
   EOL
   
   edgeimage.edge.stackit.cloud/olyfoo created
   
   > kubectl get EdgeImage/olyfoo
   NAME AGE
   olyfoo      1m

3. The rest of the process is identical to the regular image creation procedure.

Currently, the only way to get a list of all available image versions, overlays, or extensions, is to query the STEC image factory. The following example shows how to use the API to get a list of Talos overlays.

# get available overlays
> INSTANCE_REGION="eu01"
> curl https://image-factory.edge.$INSTANCE_REGION.stackit.cloud/versions
[
 "v1.10.5-stackit.v0.20.0",
 "v1.10.5-stackit.v0.21.0",
 "..."
]

> IMAGE_VERSION="v1.10.5-stackit.v0.20.0"
> curl https://image-factory.edge.$INSTANCE_REGION.stackit.cloud/version/$IMAGE_VERSION/overlays/official
[
 {
 "name": "rpi_generic",
 "image": "siderolabs/sbc-raspberrypi",
 "ref": "stecreg.azurecr.io/siderolabs/sbc-raspberrypi:v0.1.5",
 "digest": "sha256:70a1b174a5bddd57da33e377af324c1f93d7ed87b9bc8f6cdefe5ec179abb4c9"
 },
 "..."
]

References

• Talos overlays