Enable possibility to use capabilities in images jobs

Make capabilities and additional_architectures equivalent during transition.
Both fields are merged into a unified capabilities list via AllCapabilities().
For architecture-specific logic (e.g. ResolveMultiArch), ArchitectureCapabilities()
filters the merged list against valid architecture strings.

- Add AllCapabilities() and ArchitectureCapabilities() helpers
- Mark AdditionalArchitectures as deprecated in favor of Capabilities
- Update prowgen, validation, project_image, and image-graph-generator
  to use the new helpers instead of accessing fields directly
- Add validation for Capabilities values
- Fix Capabilities comment on image build config (was "test runs")

Signed-off-by: Jakub Guzik <jguzik@redhat.com>

Author: jmguzik

pkg/api/types.go

@@ -2810,11 +2810,16 @@ type ProjectDirectoryImageBuildStepConfiguration struct {
 	MultiArch bool `json:"multi_arch,omitempty"`
 
 	// AdditionalArchitectures is a list of additional architectures to build for. AMD64 architecture is included by default.
+	// DEPRECATED: use Capabilities instead
 	AdditionalArchitectures []string `json:"additional_architectures,omitempty"`
 
 	// Ref is an optional string linking to the extra_ref in "org.repo" format that this belongs to
 	Ref string `json:"ref,omitempty"`
 
+	// Capabilities is the list of strings that
+	// define additional capabilities needed by the image build jobs
+	Capabilities []string `json:"capabilities,omitempty"`
+
 	// isBundleImage indicates that this build step is a bundle image
 	isBundleImage bool
 }
@@ -2834,6 +2839,33 @@ func (p *ProjectDirectoryImageBuildStepConfiguration) WithBundleImage(isBundleIm
 	return p
 }
 
+// ValidArchitectures is the set of supported architecture strings for image builds.
+var ValidArchitectures = sets.New[string](
+	"amd64",   // x86-64
+	"arm64",   // AArch64
+	"ppc64le", // PowerPC 64-bit Little Endian
+	"s390x",   // IBM System z 64-bit
+)
+
+// AllCapabilities returns the deduplicated, sorted union of Capabilities and
+// AdditionalArchitectures. Both fields are treated as equivalent during the
+// transition period while AdditionalArchitectures is being phased out.
+func (p *ProjectDirectoryImageBuildStepConfiguration) AllCapabilities() []string {
+	return sets.List(sets.New[string](append(p.Capabilities, p.AdditionalArchitectures...)...))
+}
+
+// ArchitectureCapabilities returns the subset of AllCapabilities that are valid
+// architecture strings (e.g. "arm64", "ppc64le").
+func (p *ProjectDirectoryImageBuildStepConfiguration) ArchitectureCapabilities() []string {
+	var arches []string
+	for _, c := range p.AllCapabilities() {
+		if ValidArchitectures.Has(c) {
+			arches = append(arches, c)
+		}
+	}
+	return arches
+}
+
 // ProjectDirectoryImageBuildInputs holds inputs for an image build from the repo under test
 type ProjectDirectoryImageBuildInputs struct {
 	// ContextDir is the directory in the project

pkg/api/zz_generated.deepcopy.go

@@ -104,10 +104,7 @@ func (o *Operator) callback(c *api.ReleaseBuildConfiguration, i *config.Info) er
 
 		for _, image := range c.Images {
 			if !excludedImages.Has(string(image.To)) {
-				multiArch := false
-				if len(image.AdditionalArchitectures) > 0 {
-					multiArch = true
-				}
+			multiArch := len(image.ArchitectureCapabilities()) > 0
 				if err := o.UpdateImage(image, c.BaseImages, target, branchID, multiArch); err != nil {
 					errs = append(errs, err)
 				}

pkg/image-graph-generator/operator.go

@@ -126,7 +126,7 @@ func GenerateJobs(configSpec *cioperatorapi.ReleaseBuildConfiguration, info *Pro
 		}
 		imagesTestName := "images"
 		jobBaseGen := newJobBaseBuilder().TestName(imagesTestName)
-		injectArchitectureLabels(jobBaseGen, configSpec.Images)
+		injectCapabilitiesForImgJobs(jobBaseGen, configSpec.Images)
 
 		optional := false
 		for _, image := range configSpec.Images {
@@ -143,7 +143,7 @@ func GenerateJobs(configSpec *cioperatorapi.ReleaseBuildConfiguration, info *Pro
 
 		if configSpec.PromotionConfiguration != nil {
 			jobBaseGen = newJobBaseBuilder().TestName(imagesTestName)
-			injectArchitectureLabels(jobBaseGen, configSpec.Images)
+			injectCapabilitiesForImgJobs(jobBaseGen, configSpec.Images)
 
 			jobBaseGen.PodSpec.Add(Promotion(), Targets(imageTargets.UnsortedList()...))
 			// Note: Slack reporter config for images postsubmit is now handled in generatePostsubmitForTest
@@ -436,10 +436,10 @@ func injectCapabilities(labels map[string]string, capabilities []string) {
 	}
 }
 
-func injectArchitectureLabels(g *prowJobBaseBuilder, imagesConfig []cioperatorapi.ProjectDirectoryImageBuildStepConfiguration) {
-	for _, imageConfig := range imagesConfig {
-		for _, arch := range imageConfig.AdditionalArchitectures {
-			g.WithLabel(fmt.Sprintf("capability/%s", arch), arch)
+func injectCapabilitiesForImgJobs(g *prowJobBaseBuilder, imagesConfig []cioperatorapi.ProjectDirectoryImageBuildStepConfiguration) {
+	for _, img := range imagesConfig {
+		for _, c := range img.AllCapabilities() {
+			g.WithLabel(fmt.Sprintf("capability/%s", c), c)
 		}
 	}
 }

pkg/prowgen/prowgen.go

@@ -730,6 +730,52 @@ func TestGenerateJobs(t *testing.T) {
 				},
 			},
 		},
+		{
+			id: "multiarch postsubmit images, using capabilities",
+			config: &ciop.ReleaseBuildConfiguration{
+				Images: []ciop.ProjectDirectoryImageBuildStepConfiguration{
+					{
+						From:         "os",
+						To:           "ci-tools",
+						Capabilities: []string{"arm64"},
+					},
+					{
+						From:         "os",
+						To:           "test",
+						Capabilities: []string{"arm64", "ppc64-le"},
+					},
+				},
+				PromotionConfiguration: &ciop.PromotionConfiguration{},
+			},
+			repoInfo: &ProwgenInfo{
+				Metadata: ciop.Metadata{
+					Org:    "organization",
+					Repo:   "repository",
+					Branch: "branch",
+				},
+			},
+		},
+		{
+			id: "merge capabilities and architecture labels",
+			config: &ciop.ReleaseBuildConfiguration{
+				Images: []ciop.ProjectDirectoryImageBuildStepConfiguration{
+					{
+						From:                    "os",
+						To:                      "ci-tools",
+						Capabilities:            []string{"arm64"},
+						AdditionalArchitectures: []string{"ppc64-le"},
+					},
+				},
+				PromotionConfiguration: &ciop.PromotionConfiguration{},
+			},
+			repoInfo: &ProwgenInfo{
+				Metadata: ciop.Metadata{
+					Org:    "organization",
+					Repo:   "repository",
+					Branch: "branch",
+				},
+			},
+		},
 		{
 			id: "multiarch test job",
 			config: &ciop.ReleaseBuildConfiguration{

pkg/prowgen/prowgen_test.go

@@ -0,0 +1,17 @@
+postsubmits:
+  organization/repository:
+  - always_run: true
+    labels:
+      capability/arm64: arm64
+      capability/ppc64-le: ppc64-le
+      ci-operator.openshift.io/is-promotion: "true"
+    max_concurrency: 1
+    name: branch-ci-organization-repository-branch-images
+presubmits:
+  organization/repository:
+  - always_run: false
+    labels:
+      capability/arm64: arm64
+      capability/ppc64-le: ppc64-le
+      pj-rehearse.openshift.io/can-be-rehearsed: "true"
+    name: pull-ci-organization-repository-branch-images

pkg/prowgen/testdata/zz_fixture_TestGenerateJobs_merge_capabilities_and_architecture_labels.yaml

@@ -0,0 +1,17 @@
+postsubmits:
+  organization/repository:
+  - always_run: true
+    labels:
+      capability/arm64: arm64
+      capability/ppc64-le: ppc64-le
+      ci-operator.openshift.io/is-promotion: "true"
+    max_concurrency: 1
+    name: branch-ci-organization-repository-branch-images
+presubmits:
+  organization/repository:
+  - always_run: false
+    labels:
+      capability/arm64: arm64
+      capability/ppc64-le: ppc64-le
+      pj-rehearse.openshift.io/can-be-rehearsed: "true"
+    name: pull-ci-organization-repository-branch-images

pkg/prowgen/testdata/zz_fixture_TestGenerateJobs_multiarch_postsubmit_images__using_capabilities.yaml

@@ -200,7 +200,7 @@ func (s *projectDirectoryImageBuildStep) Objects() []ctrlruntimeclient.Object {
 
 func (s *projectDirectoryImageBuildStep) ResolveMultiArch() sets.Set[string] {
 	s.architectures.Insert(string(api.NodeArchitectureAMD64))
-	s.architectures.Insert(s.config.AdditionalArchitectures...)
+	s.architectures.Insert(s.config.ArchitectureCapabilities()...)
 
 	// TODO: deprecated when the multi_arch field is removed from the configuration
 	if s.multiArch {

pkg/steps/project_image.go

@@ -4,7 +4,6 @@ import (
 	"errors"
 	"fmt"
 	"regexp"
-	"sort"
 	"strings"
 
 	"k8s.io/apimachinery/pkg/api/resource"
@@ -307,13 +306,6 @@ func validateBuildRootImageStreamTag(ctx *configContext, buildRoot api.ImageStre
 func ValidateImages(ctx *configContext, images []api.ProjectDirectoryImageBuildStepConfiguration) []error {
 	var validationErrors []error
 
-	var validArchitectures = sets.New(
-		"amd64",   // x86-64
-		"arm64",   // AArch64
-		"ppc64le", // PowerPC 64-bit Little Endian
-		"s390x",   // IBM System z 64-bit
-	)
-
 	for num, image := range images {
 		ctxN := ctx.addIndex(num)
 		if image.To == "" {
@@ -326,12 +318,19 @@ func ValidateImages(ctx *configContext, images []api.ProjectDirectoryImageBuildS
 			validationErrors = append(validationErrors, ctxN.errorf("dockerfile_literal is mutually exclusive with context_dir and dockerfile_path"))
 		}
 		for _, arch := range image.AdditionalArchitectures {
-			if !validArchitectures.Has(arch) {
-				archList := validArchitectures.UnsortedList()
-				sort.Strings(archList)
+			if !api.ValidArchitectures.Has(arch) {
+				archList := sets.List(api.ValidArchitectures)
 				validationErrors = append(validationErrors, ctxN.errorf("invalid architecture: %s. Use one of %s", arch, strings.Join(archList, ", ")))
 			}
 		}
+		for _, cap := range image.Capabilities {
+			if api.ValidArchitectures.Has(cap) {
+				continue
+			}
+			if err := validation.IsQualifiedName(cap); len(err) > 0 {
+				validationErrors = append(validationErrors, ctxN.errorf("invalid capability: %s", cap))
+			}
+		}
 
 	}
 	return validationErrors

pkg/validation/config.go

@@ -185,6 +185,7 @@ const ciOperatorReferenceYaml = "# The list of base images describe\n" +
 	"# and can be used to build only a specific image.\n" +
 	"images:\n" +
 	"    - # AdditionalArchitectures is a list of additional architectures to build for. AMD64 architecture is included by default.\n" +
+	"      # DEPRECATED: use Capabilities instead\n" +
 	"      additional_architectures:\n" +
 	"        - \"\"\n" +
 	"      # BuildArgs contains build arguments that will be resolved in the Dockerfile.\n" +
@@ -194,6 +195,10 @@ const ciOperatorReferenceYaml = "# The list of base images describe\n" +
 	"          name: ' '\n" +
 	"          # Value of the build arg.\n" +
 	"          value: ' '\n" +
+	"      # Capabilities is the list of strings that\n" +
+	"      # define additional capabilities needed by the image build jobs\n" +
+	"      capabilities:\n" +
+	"        - \"\"\n" +
 	"      # ContextDir is the directory in the project\n" +
 	"      # from which this build should be run.\n" +
 	"      context_dir: ' '\n" +
@@ -426,6 +431,7 @@ const ciOperatorReferenceYaml = "# The list of base images describe\n" +
 	"        ref: ' '\n" +
 	"      project_directory_image_build_step:\n" +
 	"        # AdditionalArchitectures is a list of additional architectures to build for. AMD64 architecture is included by default.\n" +
+	"        # DEPRECATED: use Capabilities instead\n" +
 	"        additional_architectures:\n" +
 	"            - \"\"\n" +
 	"        # BuildArgs contains build arguments that will be resolved in the Dockerfile.\n" +
@@ -435,6 +441,10 @@ const ciOperatorReferenceYaml = "# The list of base images describe\n" +
 	"              name: ' '\n" +
 	"              # Value of the build arg.\n" +
 	"              value: ' '\n" +
+	"        # Capabilities is the list of strings that\n" +
+	"        # define additional capabilities needed by the image build jobs\n" +
+	"        capabilities:\n" +
+	"            - \"\"\n" +
 	"        # ContextDir is the directory in the project\n" +
 	"        # from which this build should be run.\n" +
 	"        context_dir: ' '\n" +