Skip to content

Commit 30f2983

Browse files
Nick Youngrobscott
Nick Young
and
robscott
authored
Update HTTPRoute BackendRef docs to clarify error behavior (#1243)
* Update HTTPRoute BackendRef docs to clarify error behavior Signed-off-by: Nick Young <ynick@vmware.com> * Add new ResolvedRefs reasons Signed-off-by: Nick Young <ynick@vmware.com> * Add more invalid BackendRef conformance tests Signed-off-by: Nick Young <ynick@vmware.com> * Update conformance tests Signed-off-by: Nick Young <ynick@vmware.com> * Fix PR comments and update v1beta1 resources Signed-off-by: Nick Young <ynick@vmware.com> * Update generated YAML Signed-off-by: Nick Young <ynick@vmware.com> * Update conformance tests with Reasons Signed-off-by: Nick Young <ynick@vmware.com> * Fix spelling Signed-off-by: Nick Young <ynick@vmware.com> * UFix PR comments Signed-off-by: Nick Young <ynick@vmware.com> * Fix some more PR comments Signed-off-by: Nick Young <ynick@vmware.com> * Update helpers with PR feedback Signed-off-by: Nick Young <ynick@vmware.com> * Fixing initialization for new conformance tests Co-authored-by: Rob Scott <robertjscott@google.com>
1 parent 5e8421c commit 30f2983

16 files changed

+414
-194
lines changed

‎apis/v1alpha2/httproute_types.go‎

Lines changed: 33 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -202,24 +202,25 @@ type HTTPRouteRule struct {
202202
// BackendRefs defines the backend(s) where matching requests should be
203203
// sent.
204204
//
205-
// A 500 status code MUST be returned if there are no BackendRefs or filters
206-
// specified that would result in a response being sent.
205+
// Failure behavior here depends on how many BackendRefs are specified and
206+
// how many are invalid.
207207
//
208-
// A BackendRef is considered invalid when it refers to:
208+
// If *all* entries in BackendRefs are invalid, and there are also no filters
209+
// specified in this route rule, *all* traffic which matches this rule MUST
210+
// receive a 500 status code.
209211
//
210-
// * an unknown or unsupported kind of resource
211-
// * a resource that does not exist
212-
// * a resource in another namespace when the reference has not been
213-
// explicitly allowed by a ReferenceGrant (or equivalent concept).
212+
// See the HTTPBackendRef definition for the rules about what makes a single
213+
// HTTPBackendRef invalid.
214214
//
215-
// When a BackendRef is invalid, 500 status codes MUST be returned for
215+
// When a HTTPBackendRef is invalid, 500 status codes MUST be returned for
216216
// requests that would have otherwise been routed to an invalid backend. If
217217
// multiple backends are specified, and some are invalid, the proportion of
218218
// requests that would otherwise have been routed to an invalid backend
219219
// MUST receive a 500 status code.
220220
//
221-
// When a BackendRef refers to a Service that has no ready endpoints, it is
222-
// recommended to return a 503 status code.
221+
// For example, if two backends are specified with equal weights, and one is
222+
// invalid, 50 percent of traffic must receive a 500. Implementations may
223+
// choose how that 50 percent is determined.
223224
//
224225
// Support: Core for Kubernetes Service
225226
//
@@ -933,21 +934,31 @@ type HTTPRequestMirrorFilter struct {
933934
type HTTPBackendRef struct {
934935
// BackendRef is a reference to a backend to forward matched requests to.
935936
//
936-
// If the referent cannot be found, this HTTPBackendRef is invalid and must
937-
// be dropped from the Gateway. The controller must ensure the
938-
// "ResolvedRefs" condition on the Route is set to `status: False` and not
939-
// configure this backend in the underlying implementation.
937+
// A BackendRef can be invalid for the following reasons. In all cases, the
938+
// implementation MUST ensure the `ResolvedRefs` Condition on the Route
939+
// is set to `status: False`, with a Reason and Message that indicate
940+
// what is the cause of the error.
940941
//
941-
// If there is a cross-namespace reference to an *existing* object
942-
// that is not covered by a ReferenceGrant, the controller must ensure the
943-
// "ResolvedRefs" condition on the Route is set to `status: False`,
944-
// with the "RefNotPermitted" reason and not configure this backend in the
945-
// underlying implementation.
942+
// A BackendRef is invalid if:
946943
//
947-
// In either error case, the Message of the `ResolvedRefs` Condition
948-
// should be used to provide more detail about the problem.
944+
// * It refers to an unknown or unsupported kind of resource. In this
945+
// case, the Reason must be set to `InvalidKind` and Message of the
946+
// Condition must explain which kind of resource is unknown or unsupported.
947+
//
948+
// * It refers to a resource that does not exist. In this case, the Reason must
949+
// be set to `BackendNotFound` and the Message of the Condition must explain
950+
// which resource does not exist.
949951
//
950-
// Support: Custom
952+
// * It refers a resource in another namespace when the reference has not been
953+
// explicitly allowed by a ReferenceGrant (or equivalent concept). In this
954+
// case, the Reason must be set to `RefNotPermitted` and the Message of the
955+
// Condition must explain which cross-namespace reference is not allowed.
956+
//
957+
// Support: Core for Kubernetes Service
958+
//
959+
// Support: Custom for any other resource
960+
//
961+
// Support for weight: Core
951962
//
952963
// +optional
953964
BackendRef `json:",inline"`

‎apis/v1alpha2/shared_types.go‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,15 @@ const (
246246
// another namespace, where the object in the other namespace does
247247
// not have a ReferenceGrant explicitly allowing the reference.
248248
RouteReasonRefNotPermitted RouteConditionReason = "RefNotPermitted"
249+
250+
// This reason is used with the "ResolvedRefs" condition when
251+
// one of the Route's rules has a reference to an unknown or unsupported
252+
// Group and/or Kind.
253+
RouteReasonInvalidKind RouteConditionReason = "InvalidKind"
254+
255+
// This reason is used with the "ResolvedRefs" condition when one of the
256+
// Route's rules has a reference to a resource that does not exist.
257+
RouteReasonBackendNotFound RouteConditionReason = "BackendNotFound"
249258
)
250259

251260
// RouteParentStatus describes the status of a route with respect to an

‎apis/v1beta1/httproute_types.go‎

Lines changed: 33 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -201,24 +201,25 @@ type HTTPRouteRule struct {
201201
// BackendRefs defines the backend(s) where matching requests should be
202202
// sent.
203203
//
204-
// A 500 status code MUST be returned if there are no BackendRefs or filters
205-
// specified that would result in a response being sent.
204+
// Failure behavior here depends on how many BackendRefs are specified and
205+
// how many are invalid.
206206
//
207-
// A BackendRef is considered invalid when it refers to:
207+
// If *all* entries in BackendRefs are invalid, and there are also no filters
208+
// specified in this route rule, *all* traffic which matches this rule MUST
209+
// receive a 500 status code.
208210
//
209-
// * an unknown or unsupported kind of resource
210-
// * a resource that does not exist
211-
// * a resource in another namespace when the reference has not been
212-
// explicitly allowed by a ReferenceGrant (or equivalent concept).
211+
// See the HTTPBackendRef definition for the rules about what makes a single
212+
// HTTPBackendRef invalid.
213213
//
214-
// When a BackendRef is invalid, 500 status codes MUST be returned for
214+
// When a HTTPBackendRef is invalid, 500 status codes MUST be returned for
215215
// requests that would have otherwise been routed to an invalid backend. If
216216
// multiple backends are specified, and some are invalid, the proportion of
217217
// requests that would otherwise have been routed to an invalid backend
218218
// MUST receive a 500 status code.
219219
//
220-
// When a BackendRef refers to a Service that has no ready endpoints, it is
221-
// recommended to return a 503 status code.
220+
// For example, if two backends are specified with equal weights, and one is
221+
// invalid, 50 percent of traffic must receive a 500. Implementations may
222+
// choose how that 50 percent is determined.
222223
//
223224
// Support: Core for Kubernetes Service
224225
//
@@ -932,21 +933,31 @@ type HTTPRequestMirrorFilter struct {
932933
type HTTPBackendRef struct {
933934
// BackendRef is a reference to a backend to forward matched requests to.
934935
//
935-
// If the referent cannot be found, this HTTPBackendRef is invalid and must
936-
// be dropped from the Gateway. The controller must ensure the
937-
// "ResolvedRefs" condition on the Route is set to `status: False` and not
938-
// configure this backend in the underlying implementation.
936+
// A BackendRef can be invalid for the following reasons. In all cases, the
937+
// implementation MUST ensure the `ResolvedRefs` Condition on the Route
938+
// is set to `status: False`, with a Reason and Message that indicate
939+
// what is the cause of the error.
939940
//
940-
// If there is a cross-namespace reference to an *existing* object
941-
// that is not covered by a ReferenceGrant, the controller must ensure the
942-
// "ResolvedRefs" condition on the Route is set to `status: False`,
943-
// with the "RefNotPermitted" reason and not configure this backend in the
944-
// underlying implementation.
941+
// A BackendRef is invalid if:
945942
//
946-
// In either error case, the Message of the `ResolvedRefs` Condition
947-
// should be used to provide more detail about the problem.
943+
// * It refers to an unknown or unsupported kind of resource. In this
944+
// case, the Reason must be set to `InvalidKind` and Message of the
945+
// Condition must explain which kind of resource is unknown or unsupported.
946+
//
947+
// * It refers to a resource that does not exist. In this case, the Reason must
948+
// be set to `BackendNotFound` and the Message of the Condition must explain
949+
// which resource does not exist.
948950
//
949-
// Support: Custom
951+
// * It refers a resource in another namespace when the reference has not been
952+
// explicitly allowed by a ReferenceGrant (or equivalent concept). In this
953+
// case, the Reason must be set to `RefNotPermitted` and the Message of the
954+
// Condition must explain which cross-namespace reference is not allowed.
955+
//
956+
// Support: Core for Kubernetes Service
957+
//
958+
// Support: Custom for any other resource
959+
//
960+
// Support for weight: Core
950961
//
951962
// +optional
952963
BackendRef `json:",inline"`

‎apis/v1beta1/shared_types.go‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,15 @@ const (
246246
// another namespace, where the object in the other namespace does
247247
// not have a ReferenceGrant explicitly allowing the reference.
248248
RouteReasonRefNotPermitted RouteConditionReason = "RefNotPermitted"
249+
250+
// This reason is used with the "ResolvedRefs" condition when
251+
// one of the Route's rules has a reference to an unknown or unsupported
252+
// Group and/or Kind.
253+
RouteReasonInvalidKind RouteConditionReason = "InvalidKind"
254+
255+
// This reason is used with the "ResolvedRefs" condition when one of the
256+
// Route's rules has a reference to a resource that does not exist.
257+
RouteReasonBackendNotFound RouteConditionReason = "BackendNotFound"
249258
)
250259

251260
// RouteParentStatus describes the status of a route with respect to an

‎config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml‎

Lines changed: 34 additions & 32 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)