Imager Overlay specification

[smira]

Imager Overlay is a container image with the following structure:

.
├── artifacts
│   └── arm64
│       ├── dtb
│       │   └── rpi_4
│       ├── firmware
│       │   └── rpi4
│       │       └── firmware_20240302.bin
│       └── u-boot
│           └── rpi4.uboot.img
├── installers
│   └── rpi_generic
└── profiles
    ├── rpi_4.yaml
    └── rpi_5.yaml

12 directories, 3 files

An overlay can be passed to the imager an argument (part of the imager Profile), it is the first thing that imager will pull, unpack and use.

Imager Profile changes:

...
overlay:
   image:
      imageRef: ghcr.io/siderolabs/overlay-rpi-generic:v24
      # ociPath: /overlays/rpi.oci
   name: rpi_generic
   options: # map[string]any
       bootconfig: |
           hdmi=2

When the overlay is specified, the imager will read extra profiles from profiles/ directory and append them to the list of default profiles available.

After that imager works almost same way, but it has two hooks into the installers binary picked up by overlay.name:

package overlay

// Provided by overlay installer
// Used by the imager/Talos installer
type Installer interface{
   GetOptions(extra map[string]any) (Options, error)
   Install(options InstallOptions) error
}

// Returned by the overlay installer
type Options struct{
   Name string
   KernelArgs []string
   PartitionOptions struct {
       Offset uint64
   }
}

// Passed to the overlay installer
type InstallOptions struct {
   InstallDisk string // device name
   MountPrefix string // mount path of new Talos root (e.g. /boot)
   ArtifactsPath string // path to `artifacts/` directory from an overlay
   ExtraOptions map[string]any // overlay.options in the Profile
}

The interface between imager and a binary will be command-line stdin/stdout based, described in more details below.

We will implement Go wrappers to implement this overlay.Installer interface via command-line for both imager and overlay installer.

Draft of the command-line interface:

$ overlay-installer get-options
# STDIN << YAML
extraOptions: // map[string]any
   bootconfig: foo
# STDOUT >> YAML
name: rpi_4
kernelArgs:
  - console=ttyS1
...
# STDERR: error message (if failed)
invalid board
# EXIT CODE: 0 for no error, != 0 for error

$ overlay-installer install
# STDIN << YAML
installDisk: /dev/nvme0n1
artifactsPath: /tmp/artifacts
...
# STDOUT >> YAML
<empty>
# STDERR: error message (if failed)
invalid board
# EXIT CODE: 0 for no error, != 0 for error