CNTRLPLANE-3999: add declarative TestPlan for composing v2 cluster variants and test matrices

test/e2e/v2/cmd/create-guests/main.go

@@ -66,6 +66,7 @@ const defaultNamespace = "clusters"
 
 // envConfig captures the common environment configuration.
 type envConfig struct {
+	testPlanPath string
 	prowJobID    string
 	sharedDir    string
 	artifactDir  string
@@ -104,6 +105,7 @@ func loadEnvConfig() envConfig {
 	}
 
 	cfg := envConfig{
+		testPlanPath: os.Getenv("TEST_PLAN"),
 		prowJobID:    mustGetenv("PROW_JOB_ID"),
 		sharedDir:    sharedDir,
 		artifactDir:  mustGetenv("ARTIFACT_DIR"),
@@ -130,7 +132,17 @@ func loadEnvConfig() envConfig {
 }
 
 func run(ctx context.Context, cfg envConfig) error {
-	specs := cfg.platform.ClusterSpecs(cfg.releaseImage, cfg.n1Image)
+	plan, err := lifecycle.ResolveTestPlan(cfg.testPlanPath, cfg.platform)
+	if err != nil {
+		return fmt.Errorf("resolving test plan: %w", err)
+	}
+	log.Printf("Using test plan %q", plan.Name)
+
+	allSpecs := cfg.platform.ClusterSpecs(cfg.releaseImage, cfg.n1Image)
+	if err := plan.Validate(allSpecs); err != nil {
+		return err
+	}
+	specs := plan.FilterClusterSpecs(allSpecs)
 
 	// Phase 0: The manifest must exist before any infra is provisioned so
 	// destroy-guests can always clean up, even if create-guests fails

test/e2e/v2/cmd/run-tests/main.go

@@ -42,14 +42,17 @@ func main() {
 
 	sharedDir := requireEnv("SHARED_DIR")
 	artifactDir := requireEnv("ARTIFACT_DIR")
-	releaseImage := os.Getenv("RELEASE_IMAGE_LATEST")
 
 	eventuallyVerbose := os.Getenv("EVENTUALLY_VERBOSE")
 	if eventuallyVerbose == "" {
 		eventuallyVerbose = defaultVerbose
 	}
 	os.Setenv("EVENTUALLY_VERBOSE", eventuallyVerbose)
 
+	if v := os.Getenv("RELEASE_IMAGE_LATEST"); v != "" {
+		os.Setenv("E2E_LATEST_RELEASE_IMAGE", v)
+	}
+
 	manifest, err := lifecycle.ReadManifest(sharedDir)
 	if err != nil {
 		log.Fatalf("Failed to read cluster manifest: %v", err)
@@ -63,9 +66,18 @@ func main() {
 	// Let the platform set up any env vars it needs for tests.
 	platform.SetupTestEnv(sharedDir)
 
-	matrix := platform.TestMatrix(releaseImage)
+	testPlanPath := os.Getenv("TEST_PLAN")
+	plan, err := lifecycle.ResolveTestPlan(testPlanPath, platform)
+	if err != nil {
+		log.Fatalf("Failed to resolve test plan: %v", err)
+	}
+	log.Printf("Using test plan %q", plan.Name)
+
+	if err := plan.TestMatrix.Validate(); err != nil {
+		log.Fatalf("Invalid test plan: %v", err)
+	}
 
-	clustersByVariant, err := matrix.ResolveVariants(manifest)
+	clustersByVariant, err := plan.TestMatrix.ResolveVariants(manifest)
 	if err != nil {
 		log.Fatalf("Manifest/test matrix mismatch: %v", err)
 	}
@@ -77,15 +89,15 @@ func main() {
 	)
 
 	// Launch parallel test groups.
-	for _, g := range matrix.Parallel {
+	for _, g := range plan.TestMatrix.Parallel {
 		g := g
 		entry := clustersByVariant[g.Variant]
 		wg.Add(1)
 		go func() {
 			defer wg.Done()
 			log.Printf("Running %s tests against %s...", g.Name, entry.Name)
 			err := runTestBinary(testBinary, entry.Name, entry.Namespace, g.LabelFilter, g.Skip,
-				filepath.Join(artifactDir, g.JUnitFile), g.ExtraEnv)
+				filepath.Join(artifactDir, g.JUnitFile()))
 			mu.Lock()
 			results = append(results, testResult{name: g.Name, err: err})
 			mu.Unlock()
@@ -99,7 +111,7 @@ func main() {
 
 	// Launch sequential groups (each group runs in its own goroutine,
 	// but steps within a group run one after another).
-	for _, sg := range matrix.Sequential {
+	for _, sg := range plan.TestMatrix.Sequential {
 		sg := sg
 		wg.Add(1)
 		go func() {
@@ -108,7 +120,7 @@ func main() {
 				entry := clustersByVariant[step.Variant]
 				log.Printf("Running %s tests against %s...", step.Name, entry.Name)
 				err := runTestBinary(testBinary, entry.Name, entry.Namespace, step.LabelFilter, step.Skip,
-					filepath.Join(artifactDir, step.JUnitFile), step.ExtraEnv)
+					filepath.Join(artifactDir, step.JUnitFile()))
 				mu.Lock()
 				results = append(results, testResult{name: step.Name, err: err})
 				mu.Unlock()
@@ -143,7 +155,7 @@ func main() {
 	log.Println("All test groups passed")
 }
 
-func runTestBinary(testBinary, clusterName, namespace, labelFilter, skip, junitPath string, extraEnv []string) error {
+func runTestBinary(testBinary, clusterName, namespace, labelFilter, skip, junitPath string) error {
 	ginkgoTimeout := os.Getenv("GINKGO_TIMEOUT")
 	if ginkgoTimeout == "" {
 		ginkgoTimeout = defaultGinkgoTimeout
@@ -167,7 +179,6 @@ func runTestBinary(testBinary, clusterName, namespace, labelFilter, skip, junitP
 		fmt.Sprintf("E2E_HOSTED_CLUSTER_NAME=%s", clusterName),
 		fmt.Sprintf("E2E_HOSTED_CLUSTER_NAMESPACE=%s", namespace),
 	)
-	cmd.Env = append(cmd.Env, extraEnv...)
 
 	return cmd.Run()
 }

test/e2e/v2/lifecycle/aws.go

@@ -119,20 +119,26 @@ func (a *AWSPlatformConfig) PostVersionRollout(ctx context.Context, cl crclient.
 	return nil
 }
 
-func (a *AWSPlatformConfig) TestMatrix(releaseImage string) TestMatrix {
+func (a *AWSPlatformConfig) DefaultTestPlan() TestPlan {
+	return TestPlan{
+		Name:       "aws-full",
+		Platform:   "aws",
+		TestMatrix: a.TestMatrix(),
+	}
+}
+
+func (a *AWSPlatformConfig) TestMatrix() TestMatrix {
 	return TestMatrix{
 		Parallel: []TestGroup{
 			{
 				Name:        "public",
 				Variant:     "public",
 				LabelFilter: "!lifecycle || hosted-cluster-aws",
-				JUnitFile:   "junit_public.xml",
 			},
 			{
 				Name:        "karpenter",
 				Variant:     "karpenter",
 				LabelFilter: "karpenter",
-				JUnitFile:   "junit_karpenter.xml",
 			},
 		},
 	}

test/e2e/v2/lifecycle/azure.go

@@ -321,39 +321,42 @@ func (a *AzurePlatformConfig) postCreateExternalOIDC(ctx context.Context, cl crc
 	return nil
 }
 
-func (a *AzurePlatformConfig) TestMatrix(releaseImage string) TestMatrix {
+func (a *AzurePlatformConfig) DefaultTestPlan() TestPlan {
+	return TestPlan{
+		Name:       "azure-full",
+		Platform:   "azure",
+		TestMatrix: a.TestMatrix(),
+	}
+}
+
+func (a *AzurePlatformConfig) TestMatrix() TestMatrix {
 	return TestMatrix{
 		Parallel: []TestGroup{
 			{
 				Name:        "public",
 				Variant:     "public",
 				LabelFilter: "self-managed-azure-public || nodepool-lifecycle || secret-encryption || control-plane-workloads || hosted-cluster-security || nodepool-osimagestream",
 				Skip:        "KAS allowed CIDRs",
-				JUnitFile:   "junit_self_managed_azure_public.xml",
 			},
 			{
 				Name:        "private",
 				Variant:     "private",
 				LabelFilter: "self-managed-azure-private || hosted-cluster-compliance",
-				JUnitFile:   "junit_self_managed_azure_private.xml",
 			},
 			{
 				Name:        "oauth-lb",
 				Variant:     "oauth-lb",
 				LabelFilter: "self-managed-azure-oauth-lb || hosted-cluster-health || hosted-cluster-metrics || hosted-cluster-image-registry",
-				JUnitFile:   "junit_self_managed_azure_oauth_lb.xml",
 			},
 			{
 				Name:        "autoscaling",
 				Variant:     "autoscaling",
 				LabelFilter: "nodepool-autoscaling",
-				JUnitFile:   "junit_self_managed_azure_nodepool_autoscaling.xml",
 			},
 			{
 				Name:        "external-oidc",
 				Variant:     "external-oidc",
 				LabelFilter: "external-oidc || global-pull-secret",
-				JUnitFile:   "junit_self_managed_azure_external_oidc.xml",
 			},
 		},
 		Sequential: []SequentialGroup{
@@ -364,20 +367,16 @@ func (a *AzurePlatformConfig) TestMatrix(releaseImage string) TestMatrix {
 						Name:        "upgrade",
 						Variant:     "upgrade",
 						LabelFilter: "control-plane-upgrade",
-						JUnitFile:   "junit_lifecycle_upgrade.xml",
-						ExtraEnv:    []string{fmt.Sprintf("E2E_LATEST_RELEASE_IMAGE=%s", releaseImage)},
 					},
 					{
 						Name:        "control-plane-tls",
 						Variant:     "upgrade",
 						LabelFilter: "control-plane-pki-operator",
-						JUnitFile:   "junit_control_plane_tls.xml",
 					},
 					{
 						Name:        "etcd-chaos",
 						Variant:     "upgrade",
 						LabelFilter: "etcd-chaos",
-						JUnitFile:   "junit_lifecycle_etcd_chaos.xml",
 					},
 				},
 			},
@@ -412,7 +411,6 @@ func (a *AzurePlatformConfig) DestroyArgs() []string {
 	}
 }
 
-
 func envOrDefault(key, defaultVal string) string {
 	if val := os.Getenv(key); val != "" {
 		return val

test/e2e/v2/lifecycle/platform.go

@@ -5,42 +5,106 @@ package lifecycle
 import (
 	"context"
 	"crypto/sha256"
+	"errors"
 	"fmt"
+	"strings"
 
 	crclient "sigs.k8s.io/controller-runtime/pkg/client"
 )
 
 // ClusterSpec describes a single cluster to create for lifecycle tests.
 type ClusterSpec struct {
-	Variant      string
-	ExtraArgs    []string
-	ReleaseImage string // override (empty = use default)
+	Variant      string   `json:"variant"`
+	ExtraArgs    []string `json:"extraArgs,omitempty"`
+	ReleaseImage string   `json:"releaseImage,omitempty"` // override (empty = use default)
 }
 
 // TestGroup describes one logical group of e2e tests to execute.
 type TestGroup struct {
-	Name        string
-	Variant     string
-	LabelFilter string
-	Skip        string
-	JUnitFile   string
-	ExtraEnv    []string
+	Name        string `json:"name"`
+	Variant     string `json:"variant"`
+	LabelFilter string `json:"labelFilter"`
+	Skip        string `json:"skip,omitempty"`
+}
+
+// JUnitFile returns the deterministic JUnit XML filename for this
+// test group, derived from the group name. It panics if the name
+// contains path separators or traversal sequences; callers must
+// validate the matrix before use.
+func (g TestGroup) JUnitFile() string {
+	if err := validateGroupName(g.Name); err != nil {
+		panic(err.Error())
+	}
+	return fmt.Sprintf("junit_%s.xml", g.Name)
+}
+
+// validateGroupName checks that name is safe for use as a path
+// component in JUnit filenames (no separators or traversal sequences).
+func validateGroupName(name string) error {
+	if strings.Contains(name, "/") || strings.Contains(name, "\\") || strings.Contains(name, "..") {
+		return fmt.Errorf("invalid path component in test group name: %q", name)
+	}
+	return nil
 }
 
 // SequentialGroup runs its Steps one after another within a single
 // goroutine. If any step fails, subsequent steps are skipped.
 type SequentialGroup struct {
-	Name  string
-	Steps []TestGroup
+	Name  string      `json:"name"`
+	Steps []TestGroup `json:"steps"`
 }
 
 // TestMatrix defines the full set of test groups for a platform.
 // Parallel groups all run concurrently. Each SequentialGroup also
 // runs concurrently with everything else, but its internal Steps
 // run one after another.
 type TestMatrix struct {
-	Parallel   []TestGroup
-	Sequential []SequentialGroup
+	Parallel   []TestGroup       `json:"parallel,omitempty"`
+	Sequential []SequentialGroup `json:"sequential,omitempty"`
+}
+
+// Validate checks that all group names within the matrix are unique
+// and safe for use as JUnit filename components.
+func (m TestMatrix) Validate() error {
+	seen := make(map[string]bool)
+	var errs []error
+	check := func(name string) {
+		if err := validateGroupName(name); err != nil {
+			errs = append(errs, err)
+		}
+		if seen[name] {
+			errs = append(errs, fmt.Errorf("duplicate test group name: %q", name))
+		}
+		seen[name] = true
+	}
+	for _, g := range m.Parallel {
+		check(g.Name)
+	}
+	for _, sg := range m.Sequential {
+		for _, step := range sg.Steps {
+			check(step.Name)
+		}
+	}
+	return errors.Join(errs...)
+}
+
+// Variants returns the unique cluster variants referenced by the
+// matrix. No ordering is guaranteed.
+func (m TestMatrix) Variants() []string {
+	seen := make(map[string]bool)
+	for _, g := range m.Parallel {
+		seen[g.Variant] = true
+	}
+	for _, sg := range m.Sequential {
+		for _, step := range sg.Steps {
+			seen[step.Variant] = true
+		}
+	}
+	variants := make([]string, 0, len(seen))
+	for v := range seen {
+		variants = append(variants, v)
+	}
+	return variants
 }
 
 // ResolveVariants validates that every variant referenced by the test
@@ -117,8 +181,13 @@ type PlatformConfig interface {
 	// block the initial version rollout if applied earlier.
 	PostVersionRollout(ctx context.Context, cl crclient.WithWatch, namespace string, clusterNames map[string]string) error
 
+	// DefaultTestPlan returns the full test plan for this platform,
+	// selecting all variants returned by ClusterSpecs and the complete
+	// test matrix using those variants.
+	DefaultTestPlan() TestPlan
+
 	// TestMatrix returns the test groups for this platform.
-	TestMatrix(releaseImage string) TestMatrix
+	TestMatrix() TestMatrix
 
 	// SetupTestEnv sets platform-specific environment variables
 	// before test execution (e.g., reading subnet IDs from