From b0e29a46789616b50e9491399745317c3536b648 Mon Sep 17 00:00:00 2001 From: jukie <10012479+jukie@users.noreply.github.com> Date: Wed, 1 Jul 2026 12:37:24 -0600 Subject: [PATCH 1/7] api: add OOB BackendUtilization Signed-off-by: jukie <10012479+jukie@users.noreply.github.com> --- api/v1alpha1/loadbalancer_types.go | 32 ++ api/v1alpha1/zz_generated.deepcopy.go | 35 ++ ....envoyproxy.io_backendtrafficpolicies.yaml | 30 ++ ....envoyproxy.io_envoyextensionpolicies.yaml | 30 ++ .../gateway.envoyproxy.io_envoyproxies.yaml | 123 +++++++ ...ateway.envoyproxy.io_securitypolicies.yaml | 121 +++++++ ....envoyproxy.io_backendtrafficpolicies.yaml | 30 ++ ....envoyproxy.io_envoyextensionpolicies.yaml | 30 ++ .../gateway.envoyproxy.io_envoyproxies.yaml | 123 +++++++ ...ateway.envoyproxy.io_securitypolicies.yaml | 121 +++++++ site/content/en/latest/api/extension_types.md | 18 ++ .../tasks/traffic/backend-utilization.md | 32 ++ .../backendtrafficpolicy_test.go | 104 ++++++ test/helm/gateway-crds-helm/all.out.yaml | 304 ++++++++++++++++++ test/helm/gateway-crds-helm/e2e.out.yaml | 304 ++++++++++++++++++ .../envoy-gateway-crds.out.yaml | 304 ++++++++++++++++++ 16 files changed, 1741 insertions(+) diff --git a/api/v1alpha1/loadbalancer_types.go b/api/v1alpha1/loadbalancer_types.go index 3fe06579b1..10cb6fcb59 100644 --- a/api/v1alpha1/loadbalancer_types.go +++ b/api/v1alpha1/loadbalancer_types.go @@ -229,6 +229,38 @@ 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 + OOB *OOBReporting `json:"oob,omitempty"` +} + +// OOBReporting configures out-of-band ORCA load reporting for the +// BackendUtilization load balancer. +type OOBReporting struct { + // ReportingPeriod is how often Envoy requests load reports from the server. + // If omitted, uses Envoy's default of 10s. + // +optional + 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 + // +optional + Port *uint32 `json:"port,omitempty"` + + // Authority overrides the :authority header on the OOB gRPC stream. + // + // +kubebuilder:validation:Pattern=`^[^\x00\n\r]*$` + // +optional + Authority *string `json:"authority,omitempty"` } // DynamicModuleLBPolicy configures a custom load balancing algorithm diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go index a566e3c1df..d262225f62 100644 --- a/api/v1alpha1/zz_generated.deepcopy.go +++ b/api/v1alpha1/zz_generated.deepcopy.go @@ -941,6 +941,11 @@ func (in *BackendUtilization) DeepCopyInto(out *BackendUtilization) { *out = new(bool) **out = **in } + if in.OOB != nil { + in, out := &in.OOB, &out.OOB + *out = new(OOBReporting) + (*in).DeepCopyInto(*out) + } } // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BackendUtilization. @@ -6192,6 +6197,36 @@ func (in *OIDCTokenForwarding) DeepCopy() *OIDCTokenForwarding { return out } +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *OOBReporting) DeepCopyInto(out *OOBReporting) { + *out = *in + if in.ReportingPeriod != nil { + in, out := &in.ReportingPeriod, &out.ReportingPeriod + *out = new(v1.Duration) + **out = **in + } + if in.Port != nil { + in, out := &in.Port, &out.Port + *out = new(uint32) + **out = **in + } + if in.Authority != nil { + in, out := &in.Authority, &out.Authority + *out = new(string) + **out = **in + } +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new OOBReporting. +func (in *OOBReporting) DeepCopy() *OOBReporting { + if in == nil { + return nil + } + out := new(OOBReporting) + in.DeepCopyInto(out) + return out +} + // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *OTelSampler) DeepCopyInto(out *OTelSampler) { *out = *in diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml index 72e4b69d56..c3a9def7f2 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml @@ -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 diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml index 69a2983a50..5c0431c96f 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml @@ -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 diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml index 93db35107b..07030f3152 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml index 6eba7e7eb4..4d764a8385 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml @@ -1680,6 +1680,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 @@ -3125,6 +3155,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 @@ -4862,6 +4922,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 long, stop @@ -6616,6 +6707,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 diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml index a79ec46e60..c8af5a9421 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml @@ -1101,6 +1101,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 diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml index 0a6a06e25a..544884e64a 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml @@ -976,6 +976,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 diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml index eafaa9486a..a2a1e74e84 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml @@ -12313,6 +12313,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 @@ -13892,6 +13923,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 @@ -15637,6 +15699,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 @@ -17288,6 +17381,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 diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml index 3f1ec675ff..5eb0237110 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml @@ -1679,6 +1679,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 @@ -3124,6 +3154,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 @@ -4861,6 +4921,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 long, stop @@ -6615,6 +6706,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 diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md index 8c78804007..14ed15b6fc 100644 --- a/site/content/en/latest/api/extension_types.md +++ b/site/content/en/latest/api/extension_types.md @@ -643,6 +643,7 @@ _Appears in:_ | `errorUtilizationPenaltyPercent` | _integer_ | false | | ErrorUtilizationPenaltyPercent adjusts endpoint weights based on the error rate (eps/qps).
This is expressed as a percentage-based integer where 100 represents 1.0, 150 represents 1.5, etc.
For example:
- 100 => 1.0x
- 120 => 1.2x
- 200 => 2.0x
Must be non-negative. | | `metricNamesForComputingUtilization` | _string array_ | false | | Metric names used to compute utilization if application_utilization is not set.
For map fields in ORCA proto, use the form ".", e.g., "named_metrics.foo". | | `keepResponseHeaders` | _boolean_ | false | false | KeepResponseHeaders keeps the ORCA load report headers/trailers before sending the response to the client.
Defaults to false. | +| `oob` | _[OOBReporting](#oobreporting)_ | false | | 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. | #### BandwidthLimitRequestConfig @@ -4336,6 +4337,23 @@ _Appears in:_ | `header` | _string_ | true | | Header is the upstream request header that will carry the ID token. | +#### OOBReporting + + + +OOBReporting configures out-of-band ORCA load reporting for the +BackendUtilization load balancer. + +_Appears in:_ +- [BackendUtilization](#backendutilization) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `reportingPeriod` | _[Duration](https://gateway-api.sigs.k8s.io/reference/api-spec/1.5/spec/#duration)_ | false | | ReportingPeriod is how often Envoy requests load reports from the server.
If omitted, uses Envoy's default of 10s. | +| `port` | _integer_ | false | | Port overrides the port used for the OOB reporting connection, e.g. to
reach a separate reporting sidecar. Defaults to the endpoint's port. | +| `authority` | _string_ | false | | Authority overrides the :authority header on the OOB gRPC stream. | + + #### OTelSampler diff --git a/site/content/en/latest/tasks/traffic/backend-utilization.md b/site/content/en/latest/tasks/traffic/backend-utilization.md index adbd19f787..4e96c97e76 100644 --- a/site/content/en/latest/tasks/traffic/backend-utilization.md +++ b/site/content/en/latest/tasks/traffic/backend-utilization.md @@ -121,6 +121,7 @@ All fields on `backendUtilization` are optional. | `errorUtilizationPenaltyPercent` | `0` | Multiplier (as `percent × 100`) applied to an endpoint's effective utilization based on its error rate (eps/qps). `100` = 1.0×, `150` = 1.5×, `200` = 2.0×. Higher values push errant endpoints out of rotation faster. | | `metricNamesForComputingUtilization` | _unset_ | Custom ORCA metric keys to feed into the weight formula when `application_utilization` isn't reported. Use `named_metrics.` for keys inside the ORCA proto's `named_metrics` map. | | `keepResponseHeaders` | `false` | By default Envoy strips the ORCA headers/trailers before forwarding the response. Set to `true` to let downstream clients see them (useful for chained load balancers or debugging). | +| `oob` | _unset_ | Enables [out-of-band ORCA reporting](#out-of-band-oob-reporting) — Envoy streams load reports from the endpoint's `OpenRcaService` instead of relying only on in-band response headers. | ### Example: Tuned for a Bursty Backend @@ -164,6 +165,36 @@ Your backend must emit ORCA load metrics. Envoy accepts metrics in three formats For gRPC backends, the [xDS ORCA][grpc-orca] libraries emit these automatically via the `orca_load_report` service. For HTTP backends, add a response middleware that measures and serializes your CPU/memory/custom metrics on each response. +## Out-of-Band (OOB) Reporting + +By default Envoy reads ORCA metrics **in-band** — from the response headers or trailers of regular requests (see [Backend Instrumentation](#backend-instrumentation) above). With out-of-band (OOB) reporting, Envoy instead opens a dedicated server-streaming gRPC connection to each endpoint's [`OpenRcaService`][open-rca] (`xds.service.orca.v3.OpenRcaService/StreamCoreMetrics`) and receives load reports on a fixed schedule, independent of request traffic. + +OOB reporting is useful when: + +* Request volume is low or bursty, so in-band samples arrive too infrequently to weight endpoints well. +* You want load signals even for endpoints that are currently idle. +* A separate reporting sidecar exposes the ORCA stream on its own port. + +Enable it by adding an `oob` block. Its presence turns OOB on; an empty `oob: {}` enables it with Envoy's defaults. In-band metrics (and `keepResponseHeaders`) continue to be honored alongside OOB. + +```yaml +loadBalancer: + type: BackendUtilization + backendUtilization: + oob: + reportingPeriod: 5s # how often Envoy requests a report (default 10s) + port: 9001 # optional: reach a reporting sidecar on a different port + authority: orca.local # optional: :authority header for the OOB gRPC stream +``` + +| Field | Default | Purpose | +|---|---|---| +| `oob.reportingPeriod` | `10s` | How often Envoy requests a load report from the endpoint. The server may report less frequently than requested. | +| `oob.port` | endpoint port | Alternative port for the OOB reporting connection, e.g. a dedicated reporting sidecar. Must be between `1` and `65535`. | +| `oob.authority` | _unset_ | Overrides the `:authority` header on the OOB gRPC stream. | + +Your backend must implement the `OpenRcaService` streaming RPC for OOB to take effect. gRPC backends can use the [xDS ORCA][grpc-orca] server libraries; the same [`OrcaLoadReport`][orca-proto] message carries both in-band and OOB reports. + ## Combining With Zone-Aware Routing `BackendUtilization` composes with `weightedZones` to produce locality-aware weighted round-robin (Envoy's `wrr_locality` policy). See the [WeightedZones example][zone-aware-weighted] on the zone-aware routing page. @@ -212,6 +243,7 @@ kubectl delete -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/ex [orca-proto]: https://www.envoyproxy.io/docs/envoy/latest/xds/data/orca/v3/orca_load_report.proto [client-side-wrr]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto [grpc-orca]: https://github.com/grpc/proposal/blob/master/A51-custom-backend-metrics.md +[open-rca]: https://github.com/cncf/xds/blob/main/xds/service/orca/v3/orca.proto [concepts-lb]: ../../../concepts/load-balancing#backend-utilization-orca [zone-aware-weighted]: ../zone-aware-routing#weightedzones [BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy diff --git a/test/cel-validation/backendtrafficpolicy_test.go b/test/cel-validation/backendtrafficpolicy_test.go index 6bd00eb1c0..936e8f9982 100644 --- a/test/cel-validation/backendtrafficpolicy_test.go +++ b/test/cel-validation/backendtrafficpolicy_test.go @@ -840,6 +840,110 @@ func TestBackendTrafficPolicyTarget(t *testing.T) { }, wantErrors: []string{}, }, + { + desc: "backendUtilization with OOB fields is valid", + mutate: func(btp *egv1a1.BackendTrafficPolicy) { + btp.Spec = egv1a1.BackendTrafficPolicySpec{ + PolicyTargetReferences: egv1a1.PolicyTargetReferences{ + TargetRef: &gwapiv1.LocalPolicyTargetReferenceWithSectionName{ + LocalPolicyTargetReference: gwapiv1.LocalPolicyTargetReference{ + Group: gwapiv1.Group("gateway.networking.k8s.io"), + Kind: gwapiv1.Kind("Gateway"), + Name: gwapiv1.ObjectName("eg"), + }, + }, + }, + ClusterSettings: egv1a1.ClusterSettings{ + LoadBalancer: &egv1a1.LoadBalancer{ + Type: egv1a1.BackendUtilizationLoadBalancerType, + BackendUtilization: &egv1a1.BackendUtilization{ + OOB: &egv1a1.OOBReporting{ + ReportingPeriod: new(gwapiv1.Duration("5s")), + Port: new(uint32(9001)), + Authority: new("orca.local"), + }, + }, + }, + }, + } + }, + wantErrors: []string{}, + }, + { + desc: "backendUtilization OOB port zero is rejected", + mutate: func(btp *egv1a1.BackendTrafficPolicy) { + btp.Spec = egv1a1.BackendTrafficPolicySpec{ + PolicyTargetReferences: egv1a1.PolicyTargetReferences{ + TargetRef: &gwapiv1.LocalPolicyTargetReferenceWithSectionName{ + LocalPolicyTargetReference: gwapiv1.LocalPolicyTargetReference{ + Group: gwapiv1.Group("gateway.networking.k8s.io"), + Kind: gwapiv1.Kind("Gateway"), + Name: gwapiv1.ObjectName("eg"), + }, + }, + }, + ClusterSettings: egv1a1.ClusterSettings{ + LoadBalancer: &egv1a1.LoadBalancer{ + Type: egv1a1.BackendUtilizationLoadBalancerType, + BackendUtilization: &egv1a1.BackendUtilization{ + OOB: &egv1a1.OOBReporting{Port: new(uint32(0))}, + }, + }, + }, + } + }, + wantErrors: []string{"spec.loadBalancer.backendUtilization.oob.port"}, + }, + { + desc: "backendUtilization OOB port above max is rejected", + mutate: func(btp *egv1a1.BackendTrafficPolicy) { + btp.Spec = egv1a1.BackendTrafficPolicySpec{ + PolicyTargetReferences: egv1a1.PolicyTargetReferences{ + TargetRef: &gwapiv1.LocalPolicyTargetReferenceWithSectionName{ + LocalPolicyTargetReference: gwapiv1.LocalPolicyTargetReference{ + Group: gwapiv1.Group("gateway.networking.k8s.io"), + Kind: gwapiv1.Kind("Gateway"), + Name: gwapiv1.ObjectName("eg"), + }, + }, + }, + ClusterSettings: egv1a1.ClusterSettings{ + LoadBalancer: &egv1a1.LoadBalancer{ + Type: egv1a1.BackendUtilizationLoadBalancerType, + BackendUtilization: &egv1a1.BackendUtilization{ + OOB: &egv1a1.OOBReporting{Port: new(uint32(70000))}, + }, + }, + }, + } + }, + wantErrors: []string{"spec.loadBalancer.backendUtilization.oob.port"}, + }, + { + desc: "backendUtilization OOB authority with newline is rejected", + mutate: func(btp *egv1a1.BackendTrafficPolicy) { + btp.Spec = egv1a1.BackendTrafficPolicySpec{ + PolicyTargetReferences: egv1a1.PolicyTargetReferences{ + TargetRef: &gwapiv1.LocalPolicyTargetReferenceWithSectionName{ + LocalPolicyTargetReference: gwapiv1.LocalPolicyTargetReference{ + Group: gwapiv1.Group("gateway.networking.k8s.io"), + Kind: gwapiv1.Kind("Gateway"), + Name: gwapiv1.ObjectName("eg"), + }, + }, + }, + ClusterSettings: egv1a1.ClusterSettings{ + LoadBalancer: &egv1a1.LoadBalancer{ + Type: egv1a1.BackendUtilizationLoadBalancerType, + BackendUtilization: &egv1a1.BackendUtilization{ + OOB: &egv1a1.OOBReporting{Authority: new("foo\nbar")}, + }, + }, + }, + } + }, + wantErrors: []string{"spec.loadBalancer.backendUtilization.oob.authority"}, + }, { desc: "backendUtilization field nil when type is BackendUtilization", mutate: func(btp *egv1a1.BackendTrafficPolicy) { diff --git a/test/helm/gateway-crds-helm/all.out.yaml b/test/helm/gateway-crds-helm/all.out.yaml index 84c0c0a573..605617d8cc 100644 --- a/test/helm/gateway-crds-helm/all.out.yaml +++ b/test/helm/gateway-crds-helm/all.out.yaml @@ -25719,6 +25719,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 @@ -31476,6 +31506,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 @@ -45928,6 +45988,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 @@ -47507,6 +47598,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 @@ -49252,6 +49374,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 @@ -50903,6 +51056,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 @@ -54077,6 +54260,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 @@ -55522,6 +55735,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 @@ -57259,6 +57502,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 long, stop @@ -59013,6 +59287,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 diff --git a/test/helm/gateway-crds-helm/e2e.out.yaml b/test/helm/gateway-crds-helm/e2e.out.yaml index 942eab31a4..598a22d470 100644 --- a/test/helm/gateway-crds-helm/e2e.out.yaml +++ b/test/helm/gateway-crds-helm/e2e.out.yaml @@ -1657,6 +1657,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 @@ -7414,6 +7444,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 @@ -21866,6 +21926,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 @@ -23445,6 +23536,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 @@ -25190,6 +25312,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 @@ -26841,6 +26994,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 @@ -30015,6 +30198,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 @@ -31460,6 +31673,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 @@ -33197,6 +33440,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 long, stop @@ -34951,6 +35225,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 diff --git a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml index 276e43f622..3f40b27a95 100644 --- a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml +++ b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml @@ -1657,6 +1657,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 @@ -7414,6 +7444,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 @@ -21866,6 +21926,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 @@ -23445,6 +23536,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 @@ -25190,6 +25312,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 @@ -26841,6 +26994,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 @@ -30015,6 +30198,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 @@ -31460,6 +31673,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 @@ -33197,6 +33440,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 long, stop @@ -34951,6 +35225,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 From 5923722febb31f48e847831f2db946d399290567 Mon Sep 17 00:00:00 2001 From: jukie <10012479+jukie@users.noreply.github.com> Date: Wed, 1 Jul 2026 12:55:32 -0600 Subject: [PATCH 2/7] hide fields Signed-off-by: jukie <10012479+jukie@users.noreply.github.com> --- api/v1alpha1/loadbalancer_types.go | 6 ++++++ site/content/en/latest/api/extension_types.md | 1 - 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/api/v1alpha1/loadbalancer_types.go b/api/v1alpha1/loadbalancer_types.go index 10cb6fcb59..f3905b5e6d 100644 --- a/api/v1alpha1/loadbalancer_types.go +++ b/api/v1alpha1/loadbalancer_types.go @@ -238,15 +238,19 @@ type BackendUtilization struct { // // The backend must implement OpenRcaService for this to take effect. // +optional + // +notImplementedHide OOB *OOBReporting `json:"oob,omitempty"` } // 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 @@ -254,12 +258,14 @@ type OOBReporting struct { // +kubebuilder:validation:Minimum=1 // +kubebuilder:validation:Maximum=65535 // +optional + // +notImplementedHide Port *uint32 `json:"port,omitempty"` // Authority overrides the :authority header on the OOB gRPC stream. // // +kubebuilder:validation:Pattern=`^[^\x00\n\r]*$` // +optional + // +notImplementedHide Authority *string `json:"authority,omitempty"` } diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md index 14ed15b6fc..bd078eeb86 100644 --- a/site/content/en/latest/api/extension_types.md +++ b/site/content/en/latest/api/extension_types.md @@ -643,7 +643,6 @@ _Appears in:_ | `errorUtilizationPenaltyPercent` | _integer_ | false | | ErrorUtilizationPenaltyPercent adjusts endpoint weights based on the error rate (eps/qps).
This is expressed as a percentage-based integer where 100 represents 1.0, 150 represents 1.5, etc.
For example:
- 100 => 1.0x
- 120 => 1.2x
- 200 => 2.0x
Must be non-negative. | | `metricNamesForComputingUtilization` | _string array_ | false | | Metric names used to compute utilization if application_utilization is not set.
For map fields in ORCA proto, use the form ".", e.g., "named_metrics.foo". | | `keepResponseHeaders` | _boolean_ | false | false | KeepResponseHeaders keeps the ORCA load report headers/trailers before sending the response to the client.
Defaults to false. | -| `oob` | _[OOBReporting](#oobreporting)_ | false | | 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. | #### BandwidthLimitRequestConfig From 9799120e97629341b51cdde0cc5471e322973f63 Mon Sep 17 00:00:00 2001 From: jukie <10012479+jukie@users.noreply.github.com> Date: Wed, 1 Jul 2026 13:05:26 -0600 Subject: [PATCH 3/7] regen Signed-off-by: jukie <10012479+jukie@users.noreply.github.com> --- site/content/en/latest/api/extension_types.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md index bd078eeb86..fe8666cbc5 100644 --- a/site/content/en/latest/api/extension_types.md +++ b/site/content/en/latest/api/extension_types.md @@ -4348,9 +4348,6 @@ _Appears in:_ | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | -| `reportingPeriod` | _[Duration](https://gateway-api.sigs.k8s.io/reference/api-spec/1.5/spec/#duration)_ | false | | ReportingPeriod is how often Envoy requests load reports from the server.
If omitted, uses Envoy's default of 10s. | -| `port` | _integer_ | false | | Port overrides the port used for the OOB reporting connection, e.g. to
reach a separate reporting sidecar. Defaults to the endpoint's port. | -| `authority` | _string_ | false | | Authority overrides the :authority header on the OOB gRPC stream. | #### OTelSampler From 17578413a2088dda0d537cae0cccfd6ac7305297 Mon Sep 17 00:00:00 2001 From: jukie <10012479+jukie@users.noreply.github.com> Date: Mon, 27 Jul 2026 10:40:01 -0600 Subject: [PATCH 4/7] rename Signed-off-by: jukie <10012479+jukie@users.noreply.github.com> --- api/v1alpha1/loadbalancer_types.go | 12 +-- api/v1alpha1/zz_generated.deepcopy.go | 66 +++++++-------- ....envoyproxy.io_backendtrafficpolicies.yaml | 8 +- ....envoyproxy.io_envoyextensionpolicies.yaml | 8 +- .../gateway.envoyproxy.io_envoyproxies.yaml | 32 ++++---- ...ateway.envoyproxy.io_securitypolicies.yaml | 34 ++++---- ....envoyproxy.io_backendtrafficpolicies.yaml | 8 +- ....envoyproxy.io_envoyextensionpolicies.yaml | 8 +- .../gateway.envoyproxy.io_envoyproxies.yaml | 32 ++++---- ...ateway.envoyproxy.io_securitypolicies.yaml | 34 ++++---- site/content/en/latest/api/extension_types.md | 28 +++---- .../backendtrafficpolicy_test.go | 22 ++--- test/helm/gateway-crds-helm/all.out.yaml | 82 +++++++++---------- test/helm/gateway-crds-helm/e2e.out.yaml | 82 +++++++++---------- .../envoy-gateway-crds.out.yaml | 82 +++++++++---------- 15 files changed, 269 insertions(+), 269 deletions(-) diff --git a/api/v1alpha1/loadbalancer_types.go b/api/v1alpha1/loadbalancer_types.go index f3905b5e6d..40cac9e516 100644 --- a/api/v1alpha1/loadbalancer_types.go +++ b/api/v1alpha1/loadbalancer_types.go @@ -230,7 +230,7 @@ type BackendUtilization struct { // +kubebuilder:default=false KeepResponseHeaders *bool `json:"keepResponseHeaders,omitempty"` - // OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + // OutOfBand 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 @@ -239,21 +239,21 @@ type BackendUtilization struct { // The backend must implement OpenRcaService for this to take effect. // +optional // +notImplementedHide - OOB *OOBReporting `json:"oob,omitempty"` + OutOfBand *OutOfBandReporting `json:"outOfBand,omitempty"` } -// OOBReporting configures out-of-band ORCA load reporting for the +// OutOfBandReporting configures out-of-band ORCA load reporting for the // BackendUtilization load balancer. // // +notImplementedHide -type OOBReporting struct { +type OutOfBandReporting 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 + // Port overrides the port used for the OutOfBand reporting connection, e.g. to // reach a separate reporting sidecar. Defaults to the endpoint's port. // +kubebuilder:validation:Minimum=1 // +kubebuilder:validation:Maximum=65535 @@ -261,7 +261,7 @@ type OOBReporting struct { // +notImplementedHide Port *uint32 `json:"port,omitempty"` - // Authority overrides the :authority header on the OOB gRPC stream. + // Authority overrides the :authority header on the OutOfBand gRPC stream. // // +kubebuilder:validation:Pattern=`^[^\x00\n\r]*$` // +optional diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go index 66cb7a9684..5bc83e9165 100644 --- a/api/v1alpha1/zz_generated.deepcopy.go +++ b/api/v1alpha1/zz_generated.deepcopy.go @@ -941,9 +941,9 @@ func (in *BackendUtilization) DeepCopyInto(out *BackendUtilization) { *out = new(bool) **out = **in } - if in.OOB != nil { - in, out := &in.OOB, &out.OOB - *out = new(OOBReporting) + if in.OutOfBand != nil { + in, out := &in.OutOfBand, &out.OutOfBand + *out = new(OutOfBandReporting) (*in).DeepCopyInto(*out) } } @@ -6262,36 +6262,6 @@ func (in *OIDCTokenForwarding) DeepCopy() *OIDCTokenForwarding { return out } -// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. -func (in *OOBReporting) DeepCopyInto(out *OOBReporting) { - *out = *in - if in.ReportingPeriod != nil { - in, out := &in.ReportingPeriod, &out.ReportingPeriod - *out = new(v1.Duration) - **out = **in - } - if in.Port != nil { - in, out := &in.Port, &out.Port - *out = new(uint32) - **out = **in - } - if in.Authority != nil { - in, out := &in.Authority, &out.Authority - *out = new(string) - **out = **in - } -} - -// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new OOBReporting. -func (in *OOBReporting) DeepCopy() *OOBReporting { - if in == nil { - return nil - } - out := new(OOBReporting) - in.DeepCopyInto(out) - return out -} - // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *OTelSampler) DeepCopyInto(out *OTelSampler) { *out = *in @@ -6425,6 +6395,36 @@ func (in *OtherSANMatch) DeepCopy() *OtherSANMatch { return out } +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *OutOfBandReporting) DeepCopyInto(out *OutOfBandReporting) { + *out = *in + if in.ReportingPeriod != nil { + in, out := &in.ReportingPeriod, &out.ReportingPeriod + *out = new(v1.Duration) + **out = **in + } + if in.Port != nil { + in, out := &in.Port, &out.Port + *out = new(uint32) + **out = **in + } + if in.Authority != nil { + in, out := &in.Authority, &out.Authority + *out = new(string) + **out = **in + } +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new OutOfBandReporting. +func (in *OutOfBandReporting) DeepCopy() *OutOfBandReporting { + if in == nil { + return nil + } + out := new(OutOfBandReporting) + in.DeepCopyInto(out) + return out +} + // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *PassiveHealthCheck) DeepCopyInto(out *PassiveHealthCheck) { *out = *in diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml index 83e961f3c1..b99aad6a04 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml @@ -1102,9 +1102,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -1114,12 +1114,12 @@ spec: properties: authority: description: Authority overrides the :authority header - on the OOB gRPC stream. + on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml index 8f36d66f5b..7d4228678b 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml @@ -977,9 +977,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -989,12 +989,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml index e75ecb050f..c6ad2cbf8a 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml @@ -12316,9 +12316,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -12329,12 +12329,12 @@ spec: authority: description: Authority overrides the :authority header on - the OOB gRPC stream. + the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -13926,9 +13926,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -13939,12 +13939,12 @@ spec: authority: description: Authority overrides the :authority header on - the OOB gRPC stream. + the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -15702,9 +15702,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -15714,13 +15714,13 @@ spec: properties: authority: description: Authority overrides - the :authority header on the OOB + the :authority header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -17426,9 +17426,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -17438,12 +17438,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml index b575aa1e84..7f33b38a97 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml @@ -1683,9 +1683,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -1695,12 +1695,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -3158,9 +3158,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -3170,12 +3170,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -4941,9 +4941,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -4953,13 +4953,13 @@ spec: properties: authority: description: Authority overrides the - :authority header on the OOB gRPC - stream. + :authority header on the OutOfBand + gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -6744,9 +6744,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -6756,12 +6756,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml index ff2f4c5d63..f5deefbc24 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml @@ -1101,9 +1101,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -1113,12 +1113,12 @@ spec: properties: authority: description: Authority overrides the :authority header - on the OOB gRPC stream. + on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml index ad51ac1ffd..074214d914 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml @@ -976,9 +976,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -988,12 +988,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml index ec358222c1..9a26adb2f4 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml @@ -12315,9 +12315,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -12328,12 +12328,12 @@ spec: authority: description: Authority overrides the :authority header on - the OOB gRPC stream. + the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -13925,9 +13925,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -13938,12 +13938,12 @@ spec: authority: description: Authority overrides the :authority header on - the OOB gRPC stream. + the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -15701,9 +15701,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -15713,13 +15713,13 @@ spec: properties: authority: description: Authority overrides - the :authority header on the OOB + the :authority header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -17425,9 +17425,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -17437,12 +17437,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml index eeb015f750..964b149323 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml @@ -1682,9 +1682,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -1694,12 +1694,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -3157,9 +3157,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -3169,12 +3169,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -4940,9 +4940,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -4952,13 +4952,13 @@ spec: properties: authority: description: Authority overrides the - :authority header on the OOB gRPC - stream. + :authority header on the OutOfBand + gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -6743,9 +6743,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -6755,12 +6755,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md index 3f531683c8..d5184359e8 100644 --- a/site/content/en/latest/api/extension_types.md +++ b/site/content/en/latest/api/extension_types.md @@ -4375,20 +4375,6 @@ _Appears in:_ | `header` | _string_ | true | | Header is the upstream request header that will carry the ID token.
It must be a valid HTTP header name. Pseudo-headers (names starting with ":")
and the "Host" header are not allowed. | -#### OOBReporting - - - -OOBReporting configures out-of-band ORCA load reporting for the -BackendUtilization load balancer. - -_Appears in:_ -- [BackendUtilization](#backendutilization) - -| Field | Type | Required | Default | Description | -| --- | --- | --- | --- | --- | - - #### OTelSampler @@ -4518,6 +4504,20 @@ _Appears in:_ | `value` | _string_ | true | | Value specifies the string value that the match must have. | +#### OutOfBandReporting + + + +OutOfBandReporting configures out-of-band ORCA load reporting for the +BackendUtilization load balancer. + +_Appears in:_ +- [BackendUtilization](#backendutilization) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | + + #### PassiveHealthCheck diff --git a/test/cel-validation/backendtrafficpolicy_test.go b/test/cel-validation/backendtrafficpolicy_test.go index fcd748766c..0170b28c3f 100644 --- a/test/cel-validation/backendtrafficpolicy_test.go +++ b/test/cel-validation/backendtrafficpolicy_test.go @@ -841,7 +841,7 @@ func TestBackendTrafficPolicyTarget(t *testing.T) { wantErrors: []string{}, }, { - desc: "backendUtilization with OOB fields is valid", + desc: "backendUtilization with OutOfBand fields is valid", mutate: func(btp *egv1a1.BackendTrafficPolicy) { btp.Spec = egv1a1.BackendTrafficPolicySpec{ PolicyTargetReferences: egv1a1.PolicyTargetReferences{ @@ -857,7 +857,7 @@ func TestBackendTrafficPolicyTarget(t *testing.T) { LoadBalancer: &egv1a1.LoadBalancer{ Type: egv1a1.BackendUtilizationLoadBalancerType, BackendUtilization: &egv1a1.BackendUtilization{ - OOB: &egv1a1.OOBReporting{ + OutOfBand: &egv1a1.OutOfBandReporting{ ReportingPeriod: new(gwapiv1.Duration("5s")), Port: new(uint32(9001)), Authority: new("orca.local"), @@ -870,7 +870,7 @@ func TestBackendTrafficPolicyTarget(t *testing.T) { wantErrors: []string{}, }, { - desc: "backendUtilization OOB port zero is rejected", + desc: "backendUtilization OutOfBand port zero is rejected", mutate: func(btp *egv1a1.BackendTrafficPolicy) { btp.Spec = egv1a1.BackendTrafficPolicySpec{ PolicyTargetReferences: egv1a1.PolicyTargetReferences{ @@ -886,16 +886,16 @@ func TestBackendTrafficPolicyTarget(t *testing.T) { LoadBalancer: &egv1a1.LoadBalancer{ Type: egv1a1.BackendUtilizationLoadBalancerType, BackendUtilization: &egv1a1.BackendUtilization{ - OOB: &egv1a1.OOBReporting{Port: new(uint32(0))}, + OutOfBand: &egv1a1.OutOfBandReporting{Port: new(uint32(0))}, }, }, }, } }, - wantErrors: []string{"spec.loadBalancer.backendUtilization.oob.port"}, + wantErrors: []string{"spec.loadBalancer.backendUtilization.outOfBand.port"}, }, { - desc: "backendUtilization OOB port above max is rejected", + desc: "backendUtilization OutOfBand port above max is rejected", mutate: func(btp *egv1a1.BackendTrafficPolicy) { btp.Spec = egv1a1.BackendTrafficPolicySpec{ PolicyTargetReferences: egv1a1.PolicyTargetReferences{ @@ -911,16 +911,16 @@ func TestBackendTrafficPolicyTarget(t *testing.T) { LoadBalancer: &egv1a1.LoadBalancer{ Type: egv1a1.BackendUtilizationLoadBalancerType, BackendUtilization: &egv1a1.BackendUtilization{ - OOB: &egv1a1.OOBReporting{Port: new(uint32(70000))}, + OutOfBand: &egv1a1.OutOfBandReporting{Port: new(uint32(70000))}, }, }, }, } }, - wantErrors: []string{"spec.loadBalancer.backendUtilization.oob.port"}, + wantErrors: []string{"spec.loadBalancer.backendUtilization.outOfBand.port"}, }, { - desc: "backendUtilization OOB authority with newline is rejected", + desc: "backendUtilization OutOfBand authority with newline is rejected", mutate: func(btp *egv1a1.BackendTrafficPolicy) { btp.Spec = egv1a1.BackendTrafficPolicySpec{ PolicyTargetReferences: egv1a1.PolicyTargetReferences{ @@ -936,13 +936,13 @@ func TestBackendTrafficPolicyTarget(t *testing.T) { LoadBalancer: &egv1a1.LoadBalancer{ Type: egv1a1.BackendUtilizationLoadBalancerType, BackendUtilization: &egv1a1.BackendUtilization{ - OOB: &egv1a1.OOBReporting{Authority: new("foo\nbar")}, + OutOfBand: &egv1a1.OutOfBandReporting{Authority: new("foo\nbar")}, }, }, }, } }, - wantErrors: []string{"spec.loadBalancer.backendUtilization.oob.authority"}, + wantErrors: []string{"spec.loadBalancer.backendUtilization.outOfBand.authority"}, }, { desc: "backendUtilization field nil when type is BackendUtilization", diff --git a/test/helm/gateway-crds-helm/all.out.yaml b/test/helm/gateway-crds-helm/all.out.yaml index cc49f08ae4..fd725ed35d 100644 --- a/test/helm/gateway-crds-helm/all.out.yaml +++ b/test/helm/gateway-crds-helm/all.out.yaml @@ -25719,9 +25719,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -25731,12 +25731,12 @@ spec: properties: authority: description: Authority overrides the :authority header - on the OOB gRPC stream. + on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -31589,9 +31589,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -31601,12 +31601,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -46133,9 +46133,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -46146,12 +46146,12 @@ spec: authority: description: Authority overrides the :authority header on - the OOB gRPC stream. + the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -47743,9 +47743,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -47756,12 +47756,12 @@ spec: authority: description: Authority overrides the :authority header on - the OOB gRPC stream. + the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -49519,9 +49519,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -49531,13 +49531,13 @@ spec: properties: authority: description: Authority overrides - the :authority header on the OOB + the :authority header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -51243,9 +51243,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -51255,12 +51255,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -54459,9 +54459,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -54471,12 +54471,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -55934,9 +55934,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -55946,12 +55946,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -57717,9 +57717,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -57729,13 +57729,13 @@ spec: properties: authority: description: Authority overrides the - :authority header on the OOB gRPC - stream. + :authority header on the OutOfBand + gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -59520,9 +59520,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -59532,12 +59532,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 diff --git a/test/helm/gateway-crds-helm/e2e.out.yaml b/test/helm/gateway-crds-helm/e2e.out.yaml index d004143734..4e89afbbeb 100644 --- a/test/helm/gateway-crds-helm/e2e.out.yaml +++ b/test/helm/gateway-crds-helm/e2e.out.yaml @@ -1657,9 +1657,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -1669,12 +1669,12 @@ spec: properties: authority: description: Authority overrides the :authority header - on the OOB gRPC stream. + on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -7527,9 +7527,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -7539,12 +7539,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -22071,9 +22071,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -22084,12 +22084,12 @@ spec: authority: description: Authority overrides the :authority header on - the OOB gRPC stream. + the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -23681,9 +23681,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -23694,12 +23694,12 @@ spec: authority: description: Authority overrides the :authority header on - the OOB gRPC stream. + the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -25457,9 +25457,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -25469,13 +25469,13 @@ spec: properties: authority: description: Authority overrides - the :authority header on the OOB + the :authority header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -27181,9 +27181,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -27193,12 +27193,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -30397,9 +30397,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -30409,12 +30409,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -31872,9 +31872,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -31884,12 +31884,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -33655,9 +33655,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -33667,13 +33667,13 @@ spec: properties: authority: description: Authority overrides the - :authority header on the OOB gRPC - stream. + :authority header on the OutOfBand + gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -35458,9 +35458,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -35470,12 +35470,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 diff --git a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml index aa36ae7649..1507eb6185 100644 --- a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml +++ b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml @@ -1657,9 +1657,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -1669,12 +1669,12 @@ spec: properties: authority: description: Authority overrides the :authority header - on the OOB gRPC stream. + on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -7527,9 +7527,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -7539,12 +7539,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -22071,9 +22071,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -22084,12 +22084,12 @@ spec: authority: description: Authority overrides the :authority header on - the OOB gRPC stream. + the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -23681,9 +23681,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -23694,12 +23694,12 @@ spec: authority: description: Authority overrides the :authority header on - the OOB gRPC stream. + the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -25457,9 +25457,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -25469,13 +25469,13 @@ spec: properties: authority: description: Authority overrides - the :authority header on the OOB + the :authority header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -27181,9 +27181,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -27193,12 +27193,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -30397,9 +30397,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -30409,12 +30409,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -31872,9 +31872,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -31884,12 +31884,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -33655,9 +33655,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -33667,13 +33667,13 @@ spec: properties: authority: description: Authority overrides the - :authority header on the OOB gRPC - stream. + :authority header on the OutOfBand + gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 @@ -35458,9 +35458,9 @@ spec: items: type: string type: array - oob: + outOfBand: description: |- - OOB enables out-of-band ORCA load reporting. When set, Envoy opens a + OutOfBand 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 @@ -35470,12 +35470,12 @@ spec: properties: authority: description: Authority overrides the :authority - header on the OOB gRPC stream. + header on the OutOfBand gRPC stream. pattern: ^[^\x00\n\r]*$ type: string port: description: |- - Port overrides the port used for the OOB reporting connection, e.g. to + Port overrides the port used for the OutOfBand reporting connection, e.g. to reach a separate reporting sidecar. Defaults to the endpoint's port. format: int32 maximum: 65535 From aaa35b4427fd50a3b643b49dc5ba484e84d868c6 Mon Sep 17 00:00:00 2001 From: jukie <10012479+jukie@users.noreply.github.com> Date: Tue, 28 Jul 2026 20:11:25 -0600 Subject: [PATCH 5/7] use portnumber Signed-off-by: jukie <10012479+jukie@users.noreply.github.com> --- api/v1alpha1/loadbalancer_types.go | 4 +--- api/v1alpha1/zz_generated.deepcopy.go | 2 +- ....envoyproxy.io_backendtrafficpolicies.yaml | 2 -- ....envoyproxy.io_envoyextensionpolicies.yaml | 2 -- .../gateway.envoyproxy.io_envoyproxies.yaml | 8 -------- ...ateway.envoyproxy.io_securitypolicies.yaml | 8 -------- ....envoyproxy.io_backendtrafficpolicies.yaml | 2 -- ....envoyproxy.io_envoyextensionpolicies.yaml | 2 -- .../gateway.envoyproxy.io_envoyproxies.yaml | 8 -------- ...ateway.envoyproxy.io_securitypolicies.yaml | 8 -------- test/helm/gateway-crds-helm/all.out.yaml | 20 ------------------- test/helm/gateway-crds-helm/e2e.out.yaml | 20 ------------------- .../envoy-gateway-crds.out.yaml | 20 ------------------- 13 files changed, 2 insertions(+), 104 deletions(-) diff --git a/api/v1alpha1/loadbalancer_types.go b/api/v1alpha1/loadbalancer_types.go index 40cac9e516..b5321d6e31 100644 --- a/api/v1alpha1/loadbalancer_types.go +++ b/api/v1alpha1/loadbalancer_types.go @@ -255,11 +255,9 @@ type OutOfBandReporting struct { // Port overrides the port used for the OutOfBand reporting connection, e.g. to // reach a separate reporting sidecar. Defaults to the endpoint's port. - // +kubebuilder:validation:Minimum=1 - // +kubebuilder:validation:Maximum=65535 // +optional // +notImplementedHide - Port *uint32 `json:"port,omitempty"` + Port *gwapiv1.PortNumber `json:"port,omitempty"` // Authority overrides the :authority header on the OutOfBand gRPC stream. // diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go index 8b21698671..9ec9b98a8b 100644 --- a/api/v1alpha1/zz_generated.deepcopy.go +++ b/api/v1alpha1/zz_generated.deepcopy.go @@ -6405,7 +6405,7 @@ func (in *OutOfBandReporting) DeepCopyInto(out *OutOfBandReporting) { } if in.Port != nil { in, out := &in.Port, &out.Port - *out = new(uint32) + *out = new(v1.PortNumber) **out = **in } if in.Authority != nil { diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml index b99aad6a04..48cc1161f7 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml @@ -1122,8 +1122,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml index 7d4228678b..59e047d836 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml @@ -997,8 +997,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml index c6ad2cbf8a..3cc5975c43 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml @@ -12337,8 +12337,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -13947,8 +13945,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -15723,8 +15719,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -17446,8 +17440,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml index 7f33b38a97..0d0bf11651 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml @@ -1703,8 +1703,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -3178,8 +3176,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -4962,8 +4958,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -6764,8 +6758,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml index f5deefbc24..8ba8978de0 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml @@ -1121,8 +1121,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml index 074214d914..6ff52d1579 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml @@ -996,8 +996,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml index 9a26adb2f4..7e3cae7ba4 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml @@ -12336,8 +12336,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -13946,8 +13944,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -15722,8 +15718,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -17445,8 +17439,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml index 964b149323..cb3bfb5a9d 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml @@ -1702,8 +1702,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -3177,8 +3175,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -4961,8 +4957,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -6763,8 +6757,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/test/helm/gateway-crds-helm/all.out.yaml b/test/helm/gateway-crds-helm/all.out.yaml index fd725ed35d..9218e748a6 100644 --- a/test/helm/gateway-crds-helm/all.out.yaml +++ b/test/helm/gateway-crds-helm/all.out.yaml @@ -25739,8 +25739,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -31609,8 +31607,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -46154,8 +46150,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -47764,8 +47758,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -49540,8 +49532,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -51263,8 +51253,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -54479,8 +54467,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -55954,8 +55940,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -57738,8 +57722,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -59540,8 +59522,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/test/helm/gateway-crds-helm/e2e.out.yaml b/test/helm/gateway-crds-helm/e2e.out.yaml index 4e89afbbeb..e84da69799 100644 --- a/test/helm/gateway-crds-helm/e2e.out.yaml +++ b/test/helm/gateway-crds-helm/e2e.out.yaml @@ -1677,8 +1677,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -7547,8 +7545,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -22092,8 +22088,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -23702,8 +23696,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -25478,8 +25470,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -27201,8 +27191,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -30417,8 +30405,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -31892,8 +31878,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -33676,8 +33660,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -35478,8 +35460,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml index 1507eb6185..46eb18ebfe 100644 --- a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml +++ b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml @@ -1677,8 +1677,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -7547,8 +7545,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -22092,8 +22088,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -23702,8 +23696,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -25478,8 +25470,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -27201,8 +27191,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -30417,8 +30405,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -31892,8 +31878,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -33676,8 +33660,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -35478,8 +35460,6 @@ spec: Port overrides the port used for the OutOfBand 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: |- From 34ee3ebcbf18fd738dd434694c99ff59bc75170c Mon Sep 17 00:00:00 2001 From: jukie <10012479+jukie@users.noreply.github.com> Date: Tue, 28 Jul 2026 20:23:48 -0600 Subject: [PATCH 6/7] feedback Signed-off-by: jukie <10012479+jukie@users.noreply.github.com> --- api/v1alpha1/loadbalancer_types.go | 2 + .../tasks/traffic/backend-utilization.md | 249 ------------------ 2 files changed, 2 insertions(+), 249 deletions(-) delete mode 100644 site/content/en/latest/tasks/traffic/backend-utilization.md diff --git a/api/v1alpha1/loadbalancer_types.go b/api/v1alpha1/loadbalancer_types.go index b5321d6e31..0144b06b56 100644 --- a/api/v1alpha1/loadbalancer_types.go +++ b/api/v1alpha1/loadbalancer_types.go @@ -255,6 +255,8 @@ type OutOfBandReporting struct { // Port overrides the port used for the OutOfBand reporting connection, e.g. to // reach a separate reporting sidecar. Defaults to the endpoint's port. + // +kubebuilder:validation:Minimum=1 + // +kubebuilder:validation:Maximum=65535 // +optional // +notImplementedHide Port *gwapiv1.PortNumber `json:"port,omitempty"` diff --git a/site/content/en/latest/tasks/traffic/backend-utilization.md b/site/content/en/latest/tasks/traffic/backend-utilization.md deleted file mode 100644 index 4e96c97e76..0000000000 --- a/site/content/en/latest/tasks/traffic/backend-utilization.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: "Backend Utilization Load Balancing" ---- - -BackendUtilization load balancing uses [Open Resource Cost Application (ORCA)][ORCA] load metrics reported by the backend to dynamically weight endpoints. Under the hood it is implemented as [Envoy's client-side weighted round-robin][client-side-wrr] policy: each endpoint's weight is derived from the utilization metrics it emits, so instances running hot receive proportionally less traffic than those with headroom. - -If no ORCA metrics are received from an endpoint, that endpoint is treated as evenly weighted. - -See the [Load Balancing concepts page][concepts-lb] for a deeper explanation of ORCA metric formats. - -## Prerequisites - -* Your backend (or a sidecar in front of it) must emit ORCA load metrics as response headers or trailers. See [Backend instrumentation](#backend-instrumentation) below. -* {{< boilerplate prerequisites >}} - -## Build and Deploy the Example Backend - -The Envoy Gateway repository includes a small HTTP server under `examples/backend-utilization/` that emits a fixed ORCA `cpu_utilization` value (set via the `ORCA_CPU_UTILIZATION` environment variable) on every response. The example manifest deploys two sets of pods — one reporting `0.1` (idle) and one reporting `0.9` (hot) — behind a single Service. This lets you observe the weighting effect without wiring real load into a backend. - -**Note:** The `envoyproxy/gateway-backend-utilization` image is not published to a public registry — you need to build it locally from a checkout of the Envoy Gateway repository. - -* Build the example backend image - - ```shell - make -C examples/backend-utilization docker-buildx - ``` - -* Make the image available to your cluster - - {{< tabpane text=true >}} - {{% tab header="local kind server" %}} - - ```shell - kind load docker-image --name envoy-gateway envoyproxy/gateway-backend-utilization:latest - ``` - - {{% /tab %}} - {{% tab header="other Kubernetes server" %}} - - ```shell - docker tag envoyproxy/gateway-backend-utilization:latest $YOUR_DOCKER_REPO/gateway-backend-utilization:latest - docker push $YOUR_DOCKER_REPO/gateway-backend-utilization:latest - ``` - - If you push to your own registry, update the `image:` field in `examples/kubernetes/backend-utilization.yaml` to match before applying. - - {{% /tab %}} - {{< /tabpane >}} - -* Apply the example manifest (Service, two Deployments, HTTPRoute) - - ```shell - kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/backend-utilization.yaml -n default - ``` - -Verify the two Deployments are ready: - -```shell -kubectl get deployment/backend-utilization-low deployment/backend-utilization-high -n default -``` - -## Configure BackendUtilization - -Apply a [BackendTrafficPolicy][BackendTrafficPolicy] with `loadBalancer.type: BackendUtilization`: - -{{< tabpane text=true >}} -{{% tab header="Apply from stdin" %}} -```shell -cat <}} - -Leaving `backendUtilization: {}` empty accepts the defaults, but the 10 s default `blackoutPeriod` means traffic will appear evenly split for the first 10 seconds of the test. The shorter values above make the weighting visible immediately. The `backendUtilization` field itself is required when `type: BackendUtilization` — omitting it will fail CEL validation. - -## Configuration Fields - -All fields on `backendUtilization` are optional. - -| Field | Default | Purpose | -|---|---|---| -| `blackoutPeriod` | `10s` | How long an endpoint must report metrics before its reported weight is trusted. Prevents traffic from shifting based on a single noisy sample. | -| `weightExpirationPeriod` | `3m` | If an endpoint stops reporting for this long, its reported weight is discarded and it reverts to the default weight. | -| `weightUpdatePeriod` | `1s` | How often Envoy recomputes the weight table. Values below `100ms` are capped at `100ms`. | -| `errorUtilizationPenaltyPercent` | `0` | Multiplier (as `percent × 100`) applied to an endpoint's effective utilization based on its error rate (eps/qps). `100` = 1.0×, `150` = 1.5×, `200` = 2.0×. Higher values push errant endpoints out of rotation faster. | -| `metricNamesForComputingUtilization` | _unset_ | Custom ORCA metric keys to feed into the weight formula when `application_utilization` isn't reported. Use `named_metrics.` for keys inside the ORCA proto's `named_metrics` map. | -| `keepResponseHeaders` | `false` | By default Envoy strips the ORCA headers/trailers before forwarding the response. Set to `true` to let downstream clients see them (useful for chained load balancers or debugging). | -| `oob` | _unset_ | Enables [out-of-band ORCA reporting](#out-of-band-oob-reporting) — Envoy streams load reports from the endpoint's `OpenRcaService` instead of relying only on in-band response headers. | - -### Example: Tuned for a Bursty Backend - -```yaml -loadBalancer: - type: BackendUtilization - backendUtilization: - blackoutPeriod: 30s # ignore reports during slow-start - weightExpirationPeriod: 1m # shorter memory — react faster to silent endpoints - weightUpdatePeriod: 500ms # faster reweighting - errorUtilizationPenaltyPercent: 150 # 1.5× penalty for errant endpoints -``` - -### Example: Application-Defined Utilization - -If your backend reports a custom metric (for example, queue depth) instead of CPU utilization, wire it in through `metricNamesForComputingUtilization`: - -```yaml -loadBalancer: - type: BackendUtilization - backendUtilization: - metricNamesForComputingUtilization: - - named_metrics.queue_depth -``` - -The backend would then emit: - -```http -endpoint-load-metrics: TEXT named_metrics.queue_depth=0.42 -``` - -## Backend Instrumentation - -Your backend must emit ORCA load metrics. Envoy accepts metrics in three formats on response **headers or trailers**: - -| Format | Header | Payload | -|---|---|---| -| Binary | `endpoint-load-metrics-bin` | Base64-encoded serialized [`OrcaLoadReport`][orca-proto] proto | -| JSON | `endpoint-load-metrics` | `JSON {"cpu_utilization": 0.3, "mem_utilization": 0.8}` | -| TEXT | `endpoint-load-metrics` | `TEXT cpu=0.3,mem=0.8,named_metrics.queue_depth=0.42` | - -For gRPC backends, the [xDS ORCA][grpc-orca] libraries emit these automatically via the `orca_load_report` service. For HTTP backends, add a response middleware that measures and serializes your CPU/memory/custom metrics on each response. - -## Out-of-Band (OOB) Reporting - -By default Envoy reads ORCA metrics **in-band** — from the response headers or trailers of regular requests (see [Backend Instrumentation](#backend-instrumentation) above). With out-of-band (OOB) reporting, Envoy instead opens a dedicated server-streaming gRPC connection to each endpoint's [`OpenRcaService`][open-rca] (`xds.service.orca.v3.OpenRcaService/StreamCoreMetrics`) and receives load reports on a fixed schedule, independent of request traffic. - -OOB reporting is useful when: - -* Request volume is low or bursty, so in-band samples arrive too infrequently to weight endpoints well. -* You want load signals even for endpoints that are currently idle. -* A separate reporting sidecar exposes the ORCA stream on its own port. - -Enable it by adding an `oob` block. Its presence turns OOB on; an empty `oob: {}` enables it with Envoy's defaults. In-band metrics (and `keepResponseHeaders`) continue to be honored alongside OOB. - -```yaml -loadBalancer: - type: BackendUtilization - backendUtilization: - oob: - reportingPeriod: 5s # how often Envoy requests a report (default 10s) - port: 9001 # optional: reach a reporting sidecar on a different port - authority: orca.local # optional: :authority header for the OOB gRPC stream -``` - -| Field | Default | Purpose | -|---|---|---| -| `oob.reportingPeriod` | `10s` | How often Envoy requests a load report from the endpoint. The server may report less frequently than requested. | -| `oob.port` | endpoint port | Alternative port for the OOB reporting connection, e.g. a dedicated reporting sidecar. Must be between `1` and `65535`. | -| `oob.authority` | _unset_ | Overrides the `:authority` header on the OOB gRPC stream. | - -Your backend must implement the `OpenRcaService` streaming RPC for OOB to take effect. gRPC backends can use the [xDS ORCA][grpc-orca] server libraries; the same [`OrcaLoadReport`][orca-proto] message carries both in-band and OOB reports. - -## Combining With Zone-Aware Routing - -`BackendUtilization` composes with `weightedZones` to produce locality-aware weighted round-robin (Envoy's `wrr_locality` policy). See the [WeightedZones example][zone-aware-weighted] on the zone-aware routing page. - -`preferLocal` is **not** supported with `BackendUtilization`. - -## Testing - -Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the Quickstart instructions to set the variable. - -Give Envoy a few seconds after applying the policy to collect ORCA samples and compute endpoint weights — until then, traffic will appear roughly even. Then send 200 requests and tally which deployment handled each. Because `backend-utilization-low` reports `cpu_utilization=0.1` and `backend-utilization-high` reports `0.9`, Envoy should weight the `low` pods roughly 9× more heavily. - -```shell -for i in $(seq 1 200); do - curl -s -H "Host: www.example.com" "http://${GATEWAY_HOST}/backend-utilization" | jq -r '.pod' -done | sort | uniq -c -``` - -Expected output (exact counts will vary, but `low` should dominate ~9:1): - -```console - 90 backend-utilization-low-6b9cf46b59-l7df7 - 87 backend-utilization-low-6b9cf46b59-xxrw2 - 12 backend-utilization-high-5fdb65cb87-mctlp - 11 backend-utilization-high-5fdb65cb87-rrdvq -``` - -If you instead see a roughly even split, the weights may not have stabilized yet — wait a few seconds and retry. You can verify the per-endpoint weights directly through the Envoy admin interface: - -```shell -ENVOY_POD=$(kubectl get pods -n envoy-gateway-system -l gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') -kubectl -n envoy-gateway-system port-forward pod/${ENVOY_POD} 19000:19000 & -curl -s localhost:19000/clusters | grep "backend-utilization" | grep weight -``` - -You should see weights roughly `10000` for the `low` pods and `1111` for the `high` pods (the inverse of the reported utilization). - -## Clean-Up - -```shell -kubectl delete backendtrafficpolicy/backend-utilization -kubectl delete -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/backend-utilization.yaml -n default -``` - -[ORCA]: https://docs.google.com/document/d/1NSnK3346BkBo1JUU3I9I5NYYnaJZQPt8_Z_XCBCI3uA -[orca-proto]: https://www.envoyproxy.io/docs/envoy/latest/xds/data/orca/v3/orca_load_report.proto -[client-side-wrr]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto -[grpc-orca]: https://github.com/grpc/proposal/blob/master/A51-custom-backend-metrics.md -[open-rca]: https://github.com/cncf/xds/blob/main/xds/service/orca/v3/orca.proto -[concepts-lb]: ../../../concepts/load-balancing#backend-utilization-orca -[zone-aware-weighted]: ../zone-aware-routing#weightedzones -[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy From e474be666f18a2f08460980673b91c7c8020db25 Mon Sep 17 00:00:00 2001 From: jukie <10012479+jukie@users.noreply.github.com> Date: Wed, 29 Jul 2026 09:38:09 -0600 Subject: [PATCH 7/7] fixes Signed-off-by: jukie <10012479+jukie@users.noreply.github.com> --- api/v1alpha1/loadbalancer_types.go | 2 +- api/v1alpha1/zz_generated.deepcopy.go | 2 +- ....envoyproxy.io_backendtrafficpolicies.yaml | 2 + ....envoyproxy.io_envoyextensionpolicies.yaml | 2 + .../gateway.envoyproxy.io_envoyproxies.yaml | 8 + ...ateway.envoyproxy.io_securitypolicies.yaml | 8 + ....envoyproxy.io_backendtrafficpolicies.yaml | 2 + ....envoyproxy.io_envoyextensionpolicies.yaml | 2 + .../gateway.envoyproxy.io_envoyproxies.yaml | 8 + ...ateway.envoyproxy.io_securitypolicies.yaml | 8 + .../tasks/traffic/backend-utilization.md | 217 ++++++++++++++++++ .../backendtrafficpolicy_test.go | 6 +- test/helm/gateway-crds-helm/all.out.yaml | 20 ++ test/helm/gateway-crds-helm/e2e.out.yaml | 20 ++ .../envoy-gateway-crds.out.yaml | 20 ++ 15 files changed, 322 insertions(+), 5 deletions(-) create mode 100644 site/content/en/latest/tasks/traffic/backend-utilization.md diff --git a/api/v1alpha1/loadbalancer_types.go b/api/v1alpha1/loadbalancer_types.go index 0144b06b56..5d997df169 100644 --- a/api/v1alpha1/loadbalancer_types.go +++ b/api/v1alpha1/loadbalancer_types.go @@ -259,7 +259,7 @@ type OutOfBandReporting struct { // +kubebuilder:validation:Maximum=65535 // +optional // +notImplementedHide - Port *gwapiv1.PortNumber `json:"port,omitempty"` + Port *int32 `json:"port,omitempty"` // Authority overrides the :authority header on the OutOfBand gRPC stream. // diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go index 9ec9b98a8b..6d7268f027 100644 --- a/api/v1alpha1/zz_generated.deepcopy.go +++ b/api/v1alpha1/zz_generated.deepcopy.go @@ -6405,7 +6405,7 @@ func (in *OutOfBandReporting) DeepCopyInto(out *OutOfBandReporting) { } if in.Port != nil { in, out := &in.Port, &out.Port - *out = new(v1.PortNumber) + *out = new(int32) **out = **in } if in.Authority != nil { diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml index 48cc1161f7..b99aad6a04 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml @@ -1122,6 +1122,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml index 59e047d836..7d4228678b 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml @@ -997,6 +997,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml index 3cc5975c43..c6ad2cbf8a 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml @@ -12337,6 +12337,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -13945,6 +13947,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -15719,6 +15723,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -17440,6 +17446,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml index 0d0bf11651..7f33b38a97 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml @@ -1703,6 +1703,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -3176,6 +3178,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -4958,6 +4962,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -6758,6 +6764,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml index 8ba8978de0..f5deefbc24 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml @@ -1121,6 +1121,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml index 6ff52d1579..074214d914 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml @@ -996,6 +996,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml index 7e3cae7ba4..9a26adb2f4 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml @@ -12336,6 +12336,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -13944,6 +13946,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -15718,6 +15722,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -17439,6 +17445,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml index cb3bfb5a9d..964b149323 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml @@ -1702,6 +1702,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -3175,6 +3177,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -4957,6 +4961,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -6757,6 +6763,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/site/content/en/latest/tasks/traffic/backend-utilization.md b/site/content/en/latest/tasks/traffic/backend-utilization.md new file mode 100644 index 0000000000..adbd19f787 --- /dev/null +++ b/site/content/en/latest/tasks/traffic/backend-utilization.md @@ -0,0 +1,217 @@ +--- +title: "Backend Utilization Load Balancing" +--- + +BackendUtilization load balancing uses [Open Resource Cost Application (ORCA)][ORCA] load metrics reported by the backend to dynamically weight endpoints. Under the hood it is implemented as [Envoy's client-side weighted round-robin][client-side-wrr] policy: each endpoint's weight is derived from the utilization metrics it emits, so instances running hot receive proportionally less traffic than those with headroom. + +If no ORCA metrics are received from an endpoint, that endpoint is treated as evenly weighted. + +See the [Load Balancing concepts page][concepts-lb] for a deeper explanation of ORCA metric formats. + +## Prerequisites + +* Your backend (or a sidecar in front of it) must emit ORCA load metrics as response headers or trailers. See [Backend instrumentation](#backend-instrumentation) below. +* {{< boilerplate prerequisites >}} + +## Build and Deploy the Example Backend + +The Envoy Gateway repository includes a small HTTP server under `examples/backend-utilization/` that emits a fixed ORCA `cpu_utilization` value (set via the `ORCA_CPU_UTILIZATION` environment variable) on every response. The example manifest deploys two sets of pods — one reporting `0.1` (idle) and one reporting `0.9` (hot) — behind a single Service. This lets you observe the weighting effect without wiring real load into a backend. + +**Note:** The `envoyproxy/gateway-backend-utilization` image is not published to a public registry — you need to build it locally from a checkout of the Envoy Gateway repository. + +* Build the example backend image + + ```shell + make -C examples/backend-utilization docker-buildx + ``` + +* Make the image available to your cluster + + {{< tabpane text=true >}} + {{% tab header="local kind server" %}} + + ```shell + kind load docker-image --name envoy-gateway envoyproxy/gateway-backend-utilization:latest + ``` + + {{% /tab %}} + {{% tab header="other Kubernetes server" %}} + + ```shell + docker tag envoyproxy/gateway-backend-utilization:latest $YOUR_DOCKER_REPO/gateway-backend-utilization:latest + docker push $YOUR_DOCKER_REPO/gateway-backend-utilization:latest + ``` + + If you push to your own registry, update the `image:` field in `examples/kubernetes/backend-utilization.yaml` to match before applying. + + {{% /tab %}} + {{< /tabpane >}} + +* Apply the example manifest (Service, two Deployments, HTTPRoute) + + ```shell + kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/backend-utilization.yaml -n default + ``` + +Verify the two Deployments are ready: + +```shell +kubectl get deployment/backend-utilization-low deployment/backend-utilization-high -n default +``` + +## Configure BackendUtilization + +Apply a [BackendTrafficPolicy][BackendTrafficPolicy] with `loadBalancer.type: BackendUtilization`: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} +```shell +cat <}} + +Leaving `backendUtilization: {}` empty accepts the defaults, but the 10 s default `blackoutPeriod` means traffic will appear evenly split for the first 10 seconds of the test. The shorter values above make the weighting visible immediately. The `backendUtilization` field itself is required when `type: BackendUtilization` — omitting it will fail CEL validation. + +## Configuration Fields + +All fields on `backendUtilization` are optional. + +| Field | Default | Purpose | +|---|---|---| +| `blackoutPeriod` | `10s` | How long an endpoint must report metrics before its reported weight is trusted. Prevents traffic from shifting based on a single noisy sample. | +| `weightExpirationPeriod` | `3m` | If an endpoint stops reporting for this long, its reported weight is discarded and it reverts to the default weight. | +| `weightUpdatePeriod` | `1s` | How often Envoy recomputes the weight table. Values below `100ms` are capped at `100ms`. | +| `errorUtilizationPenaltyPercent` | `0` | Multiplier (as `percent × 100`) applied to an endpoint's effective utilization based on its error rate (eps/qps). `100` = 1.0×, `150` = 1.5×, `200` = 2.0×. Higher values push errant endpoints out of rotation faster. | +| `metricNamesForComputingUtilization` | _unset_ | Custom ORCA metric keys to feed into the weight formula when `application_utilization` isn't reported. Use `named_metrics.` for keys inside the ORCA proto's `named_metrics` map. | +| `keepResponseHeaders` | `false` | By default Envoy strips the ORCA headers/trailers before forwarding the response. Set to `true` to let downstream clients see them (useful for chained load balancers or debugging). | + +### Example: Tuned for a Bursty Backend + +```yaml +loadBalancer: + type: BackendUtilization + backendUtilization: + blackoutPeriod: 30s # ignore reports during slow-start + weightExpirationPeriod: 1m # shorter memory — react faster to silent endpoints + weightUpdatePeriod: 500ms # faster reweighting + errorUtilizationPenaltyPercent: 150 # 1.5× penalty for errant endpoints +``` + +### Example: Application-Defined Utilization + +If your backend reports a custom metric (for example, queue depth) instead of CPU utilization, wire it in through `metricNamesForComputingUtilization`: + +```yaml +loadBalancer: + type: BackendUtilization + backendUtilization: + metricNamesForComputingUtilization: + - named_metrics.queue_depth +``` + +The backend would then emit: + +```http +endpoint-load-metrics: TEXT named_metrics.queue_depth=0.42 +``` + +## Backend Instrumentation + +Your backend must emit ORCA load metrics. Envoy accepts metrics in three formats on response **headers or trailers**: + +| Format | Header | Payload | +|---|---|---| +| Binary | `endpoint-load-metrics-bin` | Base64-encoded serialized [`OrcaLoadReport`][orca-proto] proto | +| JSON | `endpoint-load-metrics` | `JSON {"cpu_utilization": 0.3, "mem_utilization": 0.8}` | +| TEXT | `endpoint-load-metrics` | `TEXT cpu=0.3,mem=0.8,named_metrics.queue_depth=0.42` | + +For gRPC backends, the [xDS ORCA][grpc-orca] libraries emit these automatically via the `orca_load_report` service. For HTTP backends, add a response middleware that measures and serializes your CPU/memory/custom metrics on each response. + +## Combining With Zone-Aware Routing + +`BackendUtilization` composes with `weightedZones` to produce locality-aware weighted round-robin (Envoy's `wrr_locality` policy). See the [WeightedZones example][zone-aware-weighted] on the zone-aware routing page. + +`preferLocal` is **not** supported with `BackendUtilization`. + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the Quickstart instructions to set the variable. + +Give Envoy a few seconds after applying the policy to collect ORCA samples and compute endpoint weights — until then, traffic will appear roughly even. Then send 200 requests and tally which deployment handled each. Because `backend-utilization-low` reports `cpu_utilization=0.1` and `backend-utilization-high` reports `0.9`, Envoy should weight the `low` pods roughly 9× more heavily. + +```shell +for i in $(seq 1 200); do + curl -s -H "Host: www.example.com" "http://${GATEWAY_HOST}/backend-utilization" | jq -r '.pod' +done | sort | uniq -c +``` + +Expected output (exact counts will vary, but `low` should dominate ~9:1): + +```console + 90 backend-utilization-low-6b9cf46b59-l7df7 + 87 backend-utilization-low-6b9cf46b59-xxrw2 + 12 backend-utilization-high-5fdb65cb87-mctlp + 11 backend-utilization-high-5fdb65cb87-rrdvq +``` + +If you instead see a roughly even split, the weights may not have stabilized yet — wait a few seconds and retry. You can verify the per-endpoint weights directly through the Envoy admin interface: + +```shell +ENVOY_POD=$(kubectl get pods -n envoy-gateway-system -l gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +kubectl -n envoy-gateway-system port-forward pod/${ENVOY_POD} 19000:19000 & +curl -s localhost:19000/clusters | grep "backend-utilization" | grep weight +``` + +You should see weights roughly `10000` for the `low` pods and `1111` for the `high` pods (the inverse of the reported utilization). + +## Clean-Up + +```shell +kubectl delete backendtrafficpolicy/backend-utilization +kubectl delete -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/backend-utilization.yaml -n default +``` + +[ORCA]: https://docs.google.com/document/d/1NSnK3346BkBo1JUU3I9I5NYYnaJZQPt8_Z_XCBCI3uA +[orca-proto]: https://www.envoyproxy.io/docs/envoy/latest/xds/data/orca/v3/orca_load_report.proto +[client-side-wrr]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto +[grpc-orca]: https://github.com/grpc/proposal/blob/master/A51-custom-backend-metrics.md +[concepts-lb]: ../../../concepts/load-balancing#backend-utilization-orca +[zone-aware-weighted]: ../zone-aware-routing#weightedzones +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy diff --git a/test/cel-validation/backendtrafficpolicy_test.go b/test/cel-validation/backendtrafficpolicy_test.go index 0170b28c3f..4fd5102b55 100644 --- a/test/cel-validation/backendtrafficpolicy_test.go +++ b/test/cel-validation/backendtrafficpolicy_test.go @@ -859,7 +859,7 @@ func TestBackendTrafficPolicyTarget(t *testing.T) { BackendUtilization: &egv1a1.BackendUtilization{ OutOfBand: &egv1a1.OutOfBandReporting{ ReportingPeriod: new(gwapiv1.Duration("5s")), - Port: new(uint32(9001)), + Port: new(int32(9001)), Authority: new("orca.local"), }, }, @@ -886,7 +886,7 @@ func TestBackendTrafficPolicyTarget(t *testing.T) { LoadBalancer: &egv1a1.LoadBalancer{ Type: egv1a1.BackendUtilizationLoadBalancerType, BackendUtilization: &egv1a1.BackendUtilization{ - OutOfBand: &egv1a1.OutOfBandReporting{Port: new(uint32(0))}, + OutOfBand: &egv1a1.OutOfBandReporting{Port: new(int32(0))}, }, }, }, @@ -911,7 +911,7 @@ func TestBackendTrafficPolicyTarget(t *testing.T) { LoadBalancer: &egv1a1.LoadBalancer{ Type: egv1a1.BackendUtilizationLoadBalancerType, BackendUtilization: &egv1a1.BackendUtilization{ - OutOfBand: &egv1a1.OutOfBandReporting{Port: new(uint32(70000))}, + OutOfBand: &egv1a1.OutOfBandReporting{Port: new(int32(70000))}, }, }, }, diff --git a/test/helm/gateway-crds-helm/all.out.yaml b/test/helm/gateway-crds-helm/all.out.yaml index 9218e748a6..fd725ed35d 100644 --- a/test/helm/gateway-crds-helm/all.out.yaml +++ b/test/helm/gateway-crds-helm/all.out.yaml @@ -25739,6 +25739,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -31607,6 +31609,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -46150,6 +46154,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -47758,6 +47764,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -49532,6 +49540,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -51253,6 +51263,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -54467,6 +54479,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -55940,6 +55954,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -57722,6 +57738,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -59522,6 +59540,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/test/helm/gateway-crds-helm/e2e.out.yaml b/test/helm/gateway-crds-helm/e2e.out.yaml index e84da69799..4e89afbbeb 100644 --- a/test/helm/gateway-crds-helm/e2e.out.yaml +++ b/test/helm/gateway-crds-helm/e2e.out.yaml @@ -1677,6 +1677,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -7545,6 +7547,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -22088,6 +22092,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -23696,6 +23702,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -25470,6 +25478,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -27191,6 +27201,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -30405,6 +30417,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -31878,6 +31892,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -33660,6 +33676,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -35460,6 +35478,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- diff --git a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml index 46eb18ebfe..1507eb6185 100644 --- a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml +++ b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml @@ -1677,6 +1677,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -7545,6 +7547,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -22088,6 +22092,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -23696,6 +23702,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -25470,6 +25478,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -27191,6 +27201,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -30405,6 +30417,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -31878,6 +31892,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -33660,6 +33676,8 @@ spec: Port overrides the port used for the OutOfBand 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: |- @@ -35460,6 +35478,8 @@ spec: Port overrides the port used for the OutOfBand 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: |-