Skip to content

Commit 23a4f5a

Browse files
lahinsonlahinson
committed
[OSDOCS-6488]: Adding troubleshooting docs for hosted control planes
1 parent 88f0668 commit 23a4f5a

File tree

2 files changed

+148
-0
lines changed

2 files changed

+148
-0
lines changed

‎hosted_control_planes/hcp-managing.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,5 +19,6 @@ include::modules/hosted-control-planes-pause-reconciliation.adoc[leveloffset=+1]
1919
//using service-level DNS for control plane services
2020
//configuring metrics sets
2121
//automated machine management
22+
include::modules/hosted-control-planes-troubleshooting.adoc[leveloffset=+1]
2223
include::modules/delete-hosted-cluster.adoc[leveloffset=+1]
2324

‎modules/hosted-control-planes-troubleshooting.adoc

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hosted_control_planes/hcp-managing.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="hosted-control-planes-troubleshooting_{context}"]
7+
= Troubleshooting hosted control planes
8+
9+
When you need to troubleshoot an issue with hosted control plane clusters, you can gather information by running the `hypershift dump cluster` command. The command generates output for the management cluster and the hosted cluster.
10+
11+
The output for the management cluster contains the following content:
12+
13+
* *Cluster-scoped resources:* These resources are node definitions of the management cluster.
14+
* *The `hypershift-dump` compressed file:* This file is useful if you need to share the content with other people.
15+
* *Namespaced resources:* These resources include all of the objects from the relevant namespaces, such as config maps, services, events, and logs.
16+
* *Network logs:* These logs include the OVN northbound and southbound databases and the status for each one.
17+
* *Hosted clusters:* This level of output involves all of the resources inside of the hosted cluster.
18+
19+
The output for the hosted cluster contains the following content:
20+
21+
* *Cluster-scoped resources:* These resources include all of the cluster-wide objects, such as nodes and CRDs.
22+
* *Namespaced resources:* These resources include all of the objects from the relevant namespaces, such as config maps, services, events, and logs.
23+
24+
Although the output does not contain any secret objects from the cluster, it can contain references to the names of secrets.
25+
26+
.Prerequisites
27+
28+
* You must have `cluster-admin` access to the management cluster.
29+
30+
* You need the `name` value for the `HostedCluster` resource and the namespace where the CR is deployed.
31+
32+
* You must have the `hcp` command line interface installed. For more information, see link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.8/html/clusters/cluster_mce_overview#hosted-install-cli[Installing the hosted control planes command line interface].
33+
34+
* You must have the OpenShift CLI (`oc`) installed.
35+
36+
* You must ensure that the `kubeconfig` file is loaded and is pointing to the management cluster.
37+
38+
.Procedure
39+
40+
* To gather output for troubleshooting, enter the following commands:
41+
+
42+
[source,terminal]
43+
----
44+
$ CLUSTERNAME="samplecluster"
45+
----
46+
+
47+
[source,terminal]
48+
----
49+
$ CLUSTERNS="clusters"
50+
----
51+
+
52+
[source,terminal]
53+
----
54+
$ mkdir clusterDump-${CLUSTERNS}-${CLUSTERNAME}
55+
----
56+
+
57+
[source, terminal]
58+
----
59+
$ hypershift dump cluster \
60+
--name ${CLUSTERNAME} \
61+
--namespace ${CLUSTERNS} \
62+
--dump-guest-cluster \
63+
--artifact-dir clusterDump-${CLUSTERNS}-${CLUSTERNAME}
64+
----
65+
+
66+
.Example output
67+
+
68+
[source,terminal]
69+
----
70+
2023-06-06T12:18:20+02:00 INFO Archiving dump {"command": "tar", "args": ["-cvzf", "hypershift-dump.tar.gz", "cluster-scoped-resources", "event-filter.html", "namespaces", "network_logs", "timestamp"]}
71+
2023-06-06T12:18:21+02:00 INFO Successfully archived dump {"duration": "1.519376292s"}
72+
----
73+
74+
* To configure the command-line interface so that it impersonates all of the queries against the management cluster by using a username or service account, enter the `hypershift dump cluster` command with the `--as` flag.
75+
+
76+
The service account must have enough permissions to query all of the objects from the namespaces, so the `cluster-admin` role is recommended to make sure you have enough permissions. The service account must be located in or have permissions to query the namespace of the `HostedControlPlane` resource.
77+
+
78+
If your username or service account does not have enough permissions, the output contains only the objects that you have permissions to access. During that process, you might see `forbidden` errors.
79+
+
80+
** To use impersonation by using a service account, enter the following commands. Replace values as necessary:
81+
+
82+
[source,terminal]
83+
----
84+
$ CLUSTERNAME="samplecluster"
85+
----
86+
+
87+
[source,terminal]
88+
----
89+
$ CLUSTERNS="clusters"
90+
----
91+
+
92+
[source,terminal]
93+
----
94+
$ SA="samplesa"
95+
----
96+
+
97+
[source,terminal]
98+
----
99+
$ SA_NAMESPACE="default"
100+
----
101+
+
102+
[source,terminal]
103+
----
104+
$ mkdir clusterDump-${CLUSTERNS}-${CLUSTERNAME}
105+
----
106+
+
107+
[source,terminal]
108+
----
109+
$ hypershift dump cluster \
110+
--name ${CLUSTERNAME} \
111+
--namespace ${CLUSTERNS} \
112+
--dump-guest-cluster \
113+
--as "system:serviceaccount:${SA_NAMESPACE}:${SA}" \
114+
--artifact-dir clusterDump-${CLUSTERNS}-${CLUSTERNAME}
115+
----
116+
117+
** To use impersonation by using a username, enter the following commands. Replace values as necessary:
118+
+
119+
[source,terminal]
120+
----
121+
$ CLUSTERNAME="samplecluster"
122+
----
123+
+
124+
[source,terminal]
125+
----
126+
$ CLUSTERNS="clusters"
127+
----
128+
+
129+
[source,terminal]
130+
----
131+
$ CLUSTERUSER="cloud-admin"
132+
----
133+
+
134+
[source,terminal]
135+
----
136+
$ mkdir clusterDump-${CLUSTERNS}-${CLUSTERNAME}
137+
----
138+
+
139+
[source,terminal]
140+
----
141+
$ hypershift dump cluster \
142+
--name ${CLUSTERNAME} \
143+
--namespace ${CLUSTERNS} \
144+
--dump-guest-cluster \
145+
--as "${CLUSTERUSER}" \
146+
--artifact-dir clusterDump-${CLUSTERNS}-${CLUSTERNAME}
147+
----

0 commit comments

Comments
 (0)