[OSDOCS-19435]: Customizing cluster identifiers

hosted_control_planes/hcp-observability.adoc

@@ -11,8 +11,24 @@ You can gather metrics for {hcp} by configuring metrics sets. Monitoring dashboa
 
 include::modules/hosted-control-planes-metrics-sets.adoc[leveloffset=+1]
 
+include::modules/hcp-cluster-ids.adoc[leveloffset=+1]
+
+include::modules/hcp-cluster-ids-example.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../hosted_control_planes/hcp-observability.adoc#hosted-control-planes-customize-dashboards_hcp-observability[Dashboard customization]
+* xref:../hosted_control_planes/hcp-observability.adoc#hosted-control-planes-metrics-sets_hcp-observability[Configuring metrics sets for hosted control planes]
+* xref:../hosted_control_planes/hcp-observability.adoc#hosted-control-planes-monitoring-dashboard_hcp-observability[Enabling monitoring dashboards in a hosted cluster]
+
 include::modules/hosted-control-planes-monitoring-dashboard.adoc[leveloffset=+1]
 
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../hosted_control_planes/hcp-observability.adoc#hcp-cluster-ids_hcp-observability[Customized hosted cluster identifiers]
+
 include::modules/hcp-connectivity-metrics.adoc[leveloffset=+1]
 
 include::modules/hcp-connect-data-plane.adoc[leveloffset=+2]

modules/hcp-cluster-ids-example.adoc

@@ -0,0 +1,56 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-observability.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="hcp-cluster-ids-example_{context}"]
+= Example: Setting a custom cluster identifier
+
+[role="_abstract"]
+You can set the `spec.clusterID` value only when you create a `HostedCluster` custom resource (CR).
+
+[IMPORTANT]
+====
+After you set `spec.clusterID` is set, you cannot change it. Plan the identifier before you create the hosted cluster.
+====
+
+The following example shows a `HostedCluster` CR with a custom cluster identifier set:
+
+.Example `HostedCluster` CR with a custom cluster identifier
+[source,yaml]
+----
+apiVersion: hypershift.openshift.io/v1beta1
+kind: HostedCluster
+metadata:
+  name: <hosted_cluster_name>
+  namespace: <hosted_cluster_namespace>
+spec:
+  clusterID: fa45babd-40f3-4085-9b30-8bc3b7df1557
+  controllerAvailabilityPolicy: SingleReplica
+  dns:
+    baseDomain: example.com
+  platform:
+    type: AWS
+  release:
+    image: <ocp_release_image>
+  pullSecret:
+    name: <pull_secret_name>
+----
+
+The `spec.clusterID` value is the UUID that you want to use as the stable cluster identifier in metrics. The value must be a valid RFC4122 UUID: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` in hexadecimal digits.
+
+The value of `spec.clusterID` is added as the `_id` label on control plane metrics through Prometheus relabeling rules on `ServiceMonitor` and `PodMonitor` resources. HyperShift Operator metrics for the hosted cluster also use the same `_id` label, so you can correlate metrics from the management cluster and the hosted control plane in one query.
+
+For example, to filter metrics for a specific hosted cluster, use the `_id` label in a PromQL expression:
+
+[source,promql]
+----
+{__name__=~"hypershift_.*", _id="fa45babd-40f3-4085-9b30-8bc3b7df1557"}
+----
+
+When you enable monitoring dashboards, the `__CLUSTER_ID__` placeholder in the dashboard template is replaced with the same UUID. For more information, see "Dashboard customization".
+
+[id="hcp-cluster-ids-reusing_{context}"]
+== Cluster identifier reuse after a reinstall
+
+If you delete and re-create a hosted cluster, a new random `clusterID` is assigned unless you specify one. To keep the same identifier in external monitoring systems, set `spec.clusterID` in the new `HostedCluster` CR to the UUID that you used before.

modules/hcp-cluster-ids.adoc

@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-observability.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="hcp-cluster-ids_{context}"]
+= Customized hosted cluster identifiers
+
+[role="_abstract"]
+When you enable observability for {hcp}, control plane metrics include an `_id` label that identifies the hosted cluster. You can set `spec.clusterID` in the `HostedCluster` custom resource (CR) at creation time to use a stable identifier instead of a randomly assigned UUID.
+
+When you forward hosted cluster metrics to an external monitoring system, the `_id` label is commonly used to identify the cluster. If you reinstall a hosted cluster, specifying the same `clusterID` value preserves your external monitoring configuration.
+
+Each hosted cluster has a unique cluster identifier. The HyperShift Operator uses this identifier in telemetry and in metrics that the control plane operators produce. The identifier is exposed on time series as the `_id` label.
+
+If you do not specify `spec.clusterID` when you create a `HostedCluster` CR, the HyperShift controller generates a random RFC4122 UUID and sets the field for you.
+
+[NOTE]
+====
+The `spec.clusterID` specification is not the same as the `spec.infraID` specification. The `infraID` value identifies cloud infrastructure resources.
+====

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

@@ -57,3 +57,5 @@ When a dashboard is generated, the following strings are replaced with values th
 | [x-]`__CONTROL_PLANE_NAMESPACE__` | The namespace where the control plane pods of the hosted cluster are placed
 | [x-]`__CLUSTER_ID__` | The UUID of the hosted cluster, which matches the `_id` label of the hosted cluster metrics
 |===
+
+To set a custom cluster identifier when you create the hosted cluster, see "Customized hosted cluster identifiers".