🌱 Externalize CER phase objects into Secrets (#2595)

* Externalize CER phase objects into Secret refs

Add support for storing ClusterExtensionRevision phase objects in
content-addressable immutable Secrets instead of inline in the CER spec.
This removes the etcd object size limit as a constraint on bundle size.

API changes:
- Add ObjectSourceRef type with name, namespace, and key fields
- Make ClusterExtensionRevisionObject.Object optional (omitzero)
- Add optional Ref field with XValidation ensuring exactly one is set
- Add RefResolutionFailed condition reason
- Add RevisionNameKey label for ref Secret association

Applier (boxcutter.go):
- Add SecretPacker to bin-pack serialized objects into Secrets with
  gzip compression for objects exceeding 800KiB
- Add createExternalizedRevision with crash-safe three-step sequence:
  create Secrets, create CER with refs, patch ownerReferences
- Externalize desiredRevision before SSA comparison so the patch
  compares refs-vs-refs instead of inline-vs-refs
- Add ensureSecretOwnerReferences for crash recovery
- Pass SystemNamespace to Boxcutter from main.go

CER controller:
- Add resolveObjectRef to fetch and decompress objects from Secrets
- Handle ref resolution in buildBoxcutterPhases
- Add RBAC for Secret get/list/watch

E2e tests:
- Add scenario verifying refs, immutability, labels, and ownerRefs
- Add step definitions for ref Secret validation
- Fix listExtensionRevisionResources and
  ClusterExtensionRevisionObjectsNotFoundOrNotOwned to resolve refs

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

* Address PR #2595 review feedback

- Fix duplicate key size inflation in SecretPacker by only incrementing
  size for new content hash keys
- Add io.LimitReader (10 MiB cap) for gzip decompression to prevent
  gzip bombs in controller and e2e helpers
- Add doc comment clarifying ObjectSourceRef.Namespace defaults to OLM
  system namespace during ref resolution
- Fix docs: orphan cleanup uses ownerReference GC, ref resolution
  failures are retried (not terminal)
- Remove unused ClusterExtensionRevisionReasonRefResolutionFailed constant
- Add default error branch in e2e listExtensionRevisionResources for
  objects missing both ref and inline content

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

* Change gzipThreshold from 800 KiB to 900 KiB

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

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: pedjak

api/v1/clusterextensionrevision_types.go

@@ -392,14 +392,29 @@ type ClusterExtensionRevisionPhase struct {
 
 // ClusterExtensionRevisionObject represents a Kubernetes object to be applied as part
 // of a phase, along with its collision protection settings.
+//
+// Exactly one of object or ref must be set.
+//
+// +kubebuilder:validation:XValidation:rule="has(self.object) != has(self.ref)",message="exactly one of object or ref must be set"
 type ClusterExtensionRevisionObject struct {
-	// object is a required embedded Kubernetes object to be applied.
+	// object is an optional embedded Kubernetes object to be applied.
+	//
+	// Exactly one of object or ref must be set.
 	//
 	// This object must be a valid Kubernetes resource with apiVersion, kind, and metadata fields.
 	//
 	// +kubebuilder:validation:EmbeddedResource
 	// +kubebuilder:pruning:PreserveUnknownFields
-	Object unstructured.Unstructured `json:"object"`
+	// +optional
+	Object unstructured.Unstructured `json:"object,omitzero"`
+
+	// ref is an optional reference to a Secret that holds the serialized
+	// object manifest.
+	//
+	// Exactly one of object or ref must be set.
+	//
+	// +optional
+	Ref ObjectSourceRef `json:"ref,omitzero"`
 
 	// collisionProtection controls whether the operator can adopt and modify objects
 	// that already exist on the cluster.
@@ -425,6 +440,33 @@ type ClusterExtensionRevisionObject struct {
 	CollisionProtection CollisionProtection `json:"collisionProtection,omitempty"`
 }
 
+// ObjectSourceRef references content within a Secret that contains a
+// serialized object manifest.
+type ObjectSourceRef struct {
+	// name is the name of the referenced Secret.
+	//
+	// +required
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=253
+	Name string `json:"name"`
+
+	// namespace is the namespace of the referenced Secret.
+	// When empty, defaults to the OLM system namespace during ref resolution.
+	//
+	// +optional
+	// +kubebuilder:validation:MaxLength=63
+	Namespace string `json:"namespace,omitempty"`
+
+	// key is the data key within the referenced Secret containing the
+	// object manifest content. The value at this key must be a
+	// JSON-serialized Kubernetes object manifest.
+	//
+	// +required
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=253
+	Key string `json:"key"`
+}
+
 // CollisionProtection specifies if and how ownership collisions are prevented.
 type CollisionProtection string
 

api/v1/clusterextensionrevision_types_test.go

@@ -272,6 +272,77 @@ func TestClusterExtensionRevisionValidity(t *testing.T) {
 			},
 			valid: true,
 		},
+		"object with inline object is valid": {
+			spec: ClusterExtensionRevisionSpec{
+				LifecycleState:      ClusterExtensionRevisionLifecycleStateActive,
+				Revision:            1,
+				CollisionProtection: CollisionProtectionPrevent,
+				Phases: []ClusterExtensionRevisionPhase{
+					{
+						Name: "deploy",
+						Objects: []ClusterExtensionRevisionObject{
+							{
+								Object: configMap(),
+							},
+						},
+					},
+				},
+			},
+			valid: true,
+		},
+		"object with ref is valid": {
+			spec: ClusterExtensionRevisionSpec{
+				LifecycleState:      ClusterExtensionRevisionLifecycleStateActive,
+				Revision:            1,
+				CollisionProtection: CollisionProtectionPrevent,
+				Phases: []ClusterExtensionRevisionPhase{
+					{
+						Name: "deploy",
+						Objects: []ClusterExtensionRevisionObject{
+							{
+								Ref: ObjectSourceRef{Name: "my-secret", Key: "my-key"},
+							},
+						},
+					},
+				},
+			},
+			valid: true,
+		},
+		"object with both object and ref is invalid": {
+			spec: ClusterExtensionRevisionSpec{
+				LifecycleState:      ClusterExtensionRevisionLifecycleStateActive,
+				Revision:            1,
+				CollisionProtection: CollisionProtectionPrevent,
+				Phases: []ClusterExtensionRevisionPhase{
+					{
+						Name: "deploy",
+						Objects: []ClusterExtensionRevisionObject{
+							{
+								Object: configMap(),
+								Ref:    ObjectSourceRef{Name: "my-secret", Key: "my-key"},
+							},
+						},
+					},
+				},
+			},
+			valid: false,
+		},
+		"object with neither object nor ref is invalid": {
+			spec: ClusterExtensionRevisionSpec{
+				LifecycleState:      ClusterExtensionRevisionLifecycleStateActive,
+				Revision:            1,
+				CollisionProtection: CollisionProtectionPrevent,
+				Phases: []ClusterExtensionRevisionPhase{
+					{
+						Name: "deploy",
+						Objects: []ClusterExtensionRevisionObject{
+							{},
+						},
+					},
+				},
+			},
+			valid: false,
+		},
 	} {
 		t.Run(name, func(t *testing.T) {
 			cer := &ClusterExtensionRevision{

api/v1/zz_generated.deepcopy.go

@@ -634,6 +634,7 @@ func (c *boxcutterReconcilerConfigurator) Configure(ceReconciler *controllers.Cl
 		Preflights:        c.preflights,
 		PreAuthorizer:     preAuth,
 		FieldOwner:        fieldOwner,
+		SystemNamespace:   cfg.systemNamespace,
 	}
 	revisionStatesGetter := &controllers.BoxcutterRevisionStatesGetter{Reader: c.mgr.GetClient()}
 	storageMigrator := &applier.BoxcutterStorageMigrator{

applyconfigurations/api/v1/clusterextensionrevisionobject.go

@@ -475,6 +475,8 @@ _Appears in:_
 | `label` _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#labelselector-v1-meta)_ | label is the label selector definition.<br />Required when type is "Label".<br />A probe using a Label selector will be executed against every object matching the labels or expressions; you must use care<br />when using this type of selector. For example, if multiple Kind objects are selected via labels then the probe is<br />likely to fail because the values of different Kind objects rarely share the same schema.<br />The LabelSelector field uses the following Kubernetes format:<br />https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#LabelSelector<br />Requires exactly one of matchLabels or matchExpressions.<br /><opcon:experimental> |  | Optional: \{\} <br /> |
 
 
+
+
 #### PreflightConfig