search

siderolabs / image-factory

A service to generate Talos boot assets
Mozilla Public License 2.0
60 stars 16 forks source link

readme

Image Factory

The Image Factory provides a way to download Talos Linux artifacts. Artifacts can be generated with customizations defined by a "schematic". A schematic can be applied to any of the versions of Talos Linux offered by the Image Factory to produce a "model".

The following assets are provided:

The supported frontends are:

The official Image Factory is available at https://factory.talos.dev.

HTTP Frontend API

POST /schematics

Create a new image schematic.

The request body is a YAML (JSON) encoded schematic description:

customization:
    extraKernelArgs: # optional
        - vga=791
    meta: # optional, allows to set initial Talos META
      - key: 0xa
        value: "{}"
    systemExtensions: # optional
      officialExtensions: # optional
        - siderolabs/gvisor
        - siderolabs/amd-ucode
    secureboot: # optional, only applies to SecureBoot images
       # optional, include well-known UEFI certificates into auto-enrollment database (SecureBoot ISO only)
      includeWellKnownCertificates: true
overlay: # optional
  image: ghcr.io/siderolabs/sbc-raspberry-pi # overlay image
  name: rpi_generic # overlay name
  options: # optional, any valid yaml, depends on the overlay implementation
    data: "mydata"

Output is a JSON-encoded schematic ID:

{"id":"2a63b6e7dab90ec9d44f213339b9545bd39c6499b22a14cf575c1ca4b6e39ff8"}

This ID can be used to download images with this schematic.

Well-known schematic IDs:

GET /image/:schematic/:version/:path

Download a Talos Linux boot image with the specified schematic and Talos Linux version.

Common used parameters:

Supported image paths:

GET /versions

Returns a list of Talos Linux versions available for image generation.

["v1.5.0","v1.5.1", "v1.5.2"]

GET /version/:version/extensions/official

Returns a list of official system extensions available for the specified Talos Linux version.

[
  {
    "name": "siderolabs/amd-ucode",
    "ref": "ghcr.io/siderolabs/amd-ucode:20230804",
    "digest": "sha256:761a5290a4bae9ceca11468d2ba8ca7b0f94e6e3a107ede2349ae26520682832",
  },

]

GET /version/:version/overlays/official

Returns a list of official overlays available for the specified Talos Linux version.

[
  {
    "name": "rpi_generic",
    "image": "siderolabs/sbc-raspberrypi",
    "ref": "ghcr.io/siderolabs/sbc-raspberrypi:v0.1.0",
    "digest": "sha256:849ace01b9af514d817b05a9c5963a35202e09a4807d12f8a3ea83657c76c863",
  },

]

GET /secureboot/signing-cert.pem

Returns PEM-encoded SecureBoot signing certificate used by the Image Factory.

It might be used to manually enroll the certificate into the UEFI firmware. Talos Linux SecureBoot ISOs come with an option for automatic enrollment of the certificate, but if that is not desired, the certificate can be manually enrolled.

PXE Frontend API

The PXE frontend provides an iPXE script that automatically downloads and boots Talos Linux. The bare metal machine should be configured to boot from the URL provided by this API, e.g.:

#!ipxe
chain --replace --autofree https://pxe.talos.dev/pxe/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba/v1.5.0/metal-${buildarch}

GET /pxe/:schematic/:version/:path

Returns an iPXE script which downloads and boots Talos Linux with the specified schematic and Talos Linux version, architecture and platform.

In non-SecureBoot schematic, the following iPXE script is returned:

#!ipxe
kernel https://pxe.talos.dev/image/:schematic/:version/kernel-<arch> <kernel-cmdline>
initrd https://pxe.talos.dev/image/:schematic/:version/initramfs-<arch>.xz
boot

For SecureBoot schematic, the following iPXE script is returned:

#!ipxe
kernel https://pxe.talos.dev/image/:schematic/:version/<platform>-<arch>-secureboot.uki.efi
boot

OCI Registry Frontend API

The Talos Linux installer image is used for the initial install and upgrades. It can be pulled from the Image Factory OCI registry. If the image hasn't been created yet, it will be built on demand automatically.

docker pull <registry>/installer[-secureboot]/<schematic>:<version>

Example: docker pull factory.talos.dev/installer/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba:v1.5.0

Pulls the Talos Linux installer image with the specified schematic and Talos Linux version. The image platform (architecture) will be determined by the architecture of the Talos Linux Linux machine.

GET /oci/cosign/signing-key.pub

Returns PEM-encoded public key used to sign the Talos Linux installer images.

The key can be used to verify the installer images with cosign:

cosign verify --offline --insecure-ignore-tlog --insecure-ignore-sct --key signing-key.pub factory.talos.dev/...

Development

Run integration tests in local mode, with registry mirrors:

make integration TEST_FLAGS="-test.image-registry=127.0.0.1:5004 -test.schematic-service-repository=127.0.0.1:5005/image-factory/schematic -test.installer-external-repository=127.0.0.1:5005/test -test.installer-internal-repository=127.0.0.1:5005/test -test.cache-repository=127.0.0.1:5005/cache" REGISTRY=127.0.0.1:5005

In order to run the Image Factory, generate a ECDSA key pair:

openssl ecparam -name prime256v1 -genkey -noout -out cache-signing-key.key

Run the Image Factory passing the flags:

-image-registry 127.0.0.1:5004 # registry mirror for ghcr.io
-external-url https://example.com/ # external URL the Image Factory is available at
-schematic-service-repository 127.0.0.1:5005/image-factory/schematic # private registry for schematics
-installer-internal-repository 127.0.0.1:5005/siderolabs # internal registry to push installer images to
-installer-external-repository 127.0.0.1:5005/siderolabs # external registry to redirect users to pull installer
-cache-repository 127.0.0.1:5005/cache # private registry for cached assets
-cache-signing-key-path ./cache-signing-key.key # path to the ECDSA private key (to sign cached assets)