diff --git a/modules/hosted-control-planes-troubleshooting.adoc b/modules/hosted-control-planes-troubleshooting.adoc index b5d5473270..2a707afe51 100644 --- a/modules/hosted-control-planes-troubleshooting.adoc +++ b/modules/hosted-control-planes-troubleshooting.adoc @@ -6,7 +6,7 @@ [id="hosted-control-planes-troubleshooting_{context}"] = Gathering information to troubleshoot {hcp} -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. +When you need to troubleshoot an issue with hosted control plane clusters, you can gather information by running the `must-gather` command. The command generates output for the management cluster and the hosted cluster. The output for the management cluster contains the following content: @@ -41,56 +41,13 @@ Although the output does not contain any secret objects from the cluster, it can + [source,terminal] ---- -$ hypershift dump cluster \ - --name \// <1> - --namespace \ <2> - --dump-guest-cluster \ - --artifact-dir clusterDump-- +$ oc adm must-gather --image=registry.redhat.io/multicluster-engine/must-gather-rhel9:v \ + /usr/bin/gather hosted-cluster-namespace=HOSTEDCLUSTERNAMESPACE hosted-cluster-name=HOSTEDCLUSTERNAME \ + --dest-dir=NAME ; tar -cvzf NAME.tgz NAME ---- + -<1> Specify your hosted cluster name. -<2> Specify your hosted cluster namespace, for example, `clusters`. -+ -.Example output -+ -[source,terminal] ----- -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"]} -2023-06-06T12:18:21+02:00 INFO Successfully archived dump {"duration": "1.519376292s"} ----- +where: -* 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. -+ -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. -+ -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. -+ -** To use impersonation by using a service account, enter the following command: -+ -[source,terminal] ----- -$ hypershift dump cluster \ - --name \// <1> - --namespace \// <2> - --dump-guest-cluster \ - --as "system:serviceaccount::" \ <3> - --artifact-dir clusterDump-- ----- -<1> Specify your hosted cluster name. -<2> Specify your hosted cluster namespace, for example, `clusters`. -<3> Specify the `default` namespace and name, for example, `"system:serviceaccount:default:samplesa"`. - -** To use impersonation by using a username, enter the following command: -+ -[source,terminal] ----- -$ hypershift dump cluster \ - --name \// <1> - --namespace \// <2> - --dump-guest-cluster \ - --as "" \ <3> - --artifact-dir clusterDump-- ----- -<1> Specify your hosted cluster name. -<2> Specify your hosted cluster namespace, for example, `clusters`. -<3> Specify your cluster user name, for example, `cloud-admin`. +** You replace `` with the version of {mce-short} that you are using; for example, `2.4`. +** The `hosted-cluster-namespace=HOSTEDCLUSTERNAMESPACE` parameter is optional. If you do not include it, the command runs as though the hosted cluster is in the default namespace, which is `clusters`. +** The `--dest-dir=NAME` parameter is optional. Specify that parameter if you want to save the results of the command to a compressed file, replacing `NAME` with the name of the directory where you want to save the results. \ No newline at end of file