Graduate GEP-2257 and GEP-1742 to standard

[kflynn]

What type of PR is this?
/kind gep

REVIEWERS: this PR has been rebased to be best reviewed commit by commit:

• 905d806: Actually move from experimental to standard
• 767798b: Fix a couple of old typos in GEP-1742
• 30d9acb: Clean up language in GEP-2257 around repeated units
• dcc2438: Mention GEP-2257 in the CRD docstrings (I ran into this today for unrelated reasons) and clarify that if the backend request timeout isn't specified, behavior is implementation-specific.
• fc64635: Run make generate

What this PR does / why we need it:
This PR moves GEPs 2257 and 1742 to Standard rather than Experimental. Conformant implementations of HTTPRouteRequestTimeout and HTTPRouteBackendTimeout as of Gateway API v1.0.0:

• Cilium v1.15.0-pre.3
• Contour v1.29.0
• Envoy Gateway v0.6.0
• Istio 1.2

(All of these implementations support both timeout fields. I'm referencing 1.0.0 because we don't have many 1.1.0 conformance reports yet. 😐)

Does this PR introduce a user-facing change?:

GEP-2257 Durations and HTTPRoute Timeouts are now standard.

[mikemorris]

I think it would be good to at least enumerate three conformant implementations in this PR before merging. From https://gateway-api.sigs.k8s.io/implementations/v1.1/ and https://gateway-api.sigs.k8s.io/implementations/v1.0/ it appears Istio, Cilium and Contour support both HTTPRouteRequestTimeout and HTTPRouteBackendTimeout, and Kong's kubernetes-ingress-controller supports HTTPRouteBackendTimeout - are we missing others who have implemented this so far?

[youngnick]

Yes, this LGTM once we have the relevant implementations called out, with one caveat - the YAML files also need to have the status updated.

[robscott]

IMO, it's not necessary to complete these parsers before the GEP freeze in 1 week, but it is necessary to complete these parsers before the end of the API refinement phase (likely +4 weeks per https://gateway-api.sigs.k8s.io/contributing/release-cycle/#3-api-refinement-and-documentation). We should definitely clean up this guidance before our next release.

Interested in what others think here though:
/cc @youngnick @mlavacca

[youngnick]

Agreed.

[kflynn]

Sounds good from here, too.

[mlavacca]

I agree as well

[kflynn]

@mikemorris writes:

I think it would be good to at least enumerate three conformant implementations in this PR before merging. From https://gateway-api.sigs.k8s.io/implementations/v1.1/ and https://gateway-api.sigs.k8s.io/implementations/v1.0/ it appears Istio, Cilium and Contour support both HTTPRouteRequestTimeout and HTTPRouteBackendTimeout, and Kong's kubernetes-ingress-controller supports HTTPRouteBackendTimeout - are we missing others who have implemented this so far?

Updated the PR description. Envoy Gateway also implements both timeouts. Kong is the only one that claimed conformance with only one of the timeouts, and actually they don't claim to be conformant for v1.1.0 -- I'm curious about that, so I'm poking around a bit. 🙂

FTR I definitely like the idea that we should mention the conformant implementations for these kinds of GEP changes!

[kflynn]

Yes, this LGTM once we have the relevant implementations called out, with one caveat - the YAML files also need to have the status updated.

🤦‍♂️ Yes, fixed. 🤦‍♂️

[mikemorris]

/lgtm

[youngnick]

I can't see the YAML file changes, did you miss pushing? Once those are in, this LGTM.

[kflynn]

@youngnick writes:

I can't see the YAML file changes, did you miss pushing? Once those are in, this LGTM.

🤔 Do you see three commits in the PR? The last one (d868630) has the YAML changes.

(Not gonna lie, I've forgotten a push many a time. 🤦‍♂️ But in this specific case it looks OK from my end?)

[youngnick]

Ah, I wasn't clear which YAML files I meant, sorry (now there's a perennial Kubernetes sentence for you!). There's also the GEP metadata YAML files stored in the geps/ directories that need updating.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: kflynn, mlavacca

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [mlavacca]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[kflynn]

@youngnick writes:

Ah, I wasn't clear which YAML files I meant, sorry (now there's a perennial Kubernetes sentence for you!). There's also the GEP metadata YAML files stored in the geps/ directories that need updating.

🤦‍♂️ Thanks for the catch, perennial confusion or no. This should be updated.

I've rebased this onto main, cleaned up the git history, and re-requested reviews. This is now best reviewed commit by commit; see the opening comment on the PR for details.

[mikemorris]

/lgtm

[mpstefan]

I know that this one is ready to go, but I wanted to mention again that nginx is unable to add this kind of timeout by default, so keeping this as extended would be much preferred.

For anyone curious, the nginx timeout directives are keeping track of timeouts not by HTTP request, but by the entire upstream - likely because it works with many different protocols and network layers. Which means if we set a "timeout" of 10s, and one request hangs, but the others continue and return from the upstream as normal, the hanging request would hang past 10 seconds because the upstream responded in time. We'd need to design our own module to keep track of a per http request timeout.

[kflynn]

I know that this one is ready to go, but I wanted to mention again that nginx is unable to add this kind of timeout by default, so keeping this as extended would be much preferred.

Right -- we are indeed keeping it extended in this PR.

That said, this bit:

...if we set a "timeout" of 10s, and one request hangs, but the others continue and return from the upstream as normal...

is fascinating to me; I wonder if we need to update the diagram for NGINX. Are you talking about a single request from a client spawning multiple requests to upstream workloads? or multiple client requests going to the same upstream? or what, exactly? 🙂 (Please feel free to toss me a link to RTFM if that's warranted! 🙂)

[youngnick]

Looks like all the feedback has been addressed, so I'm going to merge this one in - but I feel it's worth just clarifying for @mpstefan and anyone else who sees this issue what's happening in this one.

This one moves the GEPs for Durations and Timeouts to Standard , which is a measure of API stability. This means that we are guaranteeing that there will be no backwards-incompatible changes to these APIs forever (basically).

The Timeouts feature is still Extended though, which means that it's optional, but conformance tested. I understand that Nginx can't support this mode, and that's why it's staying as Extended for now (and there's a reasonable chance it will forever as well).

/unhold