[WIP]OSDOCS-18911 OLMv1 ClusterObjectSets

extensions/arch/operator-controller.adoc

@@ -20,3 +20,5 @@ include::modules/olmv1-clusterextension-api.adoc[leveloffset=+1]
 include::modules/olmv1-about-target-versions.adoc[leveloffset=+2]
 
 include::modules/olmv1-object-ownership.adoc[leveloffset=+1]
+
+include::modules/olmv1-clusterobjectsets.adoc[leveloffset=+1]

modules/olmv1-clusterobjectsets.adoc

@@ -0,0 +1,50 @@
+// Module is included in the following assemblies:
+//
+// * openshift-docs/exxtensions/arch/operator-controller.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="olmv1-clusterobjectsets_{context}"]
+= ClusterObjectSets
+
+:FeatureName: ClusterObjectSets
+include::snippets/technology-preview.adoc[]
+
+[role="_abstract"]
+As part of  {olmv1-first}, a new internal ClusterObjectSet API is available that assists OLM transition between upgrades of the Operator. The operator-controller uses ClusterObjectSets as the mechanism to deploy and upgrade ClusterExtensions. ClusterObjectSets enable safe, phased rollouts of Kubernetes resources. 
+
+A ClusterObjectSet is a cluster-scoped Kubernetes API that represents a versioned set of resources organized into ordered phases. 
+It rolls out related resources sequentially with built-in readiness checks between phases. 
+
+ClusterObjectSets solve several problems when managing sets of related Kubernetes resources: 
+
+Immutable revision content:: The revision number, phases, objects, and collision protection strategy are immutable, that is, they cannot change once set. This provides a clear audit trail of what was deployed at each revision.  
+
+Phased rollout:: Resources are grouped into phases (CRDs before Deployments) and are deployed sequentially. A phase only progresses after all its objects pass readiness probes. Manifests are organized into phases, applied to the cluster, and must pass some status probes before they progress to the next phase.
+
+Safe transitions:: During upgrades, both old and new revisions remain active until the new revision succeeds. Object ownership transitions between revisions automatically.          
+
+Single ownership:: Each resource can only be managed by one ClusterObjectSet at a time, preventing conflicts.                                                                
+
+Large resource support:: Object manifests can be stored inline or externalized into Secrets, allowing bundles larger than the etcd 1.5 MiB object size limit. 
+
+[NOTE]
+====
+Existing ClusterObjectSets associated with the ClusterExtension are archived. This provides an historical footprint of the changes applied to the cluster as part of the Operator. 
+====
+
+Each ClusterObjectSet contains the following content:
+
+A revision number:: A permanent, sequential integer that identifies the version.
+
+A lifecycle state:: Either `Active` (being reconciled) or `Archived` (inactive). The  lifecycle state transitions from `Active` to `Archived` but not back.
+
+A list of phases:: Objects within a ClusterObjectSet are organized into phases. Each phase groups related resources, and phases are applied sequentially. Within a phase, all objects are applied simultaneously in no particular order.
+
+A collision protection strategy:: Controls whether a ClusterObjectSet can adopt pre-existing objects on the cluster. 
+
+Status conditions:: Indicates whether the revision is actively rolling out and reports rollout progress, availability, and success.
+
+Additionally, support for management of large object bundles created by ClusterObjectSet is provided. ClusterObjectSets embed Kubernetes manifests in `.spec.phases[].objects[].object`. With up to 20 phases and 50 objects per phase, they can exceed the etcd 1.5 MiB object size limit. Large Operators with many CRDs, Deployments, RBAC rules, and webhook configurations frequently hit this limit, causing the API server to reject the ClusterObjectSet and fail installation or upgrade.           
+
+To solve this, objects can be externalized using per-object content references. The phases data is immutable and only consumed by the revision reconciler, making it suitable for externalization.
+