Ensure COS phase immutability for referenced object approach

ClusterObjectSet phases are immutable by design, but when objects are
stored in external Secrets via refs, the Secret content could be changed
by deleting and recreating the Secret with the same name. This enforces
phase immutability for the referenced object approach by verifying that
referenced Secrets are marked immutable and that their content hashes
have not changed since first resolution.

On first successful reconciliation, SHA-256 hashes of referenced Secret
data are recorded in .status.observedObjectContainers. On subsequent
reconciles, the hashes are compared and reconciliation is blocked with
Progressing=False/Reason=Blocked if any mismatch is detected.

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

Author: pedjak

api/v1/clusterobjectset_types.go

@@ -510,6 +510,30 @@ type ClusterObjectSetStatus struct {
 	// +listMapKey=type
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
+
+	// observedObjectContainers records the content hashes of referenced Secrets
+	// at first successful resolution. This is used to detect if a referenced
+	// Secret was deleted and recreated with different content.
+	//
+	// +listType=map
+	// +listMapKey=name
+	// +optional
+	ObservedObjectContainers []ObservedObjectContainer `json:"observedObjectContainers,omitempty"`
+}
+
+// ObservedObjectContainer records the observed state of a referenced Secret
+// used as an object source.
+type ObservedObjectContainer struct {
+	// name identifies the referenced Secret in "namespace/name" format.
+	//
+	// +required
+	Name string `json:"name"`
+
+	// hash is the hex-encoded SHA-256 hash of the Secret's .data field
+	// at first successful resolution.
+	//
+	// +required
+	Hash string `json:"hash"`
 }
 
 // +genclient

api/v1/zz_generated.deepcopy.go

@@ -142,14 +142,18 @@ Recommended conventions:
 1. **Secret type**: Secrets should use the dedicated type
    `olm.operatorframework.io/object-data` to distinguish them from user-created
    Secrets and enable easy identification. The system always sets this type on
-   Secrets it creates. The reconciler does not enforce the type when resolving
-   refs — Secrets with any type are accepted — but producers should set it for
-   consistency.
-
-2. **Immutability**: Secrets should set `immutable: true`. Because COS phases
-   are immutable, the content backing a ref should not change after creation.
-   Mutable referenced Secrets are not rejected, but modifying them after the
-   COS is created leads to undefined behavior.
+   Secrets it creates. The reconciler does not enforce the Secret type when
+   resolving refs, but it does enforce that referenced Secrets have
+   `immutable: true` set and that their content has not changed since first
+   resolution.
+
+2. **Immutability**: Secrets must set `immutable: true`. The reconciler verifies
+   that all referenced Secrets have `immutable: true` set before proceeding.
+   Mutable referenced Secrets are rejected and reconciliation is blocked with
+   `Progressing=False, Reason=Blocked`. Additionally, the reconciler records
+   content hashes of referenced Secrets on first resolution and blocks
+   reconciliation if the content changes (e.g., if a Secret is deleted and
+   recreated with the same name but different data).
 
 3. **Owner references**: Referenced Secrets should carry an ownerReference to
    the COS so that Kubernetes garbage collection removes them when the COS is
@@ -388,6 +392,13 @@ Key properties:
 
 ### COS reconciler behavior
 
+Before resolving individual object refs, the reconciler verifies all referenced
+Secrets: each must have `immutable: true` set, and its content hash must match
+the hash recorded in `.status.observedObjectContainers` (if present). If any Secret
+fails verification, reconciliation is blocked with `Progressing=False,
+Reason=Blocked`. On first successful verification, content hashes are persisted
+to status for future comparisons.
+
 When processing a COS phase:
 - For each object entry in the phase:
   - If `object` is set, use it directly (current behavior, unchanged).

applyconfigurations/api/v1/clusterobjectsetstatus.go

@@ -621,6 +621,33 @@ spec:
                 x-kubernetes-list-map-keys:
                 - type
                 x-kubernetes-list-type: map
+              observedObjectContainers:
+                description: |-
+                  observedObjectContainers records the content hashes of referenced Secrets
+                  at first successful resolution. This is used to detect if a referenced
+                  Secret was deleted and recreated with different content.
+                items:
+                  description: |-
+                    ObservedObjectContainer records the observed state of a referenced Secret
+                    used as an object source.
+                  properties:
+                    hash:
+                      description: |-
+                        hash is the hex-encoded SHA-256 hash of the Secret's .data field
+                        at first successful resolution.
+                      type: string
+                    name:
+                      description: name identifies the referenced Secret in "namespace/name"
+                        format.
+                      type: string
+                  required:
+                  - hash
+                  - name
+                  type: object
+                type: array
+                x-kubernetes-list-map-keys:
+                - name
+                x-kubernetes-list-type: map
             type: object
         type: object
     served: true