From 8571e6a1706da41f8dae8b407c862267036686f5 Mon Sep 17 00:00:00 2001 From: Laura Hinson Date: Tue, 16 Jun 2026 13:34:14 -0400 Subject: [PATCH] [OSDOCS-19435]: Customizing cluster identifiers --- hosted_control_planes/hcp-observability.adoc | 16 ++++++ modules/hcp-cluster-ids-example.adoc | 56 +++++++++++++++++++ modules/hcp-cluster-ids.adoc | 21 +++++++ ...d-control-planes-monitoring-dashboard.adoc | 2 + 4 files changed, 95 insertions(+) create mode 100644 modules/hcp-cluster-ids-example.adoc create mode 100644 modules/hcp-cluster-ids.adoc diff --git a/hosted_control_planes/hcp-observability.adoc b/hosted_control_planes/hcp-observability.adoc index cdd25a25c5cc..aa36090b7b9b 100644 --- a/hosted_control_planes/hcp-observability.adoc +++ b/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] diff --git a/modules/hcp-cluster-ids-example.adoc b/modules/hcp-cluster-ids-example.adoc new file mode 100644 index 000000000000..21762797bdba --- /dev/null +++ b/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: + namespace: +spec: + clusterID: fa45babd-40f3-4085-9b30-8bc3b7df1557 + controllerAvailabilityPolicy: SingleReplica + dns: + baseDomain: example.com + platform: + type: AWS + release: + image: + pullSecret: + 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. diff --git a/modules/hcp-cluster-ids.adoc b/modules/hcp-cluster-ids.adoc new file mode 100644 index 000000000000..91d550cec9ee --- /dev/null +++ b/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. +==== diff --git a/modules/hosted-control-planes-monitoring-dashboard.adoc b/modules/hosted-control-planes-monitoring-dashboard.adoc index 656ea452fbea..5b7b7ce4d603 100644 --- a/modules/hosted-control-planes-monitoring-dashboard.adoc +++ b/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".