Skip to content

Commit 7080b7e

Browse files
slovernslovern
authored
Merge pull request #96809 from rohennes/TELCODOCS-2281
TELCODOCS-2281: Adding siteconfig to clusterinstance API docs
2 parents 9b7b417 + f16dff0 commit 7080b7e

11 files changed

+882
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3459,6 +3459,8 @@ Topics:
34593459
File: ztp-deploying-far-edge-sites
34603460
- Name: Manually installing a single-node OpenShift cluster with GitOps ZTP
34613461
File: ztp-manual-install
3462+
- Name: Migrating from SiteConfig CRs to ClusterInstance CRs
3463+
File: ztp-migrate-clusterinstance
34623464
- Name: Recommended single-node OpenShift cluster configuration for vDU application workloads
34633465
File: ztp-reference-cluster-configuration-for-vdu
34643466
- Name: Validating cluster tuning for vDU application workloads

‎edge_computing/ztp-migrate-clusterinstance.adoc‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="ztp-migrate-clusterinstance"]
3+
= Migrating from SiteConfig CRs to ClusterInstance CRs
4+
include::_attributes/common-attributes.adoc[]
5+
:context: ztp-migrate-clusterinstance
6+
7+
toc::[]
8+
9+
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.
10+
11+
[IMPORTANT]
12+
====
13+
* The `SiteConfig` CR is deprecated from {product-title} version 4.18 and will be removed in a future version.
14+
15+
* The `ClusterInstance` CR is available from {rh-rhacm-first} version 2.12 or later.
16+
====
17+
18+
include::modules/ztp-migrate-clusterinstance-overview.adoc[leveloffset=+1]
19+
20+
include::modules/ztp-creating-argocd-clusterinstance.adoc[leveloffset=+1]
21+
22+
include::modules/ztp-active-ocp-version.adoc[leveloffset=+1]
23+
24+
include::modules/ztp-migrating-sno-clusterinstnce.adoc[leveloffset=+1]
25+
26+
[role="_additional-resources"]
27+
.Additional resources
28+
29+
* 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]
30+
31+
//include::modules/ztp-clusterinstance-site-converter.adoc[leveloffset=+1]
32+
33+
include::modules/ztp-site-converter-ref.adoc[leveloffset=+2]
34+
35+
include::modules/ztp-clusterinstance-cleanup.adoc[leveloffset=+1]
36+
37+
//include::modules/ztp-enable-siteconfig-addon.adoc[leveloffset=+1]
38+
39+
include::modules/ztp-clusterinstance-troubleshooting.adoc[leveloffset=+1]

‎modules/ztp-active-ocp-version.adoc‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * edge_computing/ztp-migrate-clusterinstance.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="ztp-active-ocp-version_{context}"]
7+
= Transitioning the active-ocp-version ClusterImageSet
8+
9+
Optionally, the `active-ocp-version` `ClusterImageSet` is a {ztp-first} convention used in {ztp} deployments.
10+
It provides a single, central definition of the {product-title} release image to use when provisioning clusters.
11+
By default, this resource is synchronized to the hub cluster from the `site-config/resources/` folder.
12+
13+
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.
14+
This prevents synchronization conflicts because both Argo CD applications cannot manage the same resource.
15+
16+
.Prerequisites
17+
18+
* You have completed the procedure to create the parallel Argo CD pipeline for `ClusterInstance` CRs.
19+
* 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.
20+
* Your Git repository contains an `active-ocp-version.yaml` manifest in the `resources/` folder.
21+
22+
.Procedure
23+
24+
. Copy the `resources/` folder from the `site-configs/` directory into the new `site-configs-v2/` directory:
25+
+
26+
[source,bash]
27+
----
28+
$ cp -r site-configs/resources site-configs-v2/
29+
----
30+
31+
. Remove the reference to the `resources/` folder from the `site-configs/kustomization.yaml` file.
32+
This ensures that the old `clusters` Argo CD application no longer manages the `active-ocp-version` resource.
33+
+
34+
.Example updated `site-configs/resources/kustomization.yaml` file
35+
[source,yaml]
36+
----
37+
apiVersion: kustomize.config.k8s.io/v1beta1
38+
kind: Kustomization
39+
resources:
40+
- pre-reqs/
41+
#- resources/
42+
generators:
43+
- hub-1/sno1.yaml
44+
- hub-1/sno2.yaml
45+
- hub-1/sno3.yaml
46+
----
47+
48+
. Add the `resources/` folder to the `site-configs-v2/kustomization.yaml` file.
49+
This step transfers ownership of the `ClusterImageSet` to the new `clusters-v2` application.
50+
+
51+
.Example updated `site-configs-v2/kustomization.yaml` file
52+
[source,yaml]
53+
----
54+
apiVersion: kustomize.config.k8s.io/v1beta1
55+
kind: Kustomization
56+
resources:
57+
- resources/
58+
----
59+
60+
. Commit and push the changes to the Git repository.
61+
62+
.Verification
63+
64+
. In Argo CD, verify that the `clusters-v2` application is *Healthy* and *Synced*.
65+
66+
. 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:
67+
+
68+
[source,bash]
69+
----
70+
$ oc label clusterimageset active-ocp-version app.kubernetes.io/instance-
71+
----
72+
+
73+
.Example output
74+
[source,bash]
75+
----
76+
clusterimageset.hive.openshift.io/active-ocp-version unlabeled
77+
----

‎modules/ztp-clusterinstance-cleanup.adoc‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * edge_computing/ztp-migrate-clusterinstance.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="ztp-clusterinstance-cleanup_{context}"]
7+
= Deleting the Argo CD pipeline post-migration
8+
9+
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.
10+
11+
[NOTE]
12+
====
13+
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.
14+
====
15+
16+
.Prerequisites
17+
* You have logged in to the hub cluster as a user with `cluster-admin` privileges.
18+
* All {sno} clusters have been successfully migrated to use `ClusterInstance` CRs and are managed by another Argo CD application.
19+
20+
.Procedure
21+
22+
. Delete the original Argo CD application that managed the `SiteConfig` CRs:
23+
+
24+
[source,bash]
25+
----
26+
$ oc delete application.argo clusters -n openshift-gitops
27+
----
28+
+
29+
* Replace `clusters` with the name of your original Argo CD application.
30+
31+
. Delete the original Argo CD project by running the following command:
32+
+
33+
[source,bash]
34+
----
35+
$ oc delete appproject ztp-app-project -n openshift-gitops
36+
----
37+
+
38+
* Replace `ztp-app-project` with the name of your original Argo CD project.
39+
40+
.Verification
41+
42+
. Confirm that the original Argo CD application is deleted by running the following command:
43+
+
44+
[source,bash]
45+
----
46+
$ oc get appproject -n openshift-gitops
47+
----
48+
+
49+
.Example output
50+
[source,bash]
51+
----
52+
NAME AGE
53+
default 6d20h
54+
policy-app-project 2d22h
55+
ztpv2-app-project 44h
56+
----
57+
+
58+
* The original Argo CD project in this example, `ztp-app-project` is not present in the output.
59+
60+
. Confirm that the original Argo CD project is deleted by running the following command:
61+
+
62+
[source,bash]
63+
----
64+
oc get applications.argo -n openshift-gitops
65+
----
66+
+
67+
.Example output
68+
[source,bash]
69+
----
70+
NAME SYNC STATUS HEALTH STATUS
71+
clusters-v2 Synced Healthy
72+
policies Synced Healthy
73+
----
74+
+
75+
* The original Argo CD application in this example, `clusters` is not present in the output.
76+
77+
78+
79+
80+
81+

‎modules/ztp-clusterinstance-troubleshooting.adoc‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * edge_computing/ztp-migrate-clusterinstance.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="ztp-clusterinstance-troubleshooting_{context}"]
7+
= Troubleshooting the migration to ClusterInstance CRs
8+
9+
Consider the following troubleshooting steps if you encounter issues during the migration from `SiteConfig` CRs to `ClusterInstance` CRs.
10+
11+
.Procedure
12+
13+
* Verify that the SiteConfig Operator rendered all the required deployment resources by running the following command:
14+
+
15+
[source,bash]
16+
----
17+
$ oc -n <target_cluster> get clusterinstances <target_cluster> -ojson | jq .status.manifestsRendered
18+
----
19+
+
20+
.Example output
21+
[source,json]
22+
----
23+
[
24+
{
25+
"apiGroup": "extensions.hive.openshift.io/v1beta1",
26+
"kind": "AgentClusterInstall",
27+
"lastAppliedTime": "2025-01-13T11:10:52Z",
28+
"name": "sno1",
29+
"namespace": "sno1",
30+
"status": "rendered",
31+
"syncWave": 1
32+
},
33+
{
34+
"apiGroup": "metal3.io/v1alpha1",
35+
"kind": "BareMetalHost",
36+
"lastAppliedTime": "2025-01-13T11:10:53Z",
37+
"name": "sno1.example.com",
38+
"namespace": "sno1",
39+
"status": "rendered",
40+
"syncWave": 1
41+
},
42+
{
43+
"apiGroup": "hive.openshift.io/v1",
44+
"kind": "ClusterDeployment",
45+
"lastAppliedTime": "2025-01-13T11:10:53Z",
46+
"name": "sno1",
47+
"namespace": "sno1",
48+
"status": "rendered",
49+
"syncWave": 1
50+
},
51+
{
52+
"apiGroup": "agent-install.openshift.io/v1beta1",
53+
"kind": "InfraEnv",
54+
"lastAppliedTime": "2025-01-13T11:10:53Z",
55+
"name": "sno1",
56+
"namespace": "sno1",
57+
"status": "rendered",
58+
"syncWave": 1
59+
},
60+
{
61+
"apiGroup": "agent-install.openshift.io/v1beta1",
62+
"kind": "NMStateConfig",
63+
"lastAppliedTime": "2025-01-13T11:10:53Z",
64+
"name": "sno1.example.com",
65+
"namespace": "sno1",
66+
"status": "rendered",
67+
"syncWave": 1
68+
},
69+
{
70+
"apiGroup": "agent.open-cluster-management.io/v1",
71+
"kind": "KlusterletAddonConfig",
72+
"lastAppliedTime": "2025-01-13T11:10:53Z",
73+
"name": "sno1",
74+
"namespace": "sno1",
75+
"status": "rendered",
76+
"syncWave": 2
77+
},
78+
{
79+
"apiGroup": "cluster.open-cluster-management.io/v1",
80+
"kind": "ManagedCluster",
81+
"lastAppliedTime": "2025-01-13T11:10:53Z",
82+
"name": "sno1",
83+
"status": "rendered",
84+
"syncWave": 2
85+
}
86+
]
87+
----

0 commit comments

Comments
 (0)