Skip to content

api: add OOB BackendUtilization #9400

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

Merged
jukie merged 13 commits into from
Jul 29, 2026
Merged

api: add OOB BackendUtilization #9400

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
b0e29a4
api: add OOB BackendUtilization
jukie Jul 1, 2026
5923722
hide fields
jukie Jul 1, 2026
9799120
regen
jukie Jul 1, 2026
bbc6f97
Merge branch 'main' into backendutilization-oob
jukie Jul 17, 2026
6556680
Merge branch 'main' into backendutilization-oob
jukie Jul 27, 2026
1757841
rename
jukie Jul 27, 2026
9e4700c
Merge branch 'main' into backendutilization-oob
jukie Jul 28, 2026
9f1fa61
Merge branch 'main' into backendutilization-oob
jukie Jul 28, 2026
7e3446a
Merge branch 'main' into backendutilization-oob
jukie Jul 28, 2026
aaa35b4
use portnumber
jukie Jul 29, 2026
92e6566
Merge branch 'main' into backendutilization-oob
jukie Jul 29, 2026
34ee3eb
feedback
jukie Jul 29, 2026
e474be6
fixes
jukie Jul 29, 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
38 changes: 38 additions & 0 deletions api/v1alpha1/loadbalancer_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,44 @@ type BackendUtilization struct {
// +optional
// +kubebuilder:default=false
KeepResponseHeaders *bool `json:"keepResponseHeaders,omitempty"`

// OOB enables out-of-band ORCA load reporting. When set, Envoy opens a
// server-streaming gRPC connection to each endpoint's
// xds.service.orca.v3.OpenRcaService/StreamCoreMetrics and pulls load
// reports periodically, instead of relying on in-band ORCA metrics
// carried in response headers/trailers.
//
// The backend must implement OpenRcaService for this to take effect.
// +optional
// +notImplementedHide
OOB *OOBReporting `json:"oob,omitempty"`
Comment thread
jukie marked this conversation as resolved.
Outdated
Comment thread
jukie marked this conversation as resolved.
Outdated
Comment thread
jukie marked this conversation as resolved.
Outdated
}

// OOBReporting configures out-of-band ORCA load reporting for the
// BackendUtilization load balancer.
//
// +notImplementedHide
type OOBReporting struct {
// ReportingPeriod is how often Envoy requests load reports from the server.
// If omitted, uses Envoy's default of 10s.
// +optional
// +notImplementedHide
ReportingPeriod *gwapiv1.Duration `json:"reportingPeriod,omitempty"`

// Port overrides the port used for the OOB reporting connection, e.g. to
// reach a separate reporting sidecar. Defaults to the endpoint's port.
// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:Maximum=65535
Comment thread
jukie marked this conversation as resolved.
// +optional
// +notImplementedHide
Port *uint32 `json:"port,omitempty"`

@zhaohuabing zhaohuabing Jul 29, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Should use gwapiv1.PortNumber

@jukie jukie Jul 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Thanks! Fixed

@jukie jukie Jul 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@zhaohuabing I ended up reverting this back to *int32. We only use it in one other place currently vs int32 for 8 other port fields and it breaks the kubebuilder bounds setup.

@jukie jukie Jul 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I'm going to merge this but will ping you on the implementation PR in case you'd still prefer to use PortNumber


// Authority overrides the :authority header on the OOB gRPC stream.
//
// +kubebuilder:validation:Pattern=`^[^\x00\n\r]*$`
// +optional
// +notImplementedHide
Authority *string `json:"authority,omitempty"`
}

// DynamicModuleLBPolicy configures a custom load balancing algorithm
Expand Down
35 changes: 35 additions & 0 deletions api/v1alpha1/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.

30 changes: 30 additions & 0 deletions ...s/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1102,6 +1102,36 @@ spec:
items:
type: string
type: array
oob:
description: |-
OOB enables out-of-band ORCA load reporting. When set, Envoy opens a
server-streaming gRPC connection to each endpoint's
xds.service.orca.v3.OpenRcaService/StreamCoreMetrics and pulls load
reports periodically, instead of relying on in-band ORCA metrics
carried in response headers/trailers.

The backend must implement OpenRcaService for this to take effect.
properties:
authority:
description: Authority overrides the :authority header
on the OOB gRPC stream.
pattern: ^[^\x00\n\r]*$
type: string
port:
description: |-
Port overrides the port used for the OOB reporting connection, e.g. to
reach a separate reporting sidecar. Defaults to the endpoint's port.
format: int32
maximum: 65535
minimum: 1
type: integer
reportingPeriod:
description: |-
ReportingPeriod is how often Envoy requests load reports from the server.
If omitted, uses Envoy's default of 10s.
pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
type: string
type: object
weightExpirationPeriod:
description: If a given endpoint has not reported load metrics
in this long, stop using the reported weight. Defaults to
Expand Down
30 changes: 30 additions & 0 deletions ...s/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -977,6 +977,36 @@ spec:
items:
type: string
type: array
oob:
description: |-
OOB enables out-of-band ORCA load reporting. When set, Envoy opens a
server-streaming gRPC connection to each endpoint's
xds.service.orca.v3.OpenRcaService/StreamCoreMetrics and pulls load
reports periodically, instead of relying on in-band ORCA metrics
carried in response headers/trailers.

The backend must implement OpenRcaService for this to take effect.
properties:
authority:
description: Authority overrides the :authority
header on the OOB gRPC stream.
pattern: ^[^\x00\n\r]*$
type: string
port:
description: |-
Port overrides the port used for the OOB reporting connection, e.g. to
reach a separate reporting sidecar. Defaults to the endpoint's port.
format: int32
maximum: 65535
minimum: 1
type: integer
reportingPeriod:
description: |-
ReportingPeriod is how often Envoy requests load reports from the server.
If omitted, uses Envoy's default of 10s.
pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
type: string
type: object
weightExpirationPeriod:
description: If a given endpoint has not reported
load metrics in this long, stop using the reported
Expand Down
123 changes: 123 additions & 0 deletions charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12314,6 +12314,37 @@ spec:
items:
type: string
type: array
oob:
description: |-
OOB enables out-of-band ORCA load reporting. When set, Envoy opens a
server-streaming gRPC connection to each endpoint's
xds.service.orca.v3.OpenRcaService/StreamCoreMetrics and pulls load
reports periodically, instead of relying on in-band ORCA metrics
carried in response headers/trailers.

The backend must implement OpenRcaService for this to take effect.
properties:
authority:
description: Authority overrides
the :authority header on
the OOB gRPC stream.
pattern: ^[^\x00\n\r]*$
type: string
port:
description: |-
Port overrides the port used for the OOB reporting connection, e.g. to
reach a separate reporting sidecar. Defaults to the endpoint's port.
format: int32
maximum: 65535
minimum: 1
type: integer
reportingPeriod:
description: |-
ReportingPeriod is how often Envoy requests load reports from the server.
If omitted, uses Envoy's default of 10s.
pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
type: string
type: object
weightExpirationPeriod:
description: If a given endpoint
has not reported load metrics
Expand Down Expand Up @@ -13893,6 +13924,37 @@ spec:
items:
type: string
type: array
oob:
description: |-
OOB enables out-of-band ORCA load reporting. When set, Envoy opens a
server-streaming gRPC connection to each endpoint's
xds.service.orca.v3.OpenRcaService/StreamCoreMetrics and pulls load
reports periodically, instead of relying on in-band ORCA metrics
carried in response headers/trailers.

The backend must implement OpenRcaService for this to take effect.
properties:
authority:
description: Authority overrides
the :authority header on
the OOB gRPC stream.
pattern: ^[^\x00\n\r]*$
type: string
port:
description: |-
Port overrides the port used for the OOB reporting connection, e.g. to
reach a separate reporting sidecar. Defaults to the endpoint's port.
format: int32
maximum: 65535
minimum: 1
type: integer
reportingPeriod:
description: |-
ReportingPeriod is how often Envoy requests load reports from the server.
If omitted, uses Envoy's default of 10s.
pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
type: string
type: object
weightExpirationPeriod:
description: If a given endpoint
has not reported load metrics
Expand Down Expand Up @@ -15638,6 +15700,37 @@ spec:
items:
type: string
type: array
oob:
description: |-
OOB enables out-of-band ORCA load reporting. When set, Envoy opens a
server-streaming gRPC connection to each endpoint's
xds.service.orca.v3.OpenRcaService/StreamCoreMetrics and pulls load
reports periodically, instead of relying on in-band ORCA metrics
carried in response headers/trailers.

The backend must implement OpenRcaService for this to take effect.
properties:
authority:
description: Authority overrides
the :authority header on the OOB
gRPC stream.
pattern: ^[^\x00\n\r]*$
type: string
port:
description: |-
Port overrides the port used for the OOB reporting connection, e.g. to
reach a separate reporting sidecar. Defaults to the endpoint's port.
format: int32
maximum: 65535
minimum: 1
type: integer
reportingPeriod:
description: |-
ReportingPeriod is how often Envoy requests load reports from the server.
If omitted, uses Envoy's default of 10s.
pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
type: string
type: object
weightExpirationPeriod:
description: If a given endpoint has
not reported load metrics in this
Expand Down Expand Up @@ -17289,6 +17382,36 @@ spec:
items:
type: string
type: array
oob:
description: |-
OOB enables out-of-band ORCA load reporting. When set, Envoy opens a
server-streaming gRPC connection to each endpoint's
xds.service.orca.v3.OpenRcaService/StreamCoreMetrics and pulls load
reports periodically, instead of relying on in-band ORCA metrics
carried in response headers/trailers.

The backend must implement OpenRcaService for this to take effect.
properties:
authority:
description: Authority overrides the :authority
header on the OOB gRPC stream.
pattern: ^[^\x00\n\r]*$
type: string
port:
description: |-
Port overrides the port used for the OOB reporting connection, e.g. to
reach a separate reporting sidecar. Defaults to the endpoint's port.
format: int32
maximum: 65535
minimum: 1
type: integer
reportingPeriod:
description: |-
ReportingPeriod is how often Envoy requests load reports from the server.
If omitted, uses Envoy's default of 10s.
pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
type: string
type: object
weightExpirationPeriod:
description: If a given endpoint has not reported
load metrics in this long, stop using the
Expand Down
Loading
Loading