feat: allow specifying a schematic id

Closes #3

Signed-off-by: Steven Kreitzer <[email protected]>
Signed-off-by: Utku Ozdemir <[email protected]>

Author: buroa

cmd/booter/main.go

@@ -137,6 +137,8 @@ func init() {
 	rootCmd.Flags().BoolVar(&serverOptions.DisableDHCPProxy, "disable-dhcp-proxy", serverOptions.DisableDHCPProxy,
 		"Disable the DHCP proxy server.")
 
+	rootCmd.Flags().StringVar(&serverOptions.SchematicID, "schematic-id", serverOptions.SchematicID,
+		"The ID of the schematic to use.")
 	rootCmd.Flags().StringSliceVar(&serverOptions.Extensions, "extensions", serverOptions.Extensions,
 		"List of Talos extensions to use. The extensions will be used to generate schematic ID from the image factory.")
 	rootCmd.Flags().StringVarP(&serverOptions.ExtraKernelArgs, extraKernelArgsFlag, "k", serverOptions.ExtraKernelArgs,

go.mod

@@ -1,6 +1,6 @@
 module github.com/siderolabs/booter
 
-go 1.24.5
+go 1.25.3
 
 replace (
 	github.com/pin/tftp/v3 => github.com/utkuozdemir/pin-tftp/v3 v3.0.0-20241021135417-0dd7dba351ad

internal/server/imagefactory/client.go

@@ -37,18 +37,11 @@ func NewClient(baseURL, pxeBaseURL string, secureBootEnabled bool, logger *zap.L
 	}, nil
 }
 
-// SchematicIPXEURL ensures a schematic exists on the image factory and returns the iPXE URL to it.
-//
-// If agentMode is true, the schematic will be created with the firmware extensions and the metal-agent extension.
-func (c *Client) SchematicIPXEURL(ctx context.Context, talosVersion, arch string, extensions, extraKernelArgs []string) (string, error) {
-	logger := c.logger.With(zap.String("talos_version", talosVersion), zap.String("arch", arch),
-		zap.Strings("extensions", extensions), zap.Strings("extra_kernel_args", extraKernelArgs))
+// EnsureSchematic ensures a schematic exists on the image factory and returns its ID.
+func (c *Client) EnsureSchematic(ctx context.Context, extensions, extraKernelArgs []string) (string, error) {
+	logger := c.logger.With(zap.Strings("extensions", extensions), zap.Strings("extra_kernel_args", extraKernelArgs))
 
-	logger.Debug("generate schematic iPXE URL")
-
-	if talosVersion == "" {
-		return "", fmt.Errorf("talosVersion is required")
-	}
+	logger.Debug("ensure schematic")
 
 	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
 	defer cancel()
@@ -74,12 +67,28 @@ func (c *Client) SchematicIPXEURL(ctx context.Context, talosVersion, arch string
 		return "", fmt.Errorf("failed to create schematic: %w", err)
 	}
 
+	return schematicID, nil
+}
+
+// GetIPXEURL returns the iPXE URL for the given schematic ID, Talos version, and architecture.
+func (c *Client) GetIPXEURL(schematicID, talosVersion, arch string) (string, error) {
+	if schematicID == "" {
+		return "", fmt.Errorf("schematic ID is required")
+	}
+
+	if talosVersion == "" {
+		return "", fmt.Errorf("talos version is required")
+	}
+
+	if arch == "" {
+		return "", fmt.Errorf("arch is required")
+	}
+
 	ipxeURL := fmt.Sprintf("%s/pxe/%s/%s/metal-%s", c.pxeBaseURL, schematicID, talosVersion, arch)
+
 	if c.secureBootEnabled {
 		ipxeURL += "-secureboot"
 	}
 
-	logger.Debug("generated schematic iPXE URL", zap.String("ipxe_url", ipxeURL))
-
 	return ipxeURL, nil
 }

internal/server/ipxe/handler.go

@@ -37,14 +37,16 @@ chain --replace %s
 
 // ImageFactoryClient represents an image factory client which ensures a schematic exists on image factory, and returns the PXE URL to it.
 type ImageFactoryClient interface {
-	SchematicIPXEURL(ctx context.Context, talosVersion, arch string, extensions, extraKernelArgs []string) (string, error)
+	EnsureSchematic(ctx context.Context, extensions, extraKernelArgs []string) (string, error)
+	GetIPXEURL(schematicID, talosVersion, arch string) (string, error)
 }
 
 // HandlerOptions represents the options for the iPXE handler.
 type HandlerOptions struct {
 	APIAdvertiseAddress string
 	TalosVersion        string
 	ExtraKernelArgs     string
+	SchematicID         string
 	Extensions          []string
 	APIPort             int
 }
@@ -93,9 +95,12 @@ func (handler *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request) {
 
 	// TODO: later, we can do per-machine kernel args and system extensions here
 
-	kernelArgs := slices.Concat(handler.kernelArgs, handler.consoleKernelArgs(arch))
+	consoleKernelArgs := handler.consoleKernelArgs(arch)
+	kernelArgs := slices.Concat(handler.kernelArgs, consoleKernelArgs)
 
-	body, statusCode, err := handler.bootViaFactoryIPXEScript(ctx, handler.options.TalosVersion, arch, handler.options.Extensions, kernelArgs)
+	logger.Debug("injected console kernel args to the iPXE request", zap.Strings("console_kernel_args", consoleKernelArgs))
+
+	body, statusCode, err := handler.bootViaFactoryIPXEScript(ctx, arch, kernelArgs)
 	if err != nil {
 		handler.logger.Error("failed to get iPXE script", zap.Error(err))
 
@@ -123,9 +128,18 @@ func (handler *Handler) handleInitScript(w http.ResponseWriter) {
 	}
 }
 
-func (handler *Handler) bootViaFactoryIPXEScript(ctx context.Context, talosVersion, arch string, extensions, kernelArgs []string) (body string, statusCode int, err error) {
-	ipxeURL, err := handler.imageFactoryClient.SchematicIPXEURL(ctx, talosVersion, arch, extensions, kernelArgs)
-	if err != nil {
+func (handler *Handler) bootViaFactoryIPXEScript(ctx context.Context, arch string, kernelArgs []string) (body string, statusCode int, err error) {
+	schematicID := handler.options.SchematicID
+
+	if schematicID == "" {
+		if schematicID, err = handler.imageFactoryClient.EnsureSchematic(ctx, handler.options.Extensions, kernelArgs); err != nil {
+			return "", http.StatusInternalServerError, fmt.Errorf("failed to get schematic IPXE URL: %w", err)
+		}
+	}
+
+	var ipxeURL string
+
+	if ipxeURL, err = handler.imageFactoryClient.GetIPXEURL(schematicID, handler.options.TalosVersion, arch); err != nil {
 		return "", http.StatusInternalServerError, fmt.Errorf("failed to get schematic IPXE URL: %w", err)
 	}
 
@@ -145,6 +159,21 @@ func (handler *Handler) consoleKernelArgs(arch string) []string {
 
 // NewHandler creates a new iPXE server.
 func NewHandler(ctx context.Context, configServerEnabled bool, imageFactoryClient ImageFactoryClient, options HandlerOptions, logger *zap.Logger) (*Handler, error) {
+	apiHostPort := net.JoinHostPort(options.APIAdvertiseAddress, strconv.Itoa(options.APIPort))
+	talosConfigURL := fmt.Sprintf("http://%s/config?u=${uuid}", apiHostPort)
+	talosConfigKernelArg := fmt.Sprintf("%s=%s", constants.KernelParamConfig, talosConfigURL)
+
+	if options.SchematicID != "" {
+		if len(options.Extensions) > 0 || len(options.ExtraKernelArgs) > 0 {
+			return nil, fmt.Errorf("schematicID cannot be used with extensions or extraKernelArgs")
+		}
+
+		if configServerEnabled {
+			logger.Sugar().Warnf("schematic ID is set explicitly to %q and the config server is enabled (e.g., Omni connection is requested), "+
+				"note that if this schematic does not contain the kernel arg %q, the machines will not be able to connect to the config server", options.SchematicID, talosConfigKernelArg)
+		}
+	}
+
 	initScript, err := buildInitScript(options.APIAdvertiseAddress, options.APIPort)
 	if err != nil {
 		return nil, fmt.Errorf("failed to build init script: %w", err)
@@ -161,10 +190,9 @@ func NewHandler(ctx context.Context, configServerEnabled bool, imageFactoryClien
 	kernelArgs := strings.Fields(options.ExtraKernelArgs)
 
 	if configServerEnabled {
-		apiHostPort := net.JoinHostPort(options.APIAdvertiseAddress, strconv.Itoa(options.APIPort))
-		talosConfigURL := fmt.Sprintf("http://%s/config?u=${uuid}", apiHostPort)
+		kernelArgs = append(kernelArgs, talosConfigKernelArg)
 
-		kernelArgs = append(kernelArgs, fmt.Sprintf("%s=%s", constants.KernelParamConfig, talosConfigURL))
+		logger.Debug("injected talos config kernel arg to the iPXE requests", zap.String("arg", talosConfigKernelArg))
 	}
 
 	return &Handler{

internal/server/options.go

@@ -15,6 +15,7 @@ type Options struct {
 	DHCPProxyIfaceOrIP     string
 	TalosVersion           string
 	ExtraKernelArgs        string
+	SchematicID            string
 	Extensions             []string
 	Omni                   omni.Options
 	APIPort                int

internal/server/server.go

@@ -98,6 +98,7 @@ func (s *Server) Run(ctx context.Context) error {
 		Extensions:          s.options.Extensions,
 		ExtraKernelArgs:     s.options.ExtraKernelArgs,
 		TalosVersion:        s.options.TalosVersion,
+		SchematicID:         s.options.SchematicID,
 	}, s.logger.With(zap.String("component", "ipxe_handler")))
 	if err != nil {
 		return fmt.Errorf("failed to create iPXE handler: %w", err)