Add bundle-release annotation to CER and phase objects

Plumb release as an explicit annotation (BundleReleaseKey) so the
release portion of the bundle version is directly inspectable without
parsing build metadata. The annotation is only set when a release
value is present (additive, non-breaking).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: pedjak

internal/operator-controller/applier/boxcutter.go

@@ -82,6 +82,9 @@ func (r *SimpleRevisionGenerator) GenerateRevisionFromHelmRelease(
 		if v := helmRelease.Labels[labels.PackageNameKey]; v != "" {
 			annotationUpdates[labels.PackageNameKey] = v
 		}
+		if v := helmRelease.Labels[labels.BundleReleaseKey]; v != "" {
+			annotationUpdates[labels.BundleReleaseKey] = v
+		}
 		if len(annotationUpdates) > 0 {
 			obj.SetAnnotations(mergeStringMaps(obj.GetAnnotations(), annotationUpdates))
 		}
@@ -90,12 +93,16 @@ func (r *SimpleRevisionGenerator) GenerateRevisionFromHelmRelease(
 			WithObject(obj))
 	}
 
-	rev := r.buildClusterExtensionRevision(objs, ext, map[string]string{
+	cerAnnotations := map[string]string{
 		labels.BundleNameKey:      helmRelease.Labels[labels.BundleNameKey],
 		labels.PackageNameKey:     helmRelease.Labels[labels.PackageNameKey],
 		labels.BundleVersionKey:   helmRelease.Labels[labels.BundleVersionKey],
 		labels.BundleReferenceKey: helmRelease.Labels[labels.BundleReferenceKey],
-	})
+	}
+	if v := helmRelease.Labels[labels.BundleReleaseKey]; v != "" {
+		cerAnnotations[labels.BundleReleaseKey] = v
+	}
+	rev := r.buildClusterExtensionRevision(objs, ext, cerAnnotations)
 	rev.WithName(fmt.Sprintf("%s-1", ext.Name))
 	rev.Spec.WithRevision(1)
 	rev.Spec.WithCollisionProtection(ocv1.CollisionProtectionNone) // allow to adopt objects from previous release
@@ -164,6 +171,9 @@ func (r *SimpleRevisionGenerator) GenerateRevision(
 		if v := revisionAnnotations[labels.PackageNameKey]; v != "" {
 			annotationUpdates[labels.PackageNameKey] = v
 		}
+		if v := revisionAnnotations[labels.BundleReleaseKey]; v != "" {
+			annotationUpdates[labels.BundleReleaseKey] = v
+		}
 		if len(annotationUpdates) > 0 {
 			unstr.SetAnnotations(mergeStringMaps(unstr.GetAnnotations(), annotationUpdates))
 		}

internal/operator-controller/applier/boxcutter_test.go

@@ -75,6 +75,7 @@ func Test_SimpleRevisionGenerator_GenerateRevisionFromHelmRelease(t *testing.T)
 			labels.BundleNameKey:      "my-bundle",
 			labels.PackageNameKey:     "my-package",
 			labels.BundleVersionKey:   "1.2.0",
+			labels.BundleReleaseKey:   "3",
 			labels.BundleReferenceKey: "bundle-ref",
 		},
 	}
@@ -102,6 +103,7 @@ func Test_SimpleRevisionGenerator_GenerateRevisionFromHelmRelease(t *testing.T)
 		WithAnnotations(map[string]string{
 			"olm.operatorframework.io/bundle-name":               "my-bundle",
 			"olm.operatorframework.io/bundle-reference":          "bundle-ref",
+			"olm.operatorframework.io/bundle-release":            "3",
 			"olm.operatorframework.io/bundle-version":            "1.2.0",
 			"olm.operatorframework.io/package-name":              "my-package",
 			"olm.operatorframework.io/service-account-name":      "test-sa",
@@ -129,6 +131,7 @@ func Test_SimpleRevisionGenerator_GenerateRevisionFromHelmRelease(t *testing.T)
 											"my-label": "my-value",
 										},
 										"annotations": map[string]interface{}{
+											"olm.operatorframework.io/bundle-release": "3",
 											"olm.operatorframework.io/bundle-version": "1.2.0",
 											"olm.operatorframework.io/package-name":   "my-package",
 										},
@@ -145,6 +148,7 @@ func Test_SimpleRevisionGenerator_GenerateRevisionFromHelmRelease(t *testing.T)
 											"my-label": "my-value",
 										},
 										"annotations": map[string]interface{}{
+											"olm.operatorframework.io/bundle-release": "3",
 											"olm.operatorframework.io/bundle-version": "1.2.0",
 											"olm.operatorframework.io/package-name":   "my-package",
 										},
@@ -210,6 +214,7 @@ func Test_SimpleRevisionGenerator_GenerateRevision(t *testing.T) {
 	rev, err := b.GenerateRevision(t.Context(), dummyBundle, ext, map[string]string{}, map[string]string{
 		labels.BundleVersionKey: "1.0.0",
 		labels.PackageNameKey:   "test-package",
+		labels.BundleReleaseKey: "5",
 	})
 	require.NoError(t, err)
 
@@ -235,6 +240,7 @@ func Test_SimpleRevisionGenerator_GenerateRevision(t *testing.T) {
 							"metadata": map[string]interface{}{
 								"name": "test-service",
 								"annotations": map[string]interface{}{
+									"olm.operatorframework.io/bundle-release": "5",
 									"olm.operatorframework.io/bundle-version": "1.0.0",
 									"olm.operatorframework.io/package-name":   "test-package",
 								},
@@ -259,6 +265,7 @@ func Test_SimpleRevisionGenerator_GenerateRevision(t *testing.T) {
 								},
 								"annotations": map[string]interface{}{
 									"my-annotation": "my-annotation-value",
+									"olm.operatorframework.io/bundle-release": "5",
 									"olm.operatorframework.io/bundle-version": "1.0.0",
 									"olm.operatorframework.io/package-name":   "test-package",
 								},

internal/operator-controller/bundle/versionrelease.go

@@ -85,6 +85,19 @@ func (vr *VersionRelease) AsLegacyRegistryV1Version() bsemver.Version {
 
 type Release []bsemver.PRVersion
 
+// String returns the dot-separated string representation of the release segments.
+// Returns an empty string for an empty release.
+func (r Release) String() string {
+	if len(r) == 0 {
+		return ""
+	}
+	segments := make([]string, len(r))
+	for i, seg := range r {
+		segments[i] = seg.String()
+	}
+	return strings.Join(segments, ".")
+}
+
 // Compare compares two Release values. It returns:
 //
 //	-1 if r < other

internal/operator-controller/bundle/versionrelease_test.go

@@ -346,6 +346,47 @@ func TestNewRelease(t *testing.T) {
 	}
 }
 
+func TestRelease_String(t *testing.T) {
+	type testCase struct {
+		name   string
+		input  string
+		expect string
+	}
+	for _, tc := range []testCase{
+		{
+			name:   "empty release",
+			input:  "",
+			expect: "",
+		},
+		{
+			name:   "single numeric segment",
+			input:  "1",
+			expect: "1",
+		},
+		{
+			name:   "single alphanumeric segment",
+			input:  "alpha",
+			expect: "alpha",
+		},
+		{
+			name:   "multiple numeric segments",
+			input:  "4.5",
+			expect: "4.5",
+		},
+		{
+			name:   "mixed segments",
+			input:  "9.alpha.10",
+			expect: "9.alpha.10",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			rel, err := bundle.NewRelease(tc.input)
+			require.NoError(t, err)
+			assert.Equal(t, tc.expect, rel.String())
+		})
+	}
+}
+
 func TestRelease_Compare(t *testing.T) {
 	type testCase struct {
 		name   string

internal/operator-controller/controllers/boxcutter_reconcile_steps.go

@@ -64,6 +64,7 @@ func (d *BoxcutterRevisionStatesGetter) GetRevisionStates(ctx context.Context, e
 		rm := &RevisionMetadata{
 			RevisionName: rev.Name,
 			Package:      rev.Annotations[labels.PackageNameKey],
+			Release:      rev.Annotations[labels.BundleReleaseKey],
 			Image:        rev.Annotations[labels.BundleReferenceKey],
 			Conditions:   rev.Status.Conditions,
 			BundleMetadata: ocv1.BundleMetadata{
@@ -105,6 +106,9 @@ func ApplyBundleWithBoxcutter(apply func(ctx context.Context, contentFS fs.FS, e
 			labels.BundleVersionKey:   state.resolvedRevisionMetadata.Version,
 			labels.BundleReferenceKey: state.resolvedRevisionMetadata.Image,
 		}
+		if state.resolvedRevisionMetadata.Release != "" {
+			revisionAnnotations[labels.BundleReleaseKey] = state.resolvedRevisionMetadata.Release
+		}
 		objLbls := map[string]string{
 			labels.OwnerKindKey: ocv1.ClusterExtensionKind,
 			labels.OwnerNameKey: ext.GetName(),

internal/operator-controller/controllers/clusterextension_controller.go

@@ -499,6 +499,7 @@ func clusterExtensionRequestsForCatalog(c client.Reader, logger logr.Logger) crh
 type RevisionMetadata struct {
 	RevisionName string
 	Package      string
+	Release      string
 	Image        string
 	ocv1.BundleMetadata
 	Conditions []metav1.Condition

internal/operator-controller/controllers/clusterextension_reconcile_steps.go

@@ -188,6 +188,7 @@ func ResolveBundle(r resolve.Resolver, c client.Client) ReconcileStepFunc {
 
 		state.resolvedRevisionMetadata = &RevisionMetadata{
 			Package: resolvedBundle.Package,
+			Release: resolvedBundleVersion.Release.String(),
 			Image:   resolvedBundle.Image,
 			// TODO: Right now, operator-controller only supports registry+v1 bundles and has no concept
 			//   of a "release" field. If/when we add a release field concept or a new bundle format

internal/operator-controller/labels/labels.go

@@ -21,6 +21,11 @@ const (
 	// associated with a ClusterExtensionRevision.
 	BundleVersionKey = "olm.operatorframework.io/bundle-version"
 
+	// BundleReleaseKey is the annotation key used to record the release
+	// portion of the bundle version, when present. This is the release
+	// metadata extracted from the version's build metadata field.
+	BundleReleaseKey = "olm.operatorframework.io/bundle-release"
+
 	// BundleReferenceKey is the label key used to record an external reference
 	// (such as an image or catalog reference) to the bundle for a
 	// ClusterExtensionRevision.

test/e2e/features/install.feature

@@ -448,6 +448,81 @@ Feature: Install ClusterExtension
       """
     And ClusterExtension reports Progressing transition between 1 and 2 minutes since its creation
 
+  @BoxcutterRuntime
+  Scenario: Install bundle without release metadata does not include bundle-release annotation
+    When ClusterExtension is applied
+      """
+      apiVersion: olm.operatorframework.io/v1
+      kind: ClusterExtension
+      metadata:
+        name: ${NAME}
+      spec:
+        namespace: ${TEST_NAMESPACE}
+        serviceAccount:
+          name: olm-sa
+        source:
+          sourceType: Catalog
+          catalog:
+            packageName: test
+            version: 1.0.0
+            selector:
+              matchLabels:
+                "olm.operatorframework.io/metadata.name": test-catalog
+      """
+    Then ClusterExtension is rolled out
+    And ClusterExtension is available
+    And ClusterExtensionRevision "${NAME}-1" contains annotation "olm.operatorframework.io/bundle-version" with value
+      """
+      1.0.0
+      """
+    And ClusterExtensionRevision "${NAME}-1" contains annotation "olm.operatorframework.io/package-name" with value
+      """
+      test
+      """
+    And ClusterExtensionRevision "${NAME}-1" does not contain annotation "olm.operatorframework.io/bundle-release"
+    And resource "configmap/test-configmap" has annotations
+      | key                                          | value |
+      | olm.operatorframework.io/bundle-version      | 1.0.0 |
+      | olm.operatorframework.io/package-name        | test  |
+    And resource "configmap/test-configmap" does not have annotation "olm.operatorframework.io/bundle-release"
+
+  @BoxcutterRuntime
+  Scenario: Install bundle with release metadata includes bundle-release annotation
+    When ClusterExtension is applied
+      """
+      apiVersion: olm.operatorframework.io/v1
+      kind: ClusterExtension
+      metadata:
+        name: ${NAME}
+      spec:
+        namespace: ${TEST_NAMESPACE}
+        serviceAccount:
+          name: olm-sa
+        source:
+          sourceType: Catalog
+          catalog:
+            packageName: test
+            version: 1.0.5
+            selector:
+              matchLabels:
+                "olm.operatorframework.io/metadata.name": test-catalog
+      """
+    Then ClusterExtension is rolled out
+    And ClusterExtension is available
+    And ClusterExtensionRevision "${NAME}-1" contains annotation "olm.operatorframework.io/bundle-version" with value
+      """
+      1.0.5+1
+      """
+    And ClusterExtensionRevision "${NAME}-1" contains annotation "olm.operatorframework.io/bundle-release" with value
+      """
+      1
+      """
+    And resource "configmap/test-configmap" has annotations
+      | key                                          | value   |
+      | olm.operatorframework.io/bundle-version      | 1.0.5+1 |
+      | olm.operatorframework.io/bundle-release      | 1       |
+      | olm.operatorframework.io/package-name        | test    |
+
   @BoxcutterRuntime
   Scenario:  ClusterExtensionRevision is annotated with bundle properties
     When ClusterExtension is applied

test/e2e/steps/steps.go

@@ -94,6 +94,8 @@ func RegisterSteps(sc *godog.ScenarioContext) {
 	sc.Step(`^(?i)ClusterExtensionRevision "([^"]+)" is archived$`, ClusterExtensionRevisionIsArchived)
 	sc.Step(`^(?i)ClusterExtensionRevision "([^"]+)" contains annotation "([^"]+)" with value$`, ClusterExtensionRevisionHasAnnotationWithValue)
 	sc.Step(`^(?i)ClusterExtensionRevision "([^"]+)" has label "([^"]+)" with value "([^"]+)"$`, ClusterExtensionRevisionHasLabelWithValue)
+	sc.Step(`^(?i)ClusterExtensionRevision "([^"]+)" does not contain annotation "([^"]+)"$`, ClusterExtensionRevisionDoesNotHaveAnnotation)
+	sc.Step(`^(?i)resource "([^"]+)" does not have annotation "([^"]+)"$`, ResourceDoesNotHaveAnnotation)
 	sc.Step(`^(?i)ClusterExtensionRevision "([^"]+)" phase objects are not found or not owned by the revision$`, ClusterExtensionRevisionObjectsNotFoundOrNotOwned)
 
 	sc.Step(`^(?i)resource "([^"]+)" is installed$`, ResourceAvailable)
@@ -611,6 +613,49 @@ func ClusterExtensionRevisionHasLabelWithValue(ctx context.Context, revisionName
 	return nil
 }
 
+// ClusterExtensionRevisionDoesNotHaveAnnotation waits for the named ClusterExtensionRevision to exist
+// and then asserts that it does NOT have the specified annotation key. Polls with timeout.
+func ClusterExtensionRevisionDoesNotHaveAnnotation(ctx context.Context, revisionName, annotationKey string) error {
+	sc := scenarioCtx(ctx)
+	revisionName = substituteScenarioVars(strings.TrimSpace(revisionName), sc)
+	waitFor(ctx, func() bool {
+		obj, err := getResource("clusterextensionrevision", revisionName, "")
+		if err != nil {
+			logger.V(1).Error(err, "failed to get clusterextensionrevision", "name", revisionName)
+			return false
+		}
+		_, found := obj.GetAnnotations()[annotationKey]
+		return !found
+	})
+	return nil
+}
+
+// ResourceDoesNotHaveAnnotation waits for a namespaced resource to exist and then asserts
+// that it does NOT have the specified annotation key. Polls with timeout.
+func ResourceDoesNotHaveAnnotation(ctx context.Context, resourceName, annotationKey string) error {
+	sc := scenarioCtx(ctx)
+	resourceName = substituteScenarioVars(resourceName, sc)
+
+	kind, name, ok := strings.Cut(resourceName, "/")
+	if !ok {
+		return fmt.Errorf("invalid resource name format: %q (expected kind/name)", resourceName)
+	}
+
+	waitFor(ctx, func() bool {
+		out, err := k8sClient("get", kind, name, "-n", sc.namespace, "-o", "json")
+		if err != nil {
+			return false
+		}
+		var obj unstructured.Unstructured
+		if err := json.Unmarshal([]byte(out), &obj); err != nil {
+			return false
+		}
+		_, found := obj.GetAnnotations()[annotationKey]
+		return !found
+	})
+	return nil
+}
+
 // ClusterExtensionRevisionObjectsNotFoundOrNotOwned waits for all objects described in the named
 // ClusterExtensionRevision's phases to either not exist on the cluster or not contain the revision
 // in their ownerReferences. Polls with timeout.