customization: add firstboot

pkg/blueprint/customizations.go

@@ -36,6 +36,7 @@ type Customizations struct {
 	RHSM               *RHSMCustomization             `json:"rhsm,omitempty" toml:"rhsm,omitempty"`
 	CACerts            *CACustomization               `json:"cacerts,omitempty" toml:"cacerts,omitempty"`
 	ContainersStorage  *ContainerStorageCustomization `json:"containers-storage,omitempty" toml:"containers-storage,omitempty"`
+	Firstboot          *FirstbootCustomization        `json:"firstboot,omitempty" toml:"firstboot,omitempty"`
 }
 
 type IgnitionCustomization struct {

pkg/blueprint/firstboot_customizations.go

@@ -0,0 +1,181 @@
+package blueprint
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+)
+
+type FirstbootCustomization struct {
+	Scripts []FirstbootScriptCustomization `json:"scripts,omitempty" toml:"scripts,omitempty"`
+}
+
+type FirstbootScriptCustomization struct {
+	union json.RawMessage
+}
+
+// FirstbootCommonCustomization contains common fields for all firstboot customizations.
+type FirstbootCommonCustomization struct {
+	// Type of the firstboot customization. Supported values are:
+	// "custom", "satellite", and "aap".
+	Type string `json:"type,omitempty" toml:"type,omitempty"`
+
+	// Optional firstboot name. Must be unique within the blueprint and only
+	// alphanumeric characters with dashes and underscores are allowed.
+	Name string `json:"name,omitempty" toml:"name,omitempty"`
+
+	// Ignore errors when executing the firstboot script and continue with
+	// execution of the following firstboot scripts, if any. By default,
+	// firstboot scripts are executed in order and if one of them fails, the
+	// execution stops immediately.
+	IgnoreFailure bool `json:"ignore_failure,omitempty" toml:"ignore_failure,omitempty"`
+}
+
+// CustomFirstbootCustomization contains fields specific to custom firstboot
+// customizations.
+type CustomFirstbootCustomization struct {
+	FirstbootCommonCustomization
+
+	// Strings without shebang will be interpreted as shell scripts, otherwise
+	// the script will be executed using the shebang interpreter. Required if
+	// type is set to "custom".
+	Contents string `json:"contents" toml:"contents"`
+}
+
+// SatelliteFirstbootCustomization contains fields specific to satellite firstboot
+// customizations.
+type SatelliteFirstbootCustomization struct {
+	FirstbootCommonCustomization
+
+	// Optional CA certificate to enroll into the system before executing the
+	// firstboot script.
+	CACerts []string `json:"cacerts,omitempty" toml:"cacerts,omitempty"`
+
+	// Registration command as generated by the Satellite server. Required, if
+	// type is set to "satellite".
+	Command string `json:"command,omitempty" toml:"command,omitempty"`
+}
+
+// AAPFirstbootCustomization contains fields specific to AAP firstboot
+// customizations.
+type AAPFirstbootCustomization struct {
+	FirstbootCommonCustomization
+
+	// Optional CA certificate to enroll into the system before executing the
+	// firstboot script.
+	CACerts []string `json:"cacerts,omitempty" toml:"cacerts,omitempty"`
+
+	// Job template URL as generated by the AAP server. Required if type is set
+	// to "aap". Example URLs are
+	// https://aap.example.com/api/controller/v2/job_templates/9/callback/ or
+	// https://aap.example.com/api/v2/job_templates/9/callback/ depending on the
+	// AAP version.
+	JobTemplateURL string `json:"job_template_url,omitempty" toml:"job_template_url,omitempty"`
+
+	// The host config key. Required if type is set to "aap".
+	HostConfigKey string `json:"host_config_key,omitempty" toml:"host_config_key,omitempty"`
+}
+
+func (t FirstbootScriptCustomization) MarshalJSON() ([]byte, error) {
+	b, err := t.union.MarshalJSON()
+	if err != nil {
+		return nil, fmt.Errorf("FirstbootScriptCustomization marshalling error: %w", err)
+	}
+	return b, nil
+}
+
+func (t *FirstbootScriptCustomization) UnmarshalJSON(b []byte) error {
+	err := t.union.UnmarshalJSON(b)
+	if err != nil {
+		return fmt.Errorf("FirstbootScriptCustomization unmarshalling error: %w", err)
+	}
+	return nil
+}
+
+func (t FirstbootScriptCustomization) MarshalTOML() ([]byte, error) {
+	b, err := t.union.MarshalJSON()
+	if err != nil {
+		return nil, err
+	}
+	return jsonToToml(b)
+}
+
+func (t *FirstbootScriptCustomization) UnmarshalTOML(data any) error {
+	return unmarshalTOMLviaJSON(t, data)
+}
+
+var ErrMissingCustomContents = errors.New("missing contents field for custom firstboot customization")
+var ErrUnknownFirstbootCustomization = errors.New("unknown firstboot customization: missing or invalid type field")
+var ErrMissingAAPFields = errors.New("missing job_template_url or host_config_key field for aap firstboot customization")
+var ErrMissingSatelliteCommand = errors.New("missing command field for satellite firstboot customization")
+
+func unmarshalFirstbootScript[S any](data json.RawMessage) (*S, error) {
+	var script S
+	jd := json.NewDecoder(bytes.NewReader(data))
+	jd.DisallowUnknownFields()
+	err := jd.Decode(&script)
+	if err != nil {
+		return nil, err
+	}
+	return &script, nil
+}
+
+// SelectUnion returns the specific firstboot customization types. The detection
+// is based on the "type" field in the JSON payload. Returns nil for irrelevant types,
+// or if the type is unknown or if there is an error during unmarshaling.
+func (sp FirstbootScriptCustomization) SelectUnion() (*CustomFirstbootCustomization, *SatelliteFirstbootCustomization, *AAPFirstbootCustomization, error) {
+	var fcc FirstbootCommonCustomization
+	err := json.Unmarshal(sp.union, &fcc)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+
+	switch strings.ToLower(fcc.Type) {
+	case "custom":
+		cc, err := unmarshalFirstbootScript[CustomFirstbootCustomization](sp.union)
+		if err != nil {
+			return nil, nil, nil, err
+		}
+		if cc.Contents == "" {
+			return nil, nil, nil, ErrMissingCustomContents
+		}
+		return cc, nil, nil, nil
+	case "satellite":
+		sc, err := unmarshalFirstbootScript[SatelliteFirstbootCustomization](sp.union)
+		if err != nil {
+			return nil, nil, nil, err
+		}
+		if sc.Command == "" {
+			return nil, nil, nil, ErrMissingSatelliteCommand
+		}
+		return nil, sc, nil, err
+	case "aap":
+		ac, err := unmarshalFirstbootScript[AAPFirstbootCustomization](sp.union)
+		if err != nil {
+			return nil, nil, nil, err
+		}
+		if ac.JobTemplateURL == "" || ac.HostConfigKey == "" {
+			return nil, nil, nil, ErrMissingAAPFields
+		}
+		return nil, nil, ac, err
+	default:
+		return nil, nil, nil, ErrUnknownFirstbootCustomization
+	}
+}
+
+func FirstbootScriptCustomizationFromCustom(node CustomFirstbootCustomization) FirstbootScriptCustomization {
+	u, _ := json.Marshal(node)
+	return FirstbootScriptCustomization{union: u}
+}
+
+func FirstbootScriptCustomizationFromSatellite(node SatelliteFirstbootCustomization) FirstbootScriptCustomization {
+	u, _ := json.Marshal(node)
+	return FirstbootScriptCustomization{union: u}
+}
+
+func FirstbootScriptCustomizationFromAAP(node AAPFirstbootCustomization) FirstbootScriptCustomization {
+	u, _ := json.Marshal(node)
+	return FirstbootScriptCustomization{union: u}
+}