Document scheduled ClusterVersion changes

docs/modules/ROOT/pages/references/architecture/upgrade_controller.adoc

@@ -164,6 +164,54 @@ If the controller can't unpause the upgrade within this time, the upgrade is mar
 The controller should expose Prometheus metrics indicating the current state of the upgrade and the controller itself.
 This allows us to monitor the controller and the upgrade process and create alerts.
 
+=== The controller should allow scheduling `ClusterVersion` changes [[scheduled-cluster-version-change]]
+
+To facilitate minor upgrades, the controller should allow scheduling `ClusterVersion` changes.
+This allows the release channel to be changed at a specific time before selecting a new version.
+
+[source,yaml]
+----
+apiVersion: managedupgrade.appuio.io/v1beta1 <1>
+kind: ClusterVersion
+metadata:
+  name: version
+spec:
+  template: <2>
+    spec:
+      channel: stable-4.14
+      clusterID: XXX
+  overlays: <3>
+    - from: "2024-07-12T00:00:00Z"
+      overlay:
+        spec:
+          channel: stable-4.15 <4>
+----
+<1> The extended CRD based on the `config.openshift.io/v1.ClusterVersion` object.
+<2> The base `ClusterVersion` object.
+<3> The overlays to apply at a specific time to the base `ClusterVersion` object.
+Overlays are sorted by the `from` field.
+The controller applies the newest overlay where `from` is in the past.
+Overlays don't accumulate.
+<4> The new channel to switch to.
+
+==== The controller should export metrics for the `ClusterVersion` object
+
+The controller should export metrics for the `ClusterVersion` object.
+This allows us to monitor the state of the `ClusterVersion` object and check when and if a change is applied.
+
+[source]
+----
+# HELP managedupgrade_cluster_version_info Information about the ClusterVersion object. Shows the currently applied version with respective overlays applied.
+# TYPE managedupgrade_cluster_version_info gauge
+managedupgrade_cluster_version_info{channel="stable-4.14",clusterID="XXX"} 1
+# HELP managedupgrade_cluster_version_base Information about the ClusterVersion object. Shows the base version without any overlays applied.
+# TYPE managedupgrade_cluster_version_base gauge
+managedupgrade_cluster_version_base{channel="stable-4.14",clusterID="XXX"} 1
+# HELP managedupgrade_cluster_version_overlay_timestamp_seconds Information about the ClusterVersion object. All configured overlays for the ClusterVersion object. Contains the same labels as managedupgrade_cluster_version_info, empty if unset. The value is the timestamp in the from field.
+# TYPE managedupgrade_cluster_version_overlay_timestamp_seconds gauge
+managedupgrade_cluster_version_overlay_timestamp_seconds{index="0",channel="stable-4.15"} 1720742400
+----
+
 === When's an upgrade job considered successful? [[upgrade-success]]
 
 The controller monitors the `ClusterVersion/version` for the `Available` condition.
@@ -193,9 +241,17 @@ spec:
       clusterID: bc75be34-e92d-4745-bb9d-8ec39e877854
       desiredUpdate: {} <2>
       upstream: https://api.openshift.com/api/upgrades_info/v1/graph
+  overlays: <3>
+    - from: "2024-07-12T00:00:00Z"
+      overlay:
+        spec:
+          template:
+            spec:
+              channel: stable-4.15 <4>
 ----
-<1> Template for the `ClusterVersion/version` object.
+<1> Template for the `config.openshift.io/v1.ClusterVersion` object.
 <2> The `desiredUpdate` is ignored and set by the `UpgradeJob` controller.
+<3> Overlays to apply at a specific time. See <<scheduled-cluster-version-change>>.
 
 === UpgradeConfig [[upgrade-config]]