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 3 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
3 commits
Select commit Hold shift + click to select a range
5595f41
feat(api): add spec.monitoring with metricsForwarding API
muraee Jun 8, 2026
adcf016
chore(api): regenerate CRDs, deepcopy, clients, vendor, and docs
muraee Jun 8, 2026
a9ebe53
feat(cpo,ho): use spec.monitoring API instead of annotation
muraee Jun 8, 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
74 changes: 74 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 on lines +839 to +846

@everettraven everettraven Jun 9, 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.

In standalone OpenShift, we use feature-gates to ensure that we don't ship new APIs/fields as GA until we are confident that they are working as expected.

I believe HyperShift has a way to generate APIs following the same pattern but requires manually setting the feature gate enablement state in a static feature gates file.

Both the hypershift operator and control plane operator should also have a way to configure feature gates to be checked in their controllers.

It might be worth considering feature gating this functionality and going through a similar promotion process as we use for standalone openshift features to ensure we have sufficient automated regression testing in place and that those tests have consistently passed for some amount of time.

}

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

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

const (
// MetricsForwardingModeEnabled indicates metrics forwarding is active.
MetricsForwardingModeEnabled MetricsForwardingMode = "Enabled"

// MetricsForwardingModeDisabled indicates metrics forwarding is inactive.
MetricsForwardingModeDisabled MetricsForwardingMode = "Disabled"
)
Comment on lines +883 to +894

@everettraven everettraven Jun 9, 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.

In general, we discourage the usage of the terms Enabled / Disabled because they are often overloaded and can be more unclear to users as the enum values expand over time.

Maybe options like Forward and DoNotForward are more appropriately descriptive here?


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

const (
// MetricsSetTelemetry forwards only essential telemetry metrics.
MetricsSetTelemetry MetricsSet = "Telemetry"

// MetricsSetSRE forwards metrics defined in the sre-metric-set ConfigMap.
MetricsSetSRE MetricsSet = "SRE"

// MetricsSetAll forwards all metrics without filtering.
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.
//
// +optional

@everettraven everettraven Jun 9, 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.

What does it mean for this field to be omitted?

MetricsForwarding MetricsForwardingSpec `json:"metricsForwarding,omitzero"`

// metricsSet specifies which set of metrics to collect and forward.
// Valid values are "Telemetry", "SRE", and "All".

@everettraven everettraven Jun 9, 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.

It would be helpful for end-users that read the documentation generated from this GoDoc if you explain what happens when each of these values are set.

It might help explain to an end-user why they may want to configure this field to a specific value, which is currently unclear to me reviewing this change.

// 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.
//
// +optional
MetricsSet MetricsSet `json:"metricsSet,omitempty"`

@everettraven everettraven Jun 9, 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.

Can I set this field if metricsForwarding.mode is set to Disabled?

}

// MetricsForwardingSpec configures metrics forwarding for the hosted cluster.
// At least one field must be specified when this struct is present.
//
// +kubebuilder:validation:MinProperties=1
type MetricsForwardingSpec struct {
// mode controls whether metrics forwarding is active for this hosted cluster.
// When set to "Enabled", metrics-proxy and endpoint-resolver are deployed in the
// control plane, and a metrics-forwarder is deployed in the hosted cluster.
// When set to "Disabled" or omitted, metrics forwarding is inactive.
//
// +optional
Mode MetricsForwardingMode `json:"mode,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.

38 changes: 38 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,44 @@ 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.
minProperties: 1
properties:
mode:
description: |-
mode controls whether metrics forwarding is active for this hosted cluster.
When set to "Enabled", metrics-proxy and endpoint-resolver are deployed in the
control plane, and a metrics-forwarder is deployed in the hosted cluster.
When set to "Disabled" or omitted, metrics forwarding is inactive.
enum:
- Enabled
- Disabled
type: string
type: object
metricsSet:
description: |-
metricsSet specifies which set of metrics to collect and forward.
Valid values are "Telemetry", "SRE", and "All".
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".
enum:
- Telemetry
- SRE
- All
type: string
type: object
networking:
default:
clusterNetwork:
Expand Down
38 changes: 38 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,44 @@ 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.
minProperties: 1
properties:
mode:
description: |-
mode controls whether metrics forwarding is active for this hosted cluster.
When set to "Enabled", metrics-proxy and endpoint-resolver are deployed in the
control plane, and a metrics-forwarder is deployed in the hosted cluster.
When set to "Disabled" or omitted, metrics forwarding is inactive.
enum:
- Enabled
- Disabled
type: string
type: object
metricsSet:
description: |-
metricsSet specifies which set of metrics to collect and forward.
Valid values are "Telemetry", "SRE", and "All".
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".
enum:
- Telemetry
- SRE
- All
type: string
type: object
networking:
default:
clusterNetwork:
Expand Down
38 changes: 38 additions & 0 deletions ...manifests/hostedclusters.hypershift.openshift.io/ClusterVersionOperatorConfiguration.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2868,6 +2868,44 @@ 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.
minProperties: 1
properties:
mode:
description: |-
mode controls whether metrics forwarding is active for this hosted cluster.
When set to "Enabled", metrics-proxy and endpoint-resolver are deployed in the
control plane, and a metrics-forwarder is deployed in the hosted cluster.
When set to "Disabled" or omitted, metrics forwarding is inactive.
enum:
- Enabled
- Disabled
type: string
type: object
metricsSet:
description: |-
metricsSet specifies which set of metrics to collect and forward.
Valid values are "Telemetry", "SRE", and "All".
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".
enum:
- Telemetry
- SRE
- All
type: string
type: object
networking:
default:
clusterNetwork:
Expand Down
38 changes: 38 additions & 0 deletions ...rated.featuregated-crd-manifests/hostedclusters.hypershift.openshift.io/ExternalOIDC.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3200,6 +3200,44 @@ 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.
minProperties: 1
properties:
mode:
description: |-
mode controls whether metrics forwarding is active for this hosted cluster.
When set to "Enabled", metrics-proxy and endpoint-resolver are deployed in the
control plane, and a metrics-forwarder is deployed in the hosted cluster.
When set to "Disabled" or omitted, metrics forwarding is inactive.
enum:
- Enabled
- Disabled
type: string
type: object
metricsSet:
description: |-
metricsSet specifies which set of metrics to collect and forward.
Valid values are "Telemetry", "SRE", and "All".
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".
enum:
- Telemetry
- SRE
- All
type: string
type: object
networking:
default:
clusterNetwork:
Expand Down
38 changes: 38 additions & 0 deletions ...ests/hostedclusters.hypershift.openshift.io/ExternalOIDCWithUIDAndExtraClaimMappings.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3340,6 +3340,44 @@ 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.
minProperties: 1
properties:
mode:
description: |-
mode controls whether metrics forwarding is active for this hosted cluster.
When set to "Enabled", metrics-proxy and endpoint-resolver are deployed in the
control plane, and a metrics-forwarder is deployed in the hosted cluster.
When set to "Disabled" or omitted, metrics forwarding is inactive.
enum:
- Enabled
- Disabled
type: string
type: object
metricsSet:
description: |-
metricsSet specifies which set of metrics to collect and forward.
Valid values are "Telemetry", "SRE", and "All".
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".
enum:
- Telemetry
- SRE
- All
type: string
type: object
networking:
default:
clusterNetwork:
Expand Down
Loading