Skip to content

Update HTTPRoute BackendRef docs to clarify error behavior #1243

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Jul 12, 2022
Merged

Update HTTPRoute BackendRef docs to clarify error behavior #1243

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
567f901
Update HTTPRoute BackendRef docs to clarify error behavior
Jun 30, 2022
b61617d
Add new ResolvedRefs reasons
Jun 30, 2022
e012d5a
Add more invalid BackendRef conformance tests
Jun 30, 2022
17cc420
Update conformance tests
Jul 1, 2022
3d221db
Fix PR comments and update v1beta1 resources
Jul 5, 2022
bc22e52
Update generated YAML
Jul 5, 2022
238c1d4
Update conformance tests with Reasons
Jul 5, 2022
e041ecf
Fix spelling
Jul 6, 2022
477fde5
UFix PR comments
Jul 11, 2022
ac7d3f8
Fix some more PR comments
Jul 12, 2022
8abd902
Update helpers with PR feedback
Jul 12, 2022
49c0453
Fixing initialization for new conformance tests
robscott Jul 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 33 additions & 22 deletions apis/v1alpha2/httproute_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,24 +202,25 @@ type HTTPRouteRule struct {
// BackendRefs defines the backend(s) where matching requests should be
// sent.
//
// A 500 status code MUST be returned if there are no BackendRefs or filters
// specified that would result in a response being sent.
// Failure behavior here depends on how many BackendRefs are specified and
// how many are invalid.
//
// A BackendRef is considered invalid when it refers to:
// If *all* entries in BackendRefs are invalid, and there are also no filters
Copy link
Contributor

Choose a reason for hiding this comment

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

Is this saying something different than "When a HTTPBackendRef is invalid, 500 status codes MUST be returned for"? They seem the same to me, and I wasn't sure if there was some subtle difference I was missing or if we were just re-iterating? Especially the "...also no filters..." part?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Not really in this update, no, but there are a few places where "no valid backends" and "some valid backends" were treated differently, and I wanted to make doubly sure that there's no confusion.

// specified in this route rule, *all* traffic which matches this rule MUST
// receive a 500 status code.
//
// * an unknown or unsupported kind of resource
// * a resource that does not exist
// * a resource in another namespace when the reference has not been
// explicitly allowed by a ReferenceGrant (or equivalent concept).
// See the HTTPBackendRef definition for the rules about what makes a single
// HTTPBackendRef invalid.
//
// When a BackendRef is invalid, 500 status codes MUST be returned for
// When a HTTPBackendRef is invalid, 500 status codes MUST be returned for
// requests that would have otherwise been routed to an invalid backend. If
// multiple backends are specified, and some are invalid, the proportion of
// requests that would otherwise have been routed to an invalid backend
// MUST receive a 500 status code.
//
// When a BackendRef refers to a Service that has no ready endpoints, it is
// recommended to return a 503 status code.
// For example, if two backends are specified with equal weights, and one is
// invalid, 50 percent of traffic must receive a 500. Implementations may
// choose how that 50 percent is determined.
//
// Support: Core for Kubernetes Service
//
Expand Down Expand Up @@ -933,21 +934,31 @@ type HTTPRequestMirrorFilter struct {
type HTTPBackendRef struct {
// BackendRef is a reference to a backend to forward matched requests to.
//
// If the referent cannot be found, this HTTPBackendRef is invalid and must
// be dropped from the Gateway. The controller must ensure the
// "ResolvedRefs" condition on the Route is set to `status: False` and not
// configure this backend in the underlying implementation.
// A BackendRef can be invalid for the following reasons. In all cases, the
// implementation MUST ensure the `ResolvedRefs` Condition on the Route
// is set to `status: False`, with a Reason and Message that indicate
// what is the cause of the error.
//
// If there is a cross-namespace reference to an *existing* object
// that is not covered by a ReferenceGrant, the controller must ensure the
// "ResolvedRefs" condition on the Route is set to `status: False`,
// with the "RefNotPermitted" reason and not configure this backend in the
// underlying implementation.
// A BackendRef is invalid if:
//
// In either error case, the Message of the `ResolvedRefs` Condition
// should be used to provide more detail about the problem.
// * It refers to an unknown or unsupported kind of resource. In this
// case, the Reason must be set to `InvalidKind` and Message of the
// Condition must explain which kind of resource is unknown or unsupported.
//
// * It refers to a resource that does not exist. In this case, the Reason must
// be set to `BackendNotFound` and the Message of the Condition must explain
// which resource does not exist.
//
// Support: Custom
// * It refers a resource in another namespace when the reference has not been
// explicitly allowed by a ReferenceGrant (or equivalent concept). In this
// case, the Reason must be set to `RefNotPermitted` and the Message of the
// Condition must explain which cross-namespace reference is not allowed.
//
// Support: Core for Kubernetes Service
//
// Support: Custom for any other resource
//
// Support for weight: Core
//
// +optional
BackendRef `json:",inline"`
Expand Down
9 changes: 9 additions & 0 deletions apis/v1alpha2/shared_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -246,6 +246,15 @@ const (
// another namespace, where the object in the other namespace does
// not have a ReferenceGrant explicitly allowing the reference.
RouteReasonRefNotPermitted RouteConditionReason = "RefNotPermitted"

// This reason is used with the "ResolvedRefs" condition when
// one of the Route's rules has a reference to an unknown or unsupported
// Group and/or Kind.
RouteReasonInvalidKind RouteConditionReason = "InvalidKind"

// This reason is used with the "ResolvedRefs" condition when one of the
// Route's rules has a reference to a resource that does not exist.
RouteReasonBackendNotFound RouteConditionReason = "BackendNotFound"
)

// RouteParentStatus describes the status of a route with respect to an
Expand Down
55 changes: 33 additions & 22 deletions apis/v1beta1/httproute_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,24 +201,25 @@ type HTTPRouteRule struct {
// BackendRefs defines the backend(s) where matching requests should be
// sent.
//
// A 500 status code MUST be returned if there are no BackendRefs or filters
// specified that would result in a response being sent.
// Failure behavior here depends on how many BackendRefs are specified and
// how many are invalid.
//
// A BackendRef is considered invalid when it refers to:
// If *all* entries in BackendRefs are invalid, and there are also no filters
// specified in this route rule, *all* traffic which matches this rule MUST
// receive a 500 status code.
//
// * an unknown or unsupported kind of resource
// * a resource that does not exist
// * a resource in another namespace when the reference has not been
// explicitly allowed by a ReferenceGrant (or equivalent concept).
// See the HTTPBackendRef definition for the rules about what makes a single
// HTTPBackendRef invalid.
//
// When a BackendRef is invalid, 500 status codes MUST be returned for
// When a HTTPBackendRef is invalid, 500 status codes MUST be returned for
// requests that would have otherwise been routed to an invalid backend. If
// multiple backends are specified, and some are invalid, the proportion of
// requests that would otherwise have been routed to an invalid backend
// MUST receive a 500 status code.
//
// When a BackendRef refers to a Service that has no ready endpoints, it is
// recommended to return a 503 status code.
// For example, if two backends are specified with equal weights, and one is
// invalid, 50 percent of traffic must receive a 500. Implementations may
// choose how that 50 percent is determined.
//
// Support: Core for Kubernetes Service
//
Expand Down Expand Up @@ -932,21 +933,31 @@ type HTTPRequestMirrorFilter struct {
type HTTPBackendRef struct {
// BackendRef is a reference to a backend to forward matched requests to.
//
// If the referent cannot be found, this HTTPBackendRef is invalid and must
// be dropped from the Gateway. The controller must ensure the
// "ResolvedRefs" condition on the Route is set to `status: False` and not
// configure this backend in the underlying implementation.
// A BackendRef can be invalid for the following reasons. In all cases, the
// implementation MUST ensure the `ResolvedRefs` Condition on the Route
// is set to `status: False`, with a Reason and Message that indicate
// what is the cause of the error.
//
// If there is a cross-namespace reference to an *existing* object
// that is not covered by a ReferenceGrant, the controller must ensure the
// "ResolvedRefs" condition on the Route is set to `status: False`,
// with the "RefNotPermitted" reason and not configure this backend in the
// underlying implementation.
// A BackendRef is invalid if:
//
// In either error case, the Message of the `ResolvedRefs` Condition
// should be used to provide more detail about the problem.
// * It refers to an unknown or unsupported kind of resource. In this
// case, the Reason must be set to `InvalidKind` and Message of the
// Condition must explain which kind of resource is unknown or unsupported.
//
// * It refers to a resource that does not exist. In this case, the Reason must
// be set to `BackendNotFound` and the Message of the Condition must explain
// which resource does not exist.
//
// Support: Custom
// * It refers a resource in another namespace when the reference has not been
// explicitly allowed by a ReferenceGrant (or equivalent concept). In this
// case, the Reason must be set to `RefNotPermitted` and the Message of the
// Condition must explain which cross-namespace reference is not allowed.
//
// Support: Core for Kubernetes Service
//
// Support: Custom for any other resource
//
// Support for weight: Core
//
// +optional
BackendRef `json:",inline"`
Expand Down
9 changes: 9 additions & 0 deletions apis/v1beta1/shared_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -246,6 +246,15 @@ const (
// another namespace, where the object in the other namespace does
// not have a ReferenceGrant explicitly allowing the reference.
RouteReasonRefNotPermitted RouteConditionReason = "RefNotPermitted"

// This reason is used with the "ResolvedRefs" condition when
// one of the Route's rules has a reference to an unknown or unsupported
// Group and/or Kind.
RouteReasonInvalidKind RouteConditionReason = "InvalidKind"

// This reason is used with the "ResolvedRefs" condition when one of the
// Route's rules has a reference to a resource that does not exist.
RouteReasonBackendNotFound RouteConditionReason = "BackendNotFound"
)

// RouteParentStatus describes the status of a route with respect to an
Expand Down
66 changes: 34 additions & 32 deletions config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml
View file
Open in desktop

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

Loading