Base Configs Support - Phase 1

docs/imagecustomizer/api/configuration/baseConfig.md

@@ -0,0 +1,45 @@
+---
+parent: Configuration
+ancestor: Image Customizer
+---
+
+# baseConfig type
+
+This is a preview feature.
+Its API and behavior is subject to change.
+You must enable this feature by specifying `base-configs` in the
+[previewFeatures](./config.md#previewfeatures-string) API.
+
+Defines a single configuration file to inherit from.
+
+BaseConfigs specifies a list of base configuration files to inherit from.
+When multiple base configs are specified, fields are resolved in order —
+fields in later configurations overriding or extending earlier ones.
+
+**The current(last) config’s value (if specified) overrides all base configs.**
+
+- `.input.image.path`  
+- `.output.image.path`  
+- `.output.image.format`  
+- `.output.artifacts.path`
+
+**Base config items are merged with current config’s items**
+
+- `.output.artifacts.items`
+
+## path [string]
+
+Required.
+
+A file path to the base config file. The path can be either relative or absolute.
+Relative paths are resolved relative to the parent directory of the current config file.
+
+Example:
+
+```yaml
+baseConfigs:
+  - path: ./base-config.yaml
+  - path: /absolute/path/to/base-config.yaml
+```
+
+Added in v1.1.0.

docs/imagecustomizer/api/configuration/config.md

@@ -104,6 +104,15 @@ Supported options:
 
   Added in v0.15.
 
+- `base-configs`: Enables support for hierarchical configuration inheritance.
+
+  When this option is specified, the `baseConfigs` configuration becomes available.
+  This allows configurations to inherit from one or more base configurations.
+
+  See [Base Config](./baseConfig.md) for more details.
+
+  Added in v1.1.0.
+
 ## output [[output](./output.md)]
 
 Specifies the configuration for the output image and artifacts.

toolkit/tools/imagecustomizerapi/baseconfig.go

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package imagecustomizerapi
+
+import (
+	"fmt"
+	"strings"
+)
+
+type BaseConfig struct {
+	Path string `yaml:"path" json:"path"`
+}
+
+func (b BaseConfig) IsValid() error {
+	if strings.TrimSpace(b.Path) == "" {
+		return fmt.Errorf("path must not be empty or whitespace")
+	}
+	return nil
+}

toolkit/tools/imagecustomizerapi/baseconfig_test.go

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package imagecustomizerapi
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestBaseConfigIsValidNoPath(t *testing.T) {
+	base := BaseConfig{
+		Path: "",
+	}
+	err := base.IsValid()
+	assert.Error(t, err)
+	assert.ErrorContains(t, err, "path must not be empty or whitespace")
+}
+
+func TestBaseConfigIsValidWhitespaces(t *testing.T) {
+	base := BaseConfig{
+		Path: "   ",
+	}
+	err := base.IsValid()
+	assert.Error(t, err)
+	assert.ErrorContains(t, err, "path must not be empty or whitespace")
+}

toolkit/tools/imagecustomizerapi/config.go

@@ -19,6 +19,7 @@ type Config struct {
 	Scripts         Scripts          `yaml:"scripts" json:"scripts,omitempty"`
 	PreviewFeatures []PreviewFeature `yaml:"previewFeatures" json:"previewFeatures,omitempty"`
 	Output          Output           `yaml:"output" json:"output,omitempty"`
+	BaseConfigs     []BaseConfig     `yaml:"baseConfigs" json:"baseConfigs,omitempty"`
 }
 
 func (c *Config) IsValid() (err error) {
@@ -123,6 +124,18 @@ func (c *Config) IsValid() (err error) {
 		return fmt.Errorf("the 'reinitialize-verity' preview feature must be enabled to use 'storage.reinitializeVerity'")
 	}
 
+	if c.BaseConfigs != nil {
+		if !sliceutils.ContainsValue(c.PreviewFeatures, PreviewFeatureBaseConfigs) {
+			return fmt.Errorf("the '%s' preview feature must be enabled to use 'baseConfigs'", PreviewFeatureBaseConfigs)
+		}
+
+		for i, base := range c.BaseConfigs {
+			if err := base.IsValid(); err != nil {
+				return fmt.Errorf("invalid baseConfig item at index %d:\n%w", i, err)
+			}
+		}
+	}
+
 	return nil
 }
 

toolkit/tools/imagecustomizerapi/previewfeaturetype.go

@@ -28,12 +28,15 @@ const (
 
 	// PreviewFeatureFedora42 enables support for Fedora 42 images.
 	PreviewFeatureFedora42 PreviewFeature = "fedora-42"
+
+	// PreviewFeatureBaseConfigs enables support for base configuration.
+	PreviewFeatureBaseConfigs PreviewFeature = "base-configs"
 )
 
 func (pf PreviewFeature) IsValid() error {
 	switch pf {
 	case PreviewFeatureUki, PreviewFeatureOutputArtifacts, PreviewFeatureInjectFiles, PreviewFeaturePackageSnapshotTime,
-		PreviewFeatureKdumpBootFiles, PreviewFeatureFedora42:
+		PreviewFeatureKdumpBootFiles, PreviewFeatureFedora42, PreviewFeatureBaseConfigs:
 		return nil
 	default:
 		return fmt.Errorf("invalid preview feature: %s", pf)

toolkit/tools/imagecustomizerapi/schema.json

@@ -45,6 +45,15 @@
       "additionalProperties": false,
       "type": "object"
     },
+    "BaseConfig": {
+      "properties": {
+        "path": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false,
+      "type": "object"
+    },
     "BootLoader": {
       "properties": {
         "resetType": {
@@ -82,6 +91,12 @@
         },
         "output": {
           "$ref": "#/$defs/Output"
+        },
+        "baseConfigs": {
+          "items": {
+            "$ref": "#/$defs/BaseConfig"
+          },
+          "type": "array"
         }
       },
       "additionalProperties": false,

toolkit/tools/pkg/imagecustomizerlib/baseconfigs.go

@@ -0,0 +1,70 @@
+package imagecustomizerlib
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/microsoft/azure-linux-image-tools/toolkit/tools/imagecustomizerapi"
+	"github.com/microsoft/azure-linux-image-tools/toolkit/tools/internal/file"
+)
+
+type ConfigWithBasePath struct {
+	Config         *imagecustomizerapi.Config
+	BaseConfigPath string
+}
+
+func buildConfigChain(ctx context.Context, rc *ResolvedConfig) ([]*ConfigWithBasePath, error) {
+	visited := make(map[string]bool)
+	pathStack := []string{}
+
+	configChain, err := buildConfigChainHelper(ctx, rc.Config, rc.BaseConfigPath, visited, pathStack)
+	if err != nil {
+		return nil, err
+	}
+
+	return configChain, nil
+}
+
+func buildConfigChainHelper(ctx context.Context, cfg *imagecustomizerapi.Config, configFilePath string, visited map[string]bool,
+	pathStack []string,
+) ([]*ConfigWithBasePath, error) {
+	var chain []*ConfigWithBasePath
+
+	for _, base := range cfg.BaseConfigs {
+		absPath := file.GetAbsPathWithBase(configFilePath, base.Path)
+
+		if visited[absPath] {
+			return nil, fmt.Errorf("cycle detected in baseConfigs: %v -> %s", pathStack, absPath)
+		}
+
+		visited[absPath] = true
+		pathStack = append(pathStack, absPath)
+
+		// Load base file into struct
+		var baseCfg imagecustomizerapi.Config
+		if err := imagecustomizerapi.UnmarshalYamlFile(absPath, &baseCfg); err != nil {
+			return nil, fmt.Errorf("failed to load base config (%s):\n%w", absPath, err)
+		}
+
+		// Validate base config content
+		if err := baseCfg.IsValid(); err != nil {
+			return nil, fmt.Errorf("%w (%s):\n%w", ErrInvalidBaseConfigs, absPath, err)
+		}
+
+		// Recurse into base config
+		subChain, err := buildConfigChainHelper(ctx, &baseCfg, absPath, visited, pathStack)
+		if err != nil {
+			return nil, err
+		}
+
+		chain = append(chain, subChain...)
+	}
+
+	// Add the current config last
+	chain = append(chain, &ConfigWithBasePath{
+		Config:         cfg,
+		BaseConfigPath: configFilePath,
+	})
+
+	return chain, nil
+}

toolkit/tools/pkg/imagecustomizerlib/baseconfigs_test.go

@@ -0,0 +1,51 @@
+package imagecustomizerlib
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/microsoft/azure-linux-image-tools/toolkit/tools/imagecustomizerapi"
+	"github.com/microsoft/azure-linux-image-tools/toolkit/tools/internal/file"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestBaseConfigsInputAndOutput(t *testing.T) {
+	testTempDir := filepath.Join(tmpDir, "TestBaseConfigsInputAndOutput")
+	defer os.RemoveAll(testTempDir)
+
+	buildDir := filepath.Join(testTempDir, "build")
+	currentConfigFile := filepath.Join(testDir, "hierarchical-config.yaml")
+
+	options := ImageCustomizerOptions{
+		BuildDir: buildDir,
+	}
+
+	var config imagecustomizerapi.Config
+	err := imagecustomizerapi.UnmarshalYamlFile(currentConfigFile, &config)
+	assert.NoError(t, err)
+
+	rc, err := ValidateConfig(t.Context(), testDir, &config, false, options)
+	assert.NoError(t, err)
+
+	// Verify resolved values
+	expectedInputPath := file.GetAbsPathWithBase(testDir, "testimages/empty.vhdx")
+	expectedOutputPath := file.GetAbsPathWithBase(testDir, "./out/output-image-2.vhdx")
+	expectedArtifactsPath := file.GetAbsPathWithBase(testDir, "./artifacts-2")
+
+	assert.Equal(t, expectedInputPath, rc.InputImageFile)
+	assert.Equal(t, expectedOutputPath, rc.OutputImageFile)
+	assert.Equal(t, expectedArtifactsPath, rc.OutputArtifacts.Path)
+	assert.Equal(t, "testname", rc.Config.OS.Hostname)
+
+	// Verify merged artifact items
+	expectedItems := []imagecustomizerapi.OutputArtifactsItemType{
+		imagecustomizerapi.OutputArtifactsItemUkis,
+		imagecustomizerapi.OutputArtifactsItemShim,
+	}
+	actual := rc.OutputArtifacts.Items
+	assert.Equal(t, len(expectedItems), len(actual))
+
+	assert.ElementsMatch(t, expectedItems, actual,
+		"output artifact items should match - expected: %v, got: %v", expectedItems, actual)
+}