Add user guide documentation to perform upgrade

docs/upgrade.md

@@ -0,0 +1,93 @@
+## Example upgrade from 4.16.x to 4.16.y
+### starting conditions:
+- A compatible seed image with target cluster is created. Seed image has `4.16.y` ocp version. [Both target cluster and seed image has configured a shared container partition for IBU.](https://docs.openshift.com/container-platform/4.17/edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/cnf-image-based-upgrade-shared-container-partition.html)
+- spoke cluster is successfully deployed and configured using a `ProvisioningRequest`:  
+```bash
+$ oc get provisioningrequests.o2ims.provisioning.oran.org        
+NAME      AGE   PROVISIONSTATE   PROVISIONDETAILS
+cluster-name   37m   fulfilled        Provisioning request has completed successfully
+```
+- [OADP and LCA is installed on the spoke cluster. OADP backend is configured on the spoke cluster.](https://docs.openshift.com/container-platform/4.17/edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/cnf-image-based-upgrade-install-operators.html)
+```yaml
+# policytemplates/version_4.16.x/sno-ran-du/sno-ran-du-pg-v4-16-x-v1.yaml
+
+policies:
+- name: operator-subscriptions
+  manifests:
+    # LCA
+    - path: source-crs/LcaOperatorStatus.yaml
+    - path: source-crs/LcaSubscriptionNS.yaml
+    - path: source-crs/LcaSubscriptionOperGroup.yaml
+    - path: source-crs/LcaSubscription.yaml
+    # OADP
+    - path: source-crs/OadpOperatorStatus.yaml
+    - path: source-crs/OadpSubscriptionNS.yaml
+    - path: source-crs/OadpSubscriptionOperGroup.yaml
+    - path: source-crs/OadpSubscription.yaml
+- name: oadp-backend
+  manifests:
+    - path: source-crs/OadpSecret.yaml
+      patches:
+        - data: <FILL>
+    - path: source-crs/OadpDataProtectionApplication.yaml
+      patches:
+        - spec:
+            backupLocations:
+            <FILL>
+```
+### steps:
+- create new clustertemplates and policytemplates directories for the new release according to sample git-setup.
+- update release version in new clustertemplates files
+```yaml
+# clustertemplates/version_4.16.y/sno-ran-du/clusterinstance-defaults-v1.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: clusterinstance-defaults-v1
+  namespace: sno-ran-du-v4-16-y
+data:
+  clusterinstance-defaults: |
+    clusterImageSetNameRef: "4.16.y"
+---
+# clustertemplates/version_4.16.y/sno-ran-du/sno-ran-du-v4-16-y-1.yaml
+kind: ClusterTemplate
+metadata:
+  name: sno-ran-du.v4-16-y-1
+  namespace: sno-ran-du-v4-16-y
+spec:
+  name: sno-ran-du
+  version: v4-16-y-1
+  release: 4.16.y
+---
+# clustertemplates/version_4.16.y/sno-ran-du/upgrade-defaults-v1.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: upgrade-defaults-v1
+  namespace: sno-ran-du-v4-16-y
+data:
+  ibgu: |
+    ibuSpec:
+      seedImageRef:
+        image: "quay.io/seed-repo/seed-image:4.16.y"
+        version: "4.16.y"
+      oadpContent:
+        - name: sno-ran-du-ibu-platform-backup-v4-16-y-1
+          namespace: openshift-adp
+```
+- sync ztp repo to the hub cluster.
+- patch `ProvisioningRequest.spec.templateName` and `ProvisioningRequest.spec.templateVersion` to point to the new `ClusterTemplate`. This will trigger the image based upgrade.
+- wait for upgrade to be completed.
+```yaml
+  status:                     
+    conditions: 
+      message: Upgrade is completed                
+      reason: Completed
+      status: "True"      
+      type: UpgradeCompleted    
+  provisioningStatus:
+      provisionedResources:
+      provisioningDetails: Provisioning request has completed successfully
+      provisioningState: fulfilled
+
+```

go.mod

@@ -23,6 +23,7 @@ require (
 	github.com/onsi/ginkgo/v2 v2.19.0
 	github.com/onsi/gomega v1.33.1
 	github.com/openshift-kni/cluster-group-upgrades-operator v0.0.0-20241015193426-dd5c5bc228e8
+	github.com/openshift-kni/lifecycle-agent v0.0.0-20241010194013-9d0e25438512
 	github.com/openshift-kni/oran-o2ims/api/hardwaremanagement v0.0.0-20241001130125-a052f08603f7
 	github.com/openshift-kni/oran-o2ims/api/inventory v0.0.0-00010101000000-000000000000
 	github.com/openshift-kni/oran-o2ims/api/provisioning v0.0.0-00010101000000-000000000000
@@ -94,7 +95,6 @@ require (
 	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/oklog/ulid v1.3.1 // indirect
-	github.com/openshift-kni/lifecycle-agent v0.0.0-20241010194013-9d0e25438512 // indirect
 	github.com/openshift/assisted-service/models v0.0.0 // indirect
 	github.com/openshift/custom-resource-status v1.1.3-0.20220503160415-f2fdb4999d87 // indirect
 	github.com/openshift/hive/apis v0.0.0-20240306163002-9c5806a63531 // indirect

internal/controllers/clustertemplate_controller.go

@@ -263,6 +263,7 @@ func (t *clusterTemplateReconcilerTask) validateClusterTemplateCR(ctx context.Co
 func validateUpgradeDefaultsConfigmap(
 	ctx context.Context, c client.Client, name, namespace, key string,
 ) error {
+
 	ibgu, err := utils.GetIBGUFromUpgradeDefaultsConfigmap(ctx, c, name, namespace, key, "name", "name", namespace)
 	if err != nil {
 		return fmt.Errorf("failed to get IBGU from upgrade defaults configmap: %w", err)
@@ -276,6 +277,23 @@ func validateUpgradeDefaultsConfigmap(
 		}
 		return utils.NewInputError(err.Error())
 	}
+	existingConfigmap, err := utils.GetConfigmap(ctx, c, name, namespace)
+	if err != nil {
+		return fmt.Errorf("failed to get ConfigmapReference: %w", err)
+	}
+	// Check if the configmap is set to mutable
+	if existingConfigmap.Immutable != nil && !*existingConfigmap.Immutable {
+		return utils.NewInputError("It is not allowed to set Immutable to false in the ConfigMap %s", name)
+	} else if existingConfigmap.Immutable == nil {
+		// Patch the validated ConfigMap to make it immutable if not already set
+		immutable := true
+		newConfigmap := existingConfigmap.DeepCopy()
+		newConfigmap.Immutable = &immutable
+
+		if err := utils.CreateK8sCR(ctx, c, newConfigmap, nil, utils.PATCH); err != nil {
+			return fmt.Errorf("failed to patch ConfigMap as immutable: %w", err)
+		}
+	}
 	return nil
 }
 

internal/controllers/provisioningrequest_clusterinstall.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"log/slog"
+	"slices"
 	"strings"
 
 	"k8s.io/apimachinery/pkg/api/equality"
@@ -81,14 +82,24 @@ func (t *provisioningRequestReconcilerTask) renderClusterInstanceTemplate(
 						"failed to find immutable field updates for ClusterInstance (%s): %w", ciName, err)
 				}
 
-				var disallowedChanges []string
+				// copy the existing suppressedManifests
+				existingCI := &siteconfig.ClusterInstance{}
+				err = runtime.DefaultUnstructuredConverter.FromUnstructured(existingClusterInstance.Object, existingCI)
+				if err != nil {
+					return nil, fmt.Errorf("failed to get current suppressedManifests values: %w", err)
+				}
+				suppressedManifests = existingCI.Spec.SuppressedManifests
 
+				var disallowedChanges []string
 				for _, updatedField := range updatedFields {
-					// Add "AgentClusterInstall" to ClusterInstance.SuppressedManifests in order to
-					// prevent unnecessary updates to ACI.
+					// Suppress install manifests to prevent unnecessary updates
 					if updatedField == "clusterImageSetNameRef" &&
 						crProvisionedCond.Reason == string(utils.CRconditionReasons.Completed) {
-						suppressedManifests = append(suppressedManifests, "AgentClusterInstall")
+						for _, crd := range utils.CRDsToBeSuppressedForUpgrade {
+							if !slices.Contains(suppressedManifests, crd) {
+								suppressedManifests = append(suppressedManifests, crd)
+							}
+						}
 					} else {
 						disallowedChanges = append(disallowedChanges, updatedField)
 					}