Skip to content

CNTRLPLANE-3526: Add spec.monitoring API for metrics forwarding #8626

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
muraee wants to merge 4 commits into
base: main
Choose a base branch
from
Open

CNTRLPLANE-3526: Add spec.monitoring API for metrics forwarding #8626

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c88a5ce
feat(api): add spec.monitoring with metricsForwarding API
muraee Jun 11, 2026
83ff6e1
chore(api): regenerate CRDs, deepcopy, clients, vendor, and docs
muraee Jun 11, 2026
8a4a996
feat(cpo,ho): use spec.monitoring API instead of annotation
muraee Jun 11, 2026
f092dcd
feat(api,cpo): add metricsSet to MetricsForwardingSpec
muraee Jun 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions api/hypershift/v1beta1/hosted_controlplane.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,13 @@ type HostedControlPlaneSpec struct {
// +optional
OperatorConfiguration *OperatorConfiguration `json:"operatorConfiguration,omitempty"`

// monitoring configures monitoring for the hosted cluster, including
// forwarding of control plane metrics to the hosted cluster's monitoring stack.
// When omitted, metrics forwarding is not configured and will be inactive.
//
// +optional
Monitoring MonitoringSpec `json:"monitoring,omitzero"`

Comment thread
muraee marked this conversation as resolved.
// imageContentSources lists sources/repositories for the release-image content.
// +optional
// +kubebuilder:validation:MaxItems=255
Expand Down
102 changes: 102 additions & 0 deletions api/hypershift/v1beta1/hostedcluster_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,6 +273,8 @@ const (

// EnableMetricsForwarding enables metrics forwarding from the management cluster to hosted clusters.
// When present, components like the endpoint-resolver and metrics-proxy will be deployed.
// Deprecated: Use spec.monitoring.metricsForwarding instead. This annotation is preserved
// for backward compatibility and will be honored when spec.monitoring is not set.
EnableMetricsForwarding = "hypershift.openshift.io/enable-metrics-forwarding"

// JSONPatchAnnotation allow modifying the kubevirt VM template using jsonpatch
Expand Down Expand Up @@ -833,6 +835,15 @@ type HostedClusterSpec struct {
// +kubebuilder:default={}
// +kubebuilder:validation:XValidation:rule="self == oldSelf", message="Capabilities is immutable. Changes might result in unpredictable and disruptive behavior."
Capabilities *Capabilities `json:"capabilities,omitempty"`

// monitoring configures monitoring for the hosted cluster, including
// forwarding of control plane metrics to the hosted cluster's monitoring stack.
// When omitted, metrics forwarding behavior is determined by the
// hypershift.openshift.io/enable-metrics-forwarding annotation for backward compatibility.
// If neither is set, metrics forwarding is disabled.
//
// +optional
Monitoring MonitoringSpec `json:"monitoring,omitzero"`
Comment thread
muraee marked this conversation as resolved.
}

// OLMCatalogPlacement is an enum specifying the placement of OLM catalog components.
Expand Down Expand Up @@ -869,6 +880,97 @@ func (olm *OLMCatalogPlacement) Type() string {
return "OLMCatalogPlacement"
}

// MetricsForwardingMode controls whether metrics forwarding is active for a hosted cluster.
//
// +kubebuilder:validation:Enum=Forward;None
type MetricsForwardingMode string

const (
// MetricsForwardingModeForward indicates metrics forwarding is active.
MetricsForwardingModeForward MetricsForwardingMode = "Forward"

// MetricsForwardingModeNone indicates metrics forwarding is inactive.
MetricsForwardingModeNone MetricsForwardingMode = "None"
)
Comment thread
muraee marked this conversation as resolved.

// MetricsSet specifies the set of metrics to collect and forward from hosted clusters.
//
// +kubebuilder:validation:Enum=Telemetry;SRE;All
type MetricsSet string

const (
// MetricsSetTelemetry collects only the minimal set of metrics required for
// OpenShift Telemetry. Use this to minimize metrics volume while still
// satisfying cluster telemetry requirements.
MetricsSetTelemetry MetricsSet = "Telemetry"

// MetricsSetSRE collects the metrics defined in the sre-metric-set ConfigMap,
// which includes the Telemetry set plus additional metrics needed for SRE
// monitoring dashboards and alerts. Use this for clusters that require
// SRE observability.
MetricsSetSRE MetricsSet = "SRE"

// MetricsSetAll collects all metrics from control plane components without
// any filtering. Use this for debugging or when full metric visibility is
// needed, but be aware it produces significantly higher metrics volume.
MetricsSetAll MetricsSet = "All"
)

// MonitoringSpec configures monitoring for the hosted cluster.
// At least one field must be specified when this struct is present.
//
// +kubebuilder:validation:MinProperties=1
Comment thread
muraee marked this conversation as resolved.
type MonitoringSpec struct {
// metricsForwarding configures forwarding of control plane metrics into
// the hosted cluster's monitoring stack.
// When omitted, metrics forwarding behavior is determined by the
// hypershift.openshift.io/enable-metrics-forwarding annotation for backward compatibility.
// If neither is set, metrics forwarding is disabled.
//
// +optional
Comment thread
muraee marked this conversation as resolved.
MetricsForwarding MetricsForwardingSpec `json:"metricsForwarding,omitzero"`

// metricsSet specifies which set of metrics to collect and forward.
// This overrides the global METRICS_SET environment variable configured on the HyperShift Operator.
// When not specified, the global METRICS_SET value is used, which defaults to "Telemetry".
Comment thread
muraee marked this conversation as resolved.
//
// "Telemetry" collects only the minimal set of metrics required for OpenShift Telemetry.
// "SRE" collects the Telemetry set plus additional metrics defined in the sre-metric-set ConfigMap,
// needed for SRE dashboards and alerts.
// "All" collects all metrics from control plane components without filtering,
// which produces significantly higher metrics volume.
//
// +optional
MetricsSet MetricsSet `json:"metricsSet,omitempty"`
Comment thread
muraee marked this conversation as resolved.
}

// MetricsForwardingSpec configures metrics forwarding for the hosted cluster.
type MetricsForwardingSpec struct {
// mode controls whether metrics forwarding is active for this hosted cluster.
// When set to "Forward", metrics-proxy and endpoint-resolver are deployed in the
// control plane, and a metrics-forwarder is deployed in the hosted cluster.
// When set to "None", metrics forwarding is inactive.
//
// +required
Mode MetricsForwardingMode `json:"mode,omitempty"`

// metricsSet specifies which set of metrics to forward to the hosted

@jparrill jparrill Jun 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having metricsSet at two nesting levels (monitoring.metricsSet and monitoring.metricsForwarding.metricsSet) with the same field name but different scopes makes the precedence hard to discover — you need to read 3 files across HO and CPO to understand the chain: forwarding.metricsSet > monitoring.metricsSet > operator env var.

It might be worth evaluating whether renaming one of the two fields would make the intent clearer — e.g. calling the inner one forwardingMetricsSet or the outer one defaultMetricsSet. That way users can tell from the field name alone which scope each one controls, without needing to trace the resolution chain through the controller code.

// cluster's monitoring stack. This controls only the metrics-proxy forwarding
// path and does not affect management-cluster-side ServiceMonitor/PodMonitor
// relabel configurations.
// When not specified, the value from monitoring.metricsSet is used, which itself
// falls back to the global METRICS_SET environment variable (default "Telemetry").
//
// "Telemetry" forwards only the minimal set of metrics required for OpenShift Telemetry.
// "SRE" forwards the Telemetry set plus additional metrics defined in the sre-metric-set
// ConfigMap, needed for SRE dashboards and alerts.
// "All" forwards all metrics from control plane components without filtering,
// which produces significantly higher metrics volume.
//
// +optional
MetricsSet MetricsSet `json:"metricsSet,omitempty"`
}

// ImageContentSource specifies image mirrors that can be used by cluster nodes
// to pull content. For cluster workloads, if a container image registry host of
// the pullspec matches Source then one of the Mirrors are substituted as hosts
Expand Down
33 changes: 33 additions & 0 deletions api/hypershift/v1beta1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

66 changes: 66 additions & 0 deletions ...erated.featuregated-crd-manifests/hostedclusters.hypershift.openshift.io/AAA_ungated.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2877,6 +2877,72 @@ spec:
-kubebuilder:validation:XValidation:rule=`self.all(key, size(self[key]) <= 63 && self[key].matches('^(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])?$'))`, message="label value must be 63 characters or less (can be empty), consist of alphanumeric characters, dashes (-), underscores (_) or dots (.), and begin and end with an alphanumeric character"
maxProperties: 20
type: object
monitoring:
description: |-
monitoring configures monitoring for the hosted cluster, including
forwarding of control plane metrics to the hosted cluster's monitoring stack.
When omitted, metrics forwarding behavior is determined by the
hypershift.openshift.io/enable-metrics-forwarding annotation for backward compatibility.
If neither is set, metrics forwarding is disabled.
minProperties: 1
properties:
metricsForwarding:
description: |-
metricsForwarding configures forwarding of control plane metrics into
the hosted cluster's monitoring stack.
When omitted, metrics forwarding behavior is determined by the
hypershift.openshift.io/enable-metrics-forwarding annotation for backward compatibility.
If neither is set, metrics forwarding is disabled.
properties:
metricsSet:
description: |-
metricsSet specifies which set of metrics to forward to the hosted
cluster's monitoring stack. This controls only the metrics-proxy forwarding
path and does not affect management-cluster-side ServiceMonitor/PodMonitor
relabel configurations.
When not specified, the value from monitoring.metricsSet is used, which itself
falls back to the global METRICS_SET environment variable (default "Telemetry").

"Telemetry" forwards only the minimal set of metrics required for OpenShift Telemetry.
"SRE" forwards the Telemetry set plus additional metrics defined in the sre-metric-set
ConfigMap, needed for SRE dashboards and alerts.
"All" forwards all metrics from control plane components without filtering,
which produces significantly higher metrics volume.
enum:
- Telemetry
- SRE
- All
type: string
mode:
description: |-
mode controls whether metrics forwarding is active for this hosted cluster.
When set to "Forward", metrics-proxy and endpoint-resolver are deployed in the
control plane, and a metrics-forwarder is deployed in the hosted cluster.
When set to "None", metrics forwarding is inactive.
enum:
- Forward
- None
type: string
required:
- mode
type: object
metricsSet:
description: |-
metricsSet specifies which set of metrics to collect and forward.
This overrides the global METRICS_SET environment variable configured on the HyperShift Operator.
When not specified, the global METRICS_SET value is used, which defaults to "Telemetry".

"Telemetry" collects only the minimal set of metrics required for OpenShift Telemetry.
"SRE" collects the Telemetry set plus additional metrics defined in the sre-metric-set ConfigMap,
needed for SRE dashboards and alerts.
"All" collects all metrics from control plane components without filtering,
which produces significantly higher metrics volume.
enum:
- Telemetry
- SRE
- All
type: string
type: object
networking:
default:
clusterNetwork:
Expand Down
66 changes: 66 additions & 0 deletions ...egated-crd-manifests/hostedclusters.hypershift.openshift.io/ClusterUpdateAcceptRisks.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2868,6 +2868,72 @@ spec:
-kubebuilder:validation:XValidation:rule=`self.all(key, size(self[key]) <= 63 && self[key].matches('^(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])?$'))`, message="label value must be 63 characters or less (can be empty), consist of alphanumeric characters, dashes (-), underscores (_) or dots (.), and begin and end with an alphanumeric character"
maxProperties: 20
type: object
monitoring:
description: |-
monitoring configures monitoring for the hosted cluster, including
forwarding of control plane metrics to the hosted cluster's monitoring stack.
When omitted, metrics forwarding behavior is determined by the
hypershift.openshift.io/enable-metrics-forwarding annotation for backward compatibility.
If neither is set, metrics forwarding is disabled.
minProperties: 1
properties:
metricsForwarding:
description: |-
metricsForwarding configures forwarding of control plane metrics into
the hosted cluster's monitoring stack.
When omitted, metrics forwarding behavior is determined by the
hypershift.openshift.io/enable-metrics-forwarding annotation for backward compatibility.
If neither is set, metrics forwarding is disabled.
properties:
metricsSet:
description: |-
metricsSet specifies which set of metrics to forward to the hosted
cluster's monitoring stack. This controls only the metrics-proxy forwarding
path and does not affect management-cluster-side ServiceMonitor/PodMonitor
relabel configurations.
When not specified, the value from monitoring.metricsSet is used, which itself
falls back to the global METRICS_SET environment variable (default "Telemetry").

"Telemetry" forwards only the minimal set of metrics required for OpenShift Telemetry.
"SRE" forwards the Telemetry set plus additional metrics defined in the sre-metric-set
ConfigMap, needed for SRE dashboards and alerts.
"All" forwards all metrics from control plane components without filtering,
which produces significantly higher metrics volume.
enum:
- Telemetry
- SRE
- All
type: string
mode:
description: |-
mode controls whether metrics forwarding is active for this hosted cluster.
When set to "Forward", metrics-proxy and endpoint-resolver are deployed in the
control plane, and a metrics-forwarder is deployed in the hosted cluster.
When set to "None", metrics forwarding is inactive.
enum:
- Forward
- None
type: string
required:
- mode
type: object
metricsSet:
description: |-
metricsSet specifies which set of metrics to collect and forward.
This overrides the global METRICS_SET environment variable configured on the HyperShift Operator.
When not specified, the global METRICS_SET value is used, which defaults to "Telemetry".

"Telemetry" collects only the minimal set of metrics required for OpenShift Telemetry.
"SRE" collects the Telemetry set plus additional metrics defined in the sre-metric-set ConfigMap,
needed for SRE dashboards and alerts.
"All" collects all metrics from control plane components without filtering,
which produces significantly higher metrics volume.
enum:
- Telemetry
- SRE
- All
type: string
type: object
networking:
default:
clusterNetwork:
Expand Down
Loading