openshift · slovern · Sep 30, 2025 · Jul 29, 2025
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -3458,6 +3458,8 @@ Topics:
   File: ztp-deploying-far-edge-sites
 - Name: Manually installing a single-node OpenShift cluster with GitOps ZTP
   File: ztp-manual-install
+- Name: Migrating from SiteConfig CRs to ClusterInstance CRs
+  File: ztp-migrate-clusterinstance
 - Name: Recommended single-node OpenShift cluster configuration for vDU application workloads
   File: ztp-reference-cluster-configuration-for-vdu
 - Name: Validating cluster tuning for vDU application workloads

diff --git a/edge_computing/ztp-migrate-clusterinstance.adoc b/edge_computing/ztp-migrate-clusterinstance.adoc
@@ -0,0 +1,39 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ztp-migrate-clusterinstance"]
+= Migrating from SiteConfig CRs to ClusterInstance CRs
+include::_attributes/common-attributes.adoc[]
+:context: ztp-migrate-clusterinstance
+
+toc::[]
+
+You can incrementally migrate {sno} clusters from `SiteConfig` custom resources (CRs) to `ClusterInstance` CRs. During migration, the existing and new pipelines run in parallel, so you can migrate one or more clusters at a time in a controlled and phased manner.
+
+[IMPORTANT]
+====
+* The `SiteConfig` CR is deprecated from {product-title} version 4.18 and will be removed in a future version.
+
+* The `ClusterInstance` CR is available from {rh-rhacm-first} version 2.12 or later.
+====
+
+include::modules/ztp-migrate-clusterinstance-overview.adoc[leveloffset=+1]
+
+include::modules/ztp-creating-argocd-clusterinstance.adoc[leveloffset=+1]
+
+include::modules/ztp-active-ocp-version.adoc[leveloffset=+1]
+
+include::modules/ztp-migrating-sno-clusterinstnce.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.12/html/multicluster_engine_operator_with_red_hat_advanced_cluster_management/siteconfig-intro#enable[Enabling the SiteConfig operator]
+
+//include::modules/ztp-clusterinstance-site-converter.adoc[leveloffset=+1]
+
+include::modules/ztp-site-converter-ref.adoc[leveloffset=+2]
+
+include::modules/ztp-clusterinstance-cleanup.adoc[leveloffset=+1]
+
+//include::modules/ztp-enable-siteconfig-addon.adoc[leveloffset=+1]
+
+include::modules/ztp-clusterinstance-troubleshooting.adoc[leveloffset=+1]
diff --git a/modules/ztp-active-ocp-version.adoc b/modules/ztp-active-ocp-version.adoc
@@ -0,0 +1,77 @@
+// Module included in the following assemblies:
+//
+// * edge_computing/ztp-migrate-clusterinstance.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ztp-active-ocp-version_{context}"]
+= Transitioning the active-ocp-version ClusterImageSet
+
+Optionally, the `active-ocp-version` `ClusterImageSet` is a {ztp-first} convention used in {ztp} deployments.
+It provides a single, central definition of the {product-title} release image to use when provisioning clusters.  
+By default, this resource is synchronized to the hub cluster from the `site-config/resources/` folder.
+
+If your deployment uses an `active-ocp-version` `ClusterImageSet` CR, you must migrate it to the `resources/` folder in the new directroy that contains `ClusterInstance` CRs.  
+This prevents synchronization conflicts because both Argo CD applications cannot manage the same resource.
+
+.Prerequisites
+
+* You have completed the procedure to create the parallel Argo CD pipeline for `ClusterInstance` CRs.
+* The Argo CD application points to the folder in your Git repository that will contain the new `ClusterInstance` CRs and associated cluster resouces. In this example, the `site-configs-v2/` Argo CD application points to the `site-configs-v2/` folder.  
+* Your Git repository contains an `active-ocp-version.yaml` manifest in the `resources/` folder.
+
+.Procedure
+
+. Copy the `resources/` folder from the `site-configs/` directory into the new `site-configs-v2/` directory:
++
+[source,bash]
+----
+$ cp -r site-configs/resources site-configs-v2/
+----
+
+. Remove the reference to the `resources/` folder from the `site-configs/kustomization.yaml` file.
+This ensures that the old `clusters` Argo CD application no longer manages the `active-ocp-version` resource.
++
+.Example updated `site-configs/resources/kustomization.yaml` file
+[source,yaml]
+----
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+   - pre-reqs/
+   #- resources/
+generators:
+   - hub-1/sno1.yaml
+   - hub-1/sno2.yaml
+   - hub-1/sno3.yaml
+----
+
+. Add the `resources/` folder to the `site-configs-v2/kustomization.yaml` file.  
+This step transfers ownership of the `ClusterImageSet` to the new `clusters-v2` application.
++
+.Example updated `site-configs-v2/kustomization.yaml` file
+[source,yaml]
+----
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - resources/
+----
+
+. Commit and push the changes to the Git repository.
+
+.Verification
+
+. In Argo CD, verify that the `clusters-v2` application is *Healthy* and *Synced*.
+
+. If the `active-ocp-version` `ClusterImageSet` resource in the `cluster` Argo application is out of sync, you can remove the Argo CD application label by running the following command:
++
+[source,bash]
+----
+$ oc label clusterimageset active-ocp-version app.kubernetes.io/instance- 
+----
++
+.Example output
+[source,bash]
+----
+clusterimageset.hive.openshift.io/active-ocp-version unlabeled
+----
diff --git a/modules/ztp-clusterinstance-cleanup.adoc b/modules/ztp-clusterinstance-cleanup.adoc
@@ -0,0 +1,81 @@
+// Module included in the following assemblies:
+//
+// * edge_computing/ztp-migrate-clusterinstance.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ztp-clusterinstance-cleanup_{context}"]
+= Deleting the Argo CD pipeline post-migration
+
+After you migrate all {sno} clusters from using `SiteConfig` CRs to `ClusterInstance` CRs, you can delete the original Argo CD application and related resources that managed the `SiteConfig` CRs.
+
+[NOTE]
+====
+Only delete the Argo CD application and related resources after you have confirmed that all clusters are successfully managed by the new Argo CD application that uses `ClusterInstance` CRs. Additionally, if the Argo CD project was only used for the migrated cluster's Argo application, you can also delete this project.
+====
+
+.Prerequisites
+* You have logged in to the hub cluster as a user with `cluster-admin` privileges.
+* All {sno} clusters have been successfully migrated to use `ClusterInstance` CRs and are managed by another Argo CD application.
+
+.Procedure
+
+. Delete the original Argo CD application that managed the `SiteConfig` CRs:
++
+[source,bash]
+----
+$ oc delete application.argo clusters -n openshift-gitops
+----
++
+* Replace `clusters` with the name of your original Argo CD application.
+
+. Delete the original Argo CD project by running the following command:
++
+[source,bash]
+----
+$ oc delete appproject ztp-app-project -n openshift-gitops 
+----
++
+* Replace `ztp-app-project` with the name of your original Argo CD project.
+
+.Verification
+
+. Confirm that the original Argo CD application is deleted by running the following command:
++
+[source,bash]
+----
+$ oc get appproject -n openshift-gitops
+----
++
+.Example output
+[source,bash]
+----
+NAME                 AGE
+default              6d20h
+policy-app-project   2d22h
+ztpv2-app-project    44h
+----
++
+* The original Argo CD project in this example, `ztp-app-project` is not present in the output.
+
+. Confirm that the original Argo CD project is deleted by running the following command:
++
+[source,bash]
+----
+oc get applications.argo -n openshift-gitops
+----
++
+.Example output
+[source,bash]
+----
+NAME                       SYNC STATUS   HEALTH STATUS
+clusters-v2                Synced        Healthy
+policies                   Synced        Healthy
+----
++
+* The original Argo CD application in this example, `clusters` is not present in the output.
+
+
+
+
+
+
diff --git a/modules/ztp-clusterinstance-troubleshooting.adoc b/modules/ztp-clusterinstance-troubleshooting.adoc
@@ -0,0 +1,87 @@
+// Module included in the following assemblies:
+//
+// * edge_computing/ztp-migrate-clusterinstance.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ztp-clusterinstance-troubleshooting_{context}"]
+= Troubleshooting the migration to ClusterInstance CRs
+
+Consider the following troubleshooting steps if you encounter issues during the migration from `SiteConfig` CRs to `ClusterInstance` CRs.
+
+.Procedure
+
+* Verify that the SiteConfig Operator rendered all the required deployment resources by running the following command:
++
+[source,bash]
+----
+$ oc -n <target_cluster> get clusterinstances <target_cluster> -ojson | jq .status.manifestsRendered
+----
++
+.Example output
+[source,json]
+----
+[
+  {
+    "apiGroup": "extensions.hive.openshift.io/v1beta1",
+    "kind": "AgentClusterInstall",
+    "lastAppliedTime": "2025-01-13T11:10:52Z",
+    "name": "sno1",
+    "namespace": "sno1",
+    "status": "rendered",
+    "syncWave": 1
+  },
+  {
+    "apiGroup": "metal3.io/v1alpha1",
+    "kind": "BareMetalHost",
+    "lastAppliedTime": "2025-01-13T11:10:53Z",
+    "name": "sno1.example.com",
+    "namespace": "sno1",
+    "status": "rendered",
+    "syncWave": 1
+  },
+  {
+    "apiGroup": "hive.openshift.io/v1",
+    "kind": "ClusterDeployment",
+    "lastAppliedTime": "2025-01-13T11:10:53Z",
+    "name": "sno1",
+    "namespace": "sno1",
+    "status": "rendered",
+    "syncWave": 1
+  },
+  {
+    "apiGroup": "agent-install.openshift.io/v1beta1",
+    "kind": "InfraEnv",
+    "lastAppliedTime": "2025-01-13T11:10:53Z",
+    "name": "sno1",
+    "namespace": "sno1",
+    "status": "rendered",
+    "syncWave": 1
+  },
+  {
+    "apiGroup": "agent-install.openshift.io/v1beta1",
+    "kind": "NMStateConfig",
+    "lastAppliedTime": "2025-01-13T11:10:53Z",
+    "name": "sno1.example.com",
+    "namespace": "sno1",
+    "status": "rendered",
+    "syncWave": 1
+  },
+  {
+    "apiGroup": "agent.open-cluster-management.io/v1",
+    "kind": "KlusterletAddonConfig",
+    "lastAppliedTime": "2025-01-13T11:10:53Z",
+    "name": "sno1",
+    "namespace": "sno1",
+    "status": "rendered",
+    "syncWave": 2
+  },
+  {
+    "apiGroup": "cluster.open-cluster-management.io/v1",
+    "kind": "ManagedCluster",
+    "lastAppliedTime": "2025-01-13T11:10:53Z",
+    "name": "sno1",
+    "status": "rendered",
+    "syncWave": 2
+  }
+]
+----