Merge pull request #74687 from xenolinux/minor-updates-hcp

OSDOCS#10263: Hosted control planes: Review user replaceable values

Author: jab-rh

modules/backup-etcd-hosted-cluster.adoc

@@ -19,22 +19,28 @@ This procedure requires API downtime.
 +
 [source,terminal]
 ----
-$ oc patch -n clusters hostedclusters/${CLUSTER_NAME} -p '{"spec":{"pausedUntil":"'${PAUSED_UNTIL}'"}}' --type=merge
+$ oc patch -n clusters hostedclusters/<hosted_cluster_name> -p '{"spec":{"pausedUntil":"true"}}' --type=merge
 ----
 
 . Stop all etcd-writer deployments by entering this command:
 +
 [source,terminal]
 ----
-$ oc scale deployment -n ${HOSTED_CLUSTER_NAMESPACE} --replicas=0 kube-apiserver openshift-apiserver openshift-oauth-apiserver
+$ oc scale deployment -n <hosted_cluster_namespace> --replicas=0 kube-apiserver openshift-apiserver openshift-oauth-apiserver
 ----
 
-. Take an etcd snapshot by using the `exec` command in each etcd container:
+. To take an etcd snapshot, use the `exec` command in each etcd container by running the following command:
 +
 [source,terminal]
 ----
-$ oc exec -it etcd-0 -n ${HOSTED_CLUSTER_NAMESPACE} -- env ETCDCTL_API=3 /usr/bin/etcdctl --cacert /etc/etcd/tls/client/etcd-client-ca.crt --cert /etc/etcd/tls/client/etcd-client.crt --key /etc/etcd/tls/client/etcd-client.key --endpoints=localhost:2379 snapshot save /var/lib/data/snapshot.db
-$ oc exec -it etcd-0 -n ${HOSTED_CLUSTER_NAMESPACE} -- env ETCDCTL_API=3 /usr/bin/etcdctl -w table snapshot status /var/lib/data/snapshot.db
+$ oc exec -it <etcd_pod_name> -n <hosted_cluster_namespace> -- env ETCDCTL_API=3 /usr/bin/etcdctl --cacert /etc/etcd/tls/client/etcd-client-ca.crt --cert /etc/etcd/tls/client/etcd-client.crt --key /etc/etcd/tls/client/etcd-client.key --endpoints=localhost:2379 snapshot save /var/lib/data/snapshot.db
+----
+
+. To check the snapshot status, use the `exec` command in each etcd container by running the following command:
++
+[source,terminal]
+----
+$ oc exec -it <etcd_pod_name> -n <hosted_cluster_namespace> -- env ETCDCTL_API=3 /usr/bin/etcdctl -w table snapshot status /var/lib/data/snapshot.db
 ----
 
 . Copy the snapshot data to a location where you can retrieve it later, such as an S3 bucket, as shown in the following example.

modules/hosted-cluster-etcd-status.adoc

@@ -14,7 +14,7 @@ To check the status of your hosted cluster, complete the following steps.
 +
 [source,terminal]
 ----
-$ oc rsh -n <control_plane_namespace> -c etcd etcd-0
+$ oc rsh -n <control_plane_namespace> -c etcd <etcd_pod_name>
 ----
 
 . Set up the etcdctl environment by entering the following commands:
@@ -49,4 +49,4 @@ sh-4.4$ export ETCDCTL_ENDPOINTS=https://etcd-client:2379
 [source,terminal]
 ----
 sh-4.4$ etcdctl endpoint health --cluster -w table
-----
+----

modules/hosted-cluster-single-node-recovery.adoc

@@ -32,14 +32,14 @@ etcd-2   1/2     CrashLoopBackOff   1 (5s ago)   64m
 +
 [source,terminal]
 ----
-$ oc delete pvc/data-etcd-2 pod/etcd-2 --wait=false
+$ oc delete pvc/<pvc_name> pod/<etcd_pod_name> --wait=false
 ----
 
 . When the pod restarts, verify that the etcd member is added back to the etcd cluster and is correctly functioning by entering the following command:
 +
 [source,terminal]
 ----
-$ oc get pods -l app=etcd -n $CONTROL_PLANE_NAMESPACE
+$ oc get pods -l app=etcd -n <control_plane_namespace>
 ----
 +
 .Example output
@@ -49,4 +49,4 @@ NAME     READY   STATUS    RESTARTS   AGE
 etcd-0   2/2     Running   0          67m
 etcd-1   2/2     Running   0          48m
 etcd-2   2/2     Running   0          2m2s
-----
+----

modules/hosted-control-planes-monitoring-dashboard.adoc

@@ -35,7 +35,7 @@ data:
 ----
 
 +
-When monitoring dashboards are enabled, for each hosted cluster that the HyperShift Operator manages, the Operator creates a config map named `cp-[NAMESPACE]-[NAME]` in the `openshift-config-managed` namespace, where `NAMESPACE` is the namespace of the hosted cluster and `NAME` is the name of the hosted cluster. As a result, a new dashboard is added in the administrative console of the management cluster.
+When monitoring dashboards are enabled, for each hosted cluster that the HyperShift Operator manages, the Operator creates a config map named `cp-<hosted_cluster_namespace>-<hosted_cluster_name>` in the `openshift-config-managed` namespace, where `<hosted_cluster_namespace>` is the namespace of the hosted cluster and `<hosted_cluster_name>` is the name of the hosted cluster. As a result, a new dashboard is added in the administrative console of the management cluster.
 
 . To view the dashboard, log in to the management cluster's console and go to the dashboard for the hosted cluster by clicking *Observe -> Dashboards*.
 
@@ -44,7 +44,7 @@ When monitoring dashboards are enabled, for each hosted cluster that the HyperSh
 [#hosted-control-planes-customize-dashboards]
 == Dashboard customization
 
-To generate dashboards for each hosted cluster, the HyperShift Operator uses a template that is stored in the `monitoring-dashboard-template` config map in the operator namespace (`hypershift`). This template contains a set of Grafana panels that contain the metrics for the dashboard. You can edit the content of the config map to customize the dashboards.
+To generate dashboards for each hosted cluster, the HyperShift Operator uses a template that is stored in the `monitoring-dashboard-template` config map in the Operator namespace (`hypershift`). This template contains a set of Grafana panels that contain the metrics for the dashboard. You can edit the content of the config map to customize the dashboards.
 
 When a dashboard is generated, the following strings are replaced with values that correspond to a specific hosted cluster:
 

modules/hosted-control-planes-pause-reconciliation.adoc

@@ -10,24 +10,22 @@ If you are a cluster instance administrator, you can pause the reconciliation of
 
 .Procedure
 
-. To pause reconciliation for a hosted cluster and hosted control plane, populate the `pausedUntil` field of the `HostedCluster` resource, as shown in the following examples. In the examples, the value for `pausedUntil` is defined in an environment variable prior to the command.
+. To pause reconciliation for a hosted cluster and hosted control plane, populate the `pausedUntil` field of the `HostedCluster` resource.
 +
-** To pause the reconciliation until a specific time, specify an RFC339 timestamp:
+** To pause the reconciliation until a specific time, enter the following command:
 +
 [source,terminal]
 ----
-PAUSED_UNTIL="2022-03-03T03:28:48Z"
-oc patch -n <hosted-cluster-namespace> hostedclusters/<hosted-cluster-name> -p '{"spec":{"pausedUntil":"'${PAUSED_UNTIL}'"}}' --type=merge
+$ oc patch -n <hosted_cluster_namespace> hostedclusters/<hosted_cluster_name> -p '{"spec":{"pausedUntil":"<timestamp>"}}' --type=merge <1>
 ----
 +
-The reconciliation is paused until the specified time is passed.
+<1> Specify a timestamp in the RFC339 format, for example, `2024-03-03T03:28:48Z`. The reconciliation is paused until the specified time is passed.
 +
-** To pause the reconciliation indefinitely, pass a Boolean value of `true`:
+** To pause the reconciliation indefinitely, enter the following command:
 +
 [source,terminal]
 ----
-PAUSED_UNTIL="true"
-oc patch -n <hosted-cluster-namespace> hostedclusters/<hosted-cluster-name> -p '{"spec":{"pausedUntil":"'${PAUSED_UNTIL}'"}}' --type=merge
+$ oc patch -n <hosted_cluster_namespace> hostedclusters/<hosted_cluster_name> -p '{"spec":{"pausedUntil":"true"}}' --type=merge
 ----
 +
 The reconciliation is paused until you remove the field from the `HostedCluster` resource.
@@ -38,5 +36,5 @@ When the pause reconciliation field is populated for the `HostedCluster` resourc
 +
 [source,terminal]
 ----
-oc patch -n <hosted-cluster-namespace> hostedclusters/<hosted-cluster-name> -p '{"spec":{"pausedUntil":null}}' --type=merge
+$ oc patch -n <hosted_cluster_namespace> hostedclusters/<hosted_cluster_name> -p '{"spec":{"pausedUntil":null}}' --type=merge
 ----

modules/hosted-control-planes-troubleshooting.adoc

@@ -37,32 +37,20 @@ Although the output does not contain any secret objects from the cluster, it can
 
 .Procedure
 
-* To gather output for troubleshooting, enter the following commands:
-+
-[source,terminal]
-----
-$ CLUSTERNAME="samplecluster"
-----
-+
-[source,terminal]
-----
-$ CLUSTERNS="clusters"
-----
-+
-[source,terminal]
-----
-$ mkdir clusterDump-${CLUSTERNS}-${CLUSTERNAME}
-----
+* To gather the output for troubleshooting, enter the following command:
 +
 [source,terminal]
 ----
 $ hypershift dump cluster \
-    --name ${CLUSTERNAME} \
-    --namespace ${CLUSTERNS} \
+    --name <hosted_cluster_name> \// <1>
+    --namespace <hosted_cluster_namespace> \ <2>
     --dump-guest-cluster \
-    --artifact-dir clusterDump-${CLUSTERNS}-${CLUSTERNAME}
+    --artifact-dir clusterDump-<hosted_cluster_namespace>-<hosted_cluster_name>
 ----
 +
+<1> Specify your hosted cluster name.
+<2> Specify your hosted cluster namespace, for example, `clusters`.
++
 .Example output
 +
 [source,terminal]
@@ -77,71 +65,32 @@ The service account must have enough permissions to query all of the objects fro
 +
 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 commands. Replace values as necessary:
-+
-[source,terminal]
-----
-$ CLUSTERNAME="samplecluster"
-----
-+
-[source,terminal]
-----
-$ CLUSTERNS="clusters"
-----
-+
-[source,terminal]
-----
-$ SA="samplesa"
-----
-+
-[source,terminal]
-----
-$ SA_NAMESPACE="default"
-----
-+
-[source,terminal]
-----
-$ mkdir clusterDump-${CLUSTERNS}-${CLUSTERNAME}
-----
+** To use impersonation by using a service account, enter the following command:
 +
 [source,terminal]
 ----
 $ hypershift dump cluster \
-    --name ${CLUSTERNAME} \
-    --namespace ${CLUSTERNS} \
+    --name <hosted_cluster_name> \// <1>
+    --namespace <hosted_cluster_namespace> \// <2>
     --dump-guest-cluster \
-    --as "system:serviceaccount:${SA_NAMESPACE}:${SA}" \
-    --artifact-dir clusterDump-${CLUSTERNS}-${CLUSTERNAME}
+    --as "system:serviceaccount:<service_account_namespace>:<service_account_name>" \ <3>
+    --artifact-dir clusterDump-<hosted_cluster_namespace>-<hosted_cluster_name>
 ----
+<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 commands. Replace values as necessary:
-+
-[source,terminal]
-----
-$ CLUSTERNAME="samplecluster"
-----
-+
-[source,terminal]
-----
-$ CLUSTERNS="clusters"
-----
-+
-[source,terminal]
-----
-$ CLUSTERUSER="cloud-admin"
-----
-+
-[source,terminal]
-----
-$ mkdir clusterDump-${CLUSTERNS}-${CLUSTERNAME}
-----
+** To use impersonation by using a username, enter the following command:
 +
 [source,terminal]
 ----
 $ hypershift dump cluster \
-    --name ${CLUSTERNAME} \
-    --namespace ${CLUSTERNS} \
+    --name <hosted_cluster_name> \// <1>
+    --namespace <hosted_cluster_namespace> \// <2>
     --dump-guest-cluster \
-    --as "${CLUSTERUSER}" \
-    --artifact-dir clusterDump-${CLUSTERNS}-${CLUSTERNAME}
-----
+    --as "<cluster_user_name>" \ <3>
+    --artifact-dir clusterDump-<hosted_cluster_namespace>-<hosted_cluster_name>
+----
+<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`.

modules/updating-node-pools-for-hcp.adoc

@@ -15,9 +15,14 @@ On hosted control planes, you update your version of {product-title} by updating
 +
 [source,terminal]
 ----
-$ oc -n NAMESPACE patch HC HCNAME --patch '{"spec":{"release":{"image": "example"}}}' --type=merge
+$ oc -n <hosted_cluster_namespace> patch hostedcluster <hosted_cluster_name> --patch '{"spec":{"release":{"image": "<image_name>"}}}' --type=merge
 ----
 
 .Verification
 
-* To verify that the new version was rolled out, check the `.status.version` value and the status conditions.
+* To verify that the new version was rolled out, check the `.status.version` and `.status.conditions` values in the `HostedCluster` custom resource (CR) by running the following command:
++
+[source,terminal]
+----
+$ oc get hostedcluster <hosted_cluster_name> -o yaml
+----