Skip to content

gep: align GEP-1731 retry semantics with implementations - #5167

Merged
kubernetes-prow[bot] merged 3 commits into
kubernetes-sigs:mainfrom
snorwin:gep-1731
Sep 16, 2026
Merged

kubernetes-prow[bot] merged 3 commits into
kubernetes-sigs:mainfrom
snorwin:gep-1731

Conversation

@snorwin

@snorwin snorwin commented Aug 14, 2026 •

Copy link
Copy Markdown
Member

What type of PR is this?

/kind gep

What this PR does / why we need it:
GEP-1731 currently specifies backoff as "the minimum duration a Gateway should wait between retry attempts". None of the current implementations provide this guarantee. Airlock Microgateway, Istio, Envoy Gateway and kgateway all mapbackoff to Envoy's retry_back_off.base_interval.

In addition, this PR clarifies the retry behavior on connection errors. The previous wording ("disconnect, reset, timeout, TCP failure") included conditions where the request may already have been sent and processed.

Which issue(s) this PR fixes:

Fixes #

Does this PR introduce a user-facing change?:

NONE

AI Disclosure
AI (Claude;Fable 5) was used only for spell-checking and minor rephrasing suggestions.

@kubernetes-prow kubernetes-prow Bot added release-note-none Denotes a PR that doesn't merit a release note. kind/gep PRs related to Gateway Enhancement Proposal(GEP) labels Aug 14, 2026
@kubernetes-prow
kubernetes-prow Bot requested a review from howardjohn August 14, 2026 09:44
@kubernetes-prow kubernetes-prow Bot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Aug 14, 2026
@kubernetes-prow
kubernetes-prow Bot requested a review from kflynn August 14, 2026 09:44
@kubernetes-prow kubernetes-prow Bot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Aug 14, 2026
@snorwin

snorwin commented Aug 14, 2026

Copy link
Copy Markdown
Member Author

/cc @mikemorris @rikatz

@kubernetes-prow
kubernetes-prow Bot requested review from mikemorris and rikatz August 14, 2026 09:44
@snorwin

snorwin commented Aug 14, 2026

Copy link
Copy Markdown
Member Author

/retest

Signed-off-by: Norwin Schnyder <norwin.schnyder+github@gmail.com>
Comment thread geps/gep-1731/index.md Resolved
Comment thread geps/gep-1731/index.md Resolved
Signed-off-by: Norwin Schnyder <norwin.schnyder+github@gmail.com>
@snorwin
snorwin requested a review from rikatz August 18, 2026 07:59
@rikatz

rikatz commented Aug 18, 2026

Copy link
Copy Markdown
Member

/lgtm
@mikemorris if you can take a second look please

@youngnick @robscott for approval, as I am biased on this one

@kubernetes-prow kubernetes-prow Bot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 18, 2026
@rikatz

rikatz commented Aug 18, 2026

Copy link
Copy Markdown
Member

/cc @youngnick @robscott

Comment thread geps/gep-1731/index.md Resolved
Comment thread geps/gep-1731/index.md
//
// +optional
// <gateway:experimental>
// +listType=set

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This isn't the actual types, but we need to ensure that <gateway:experimental> stays until the feature graduates to Standard...

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Yes, this only applies to the GEP. The other fields that are also considered experimental don't have the marker too.

Once we have agreed on the changes, I'm going to add them to the API as well.

Comment thread geps/gep-1731/index.md
// `100ms` will cause a backend request to first be retried approximately
// 100 milliseconds after timing out or receiving a response code configured
// to be retriable.
// The maximum duration a Gateway should wait before a retry attempt is

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This mandates that implementations must use exponential backoff, right? We didn't want to mandate that before, although it seems like it's almost always a better idea.

@snorwin snorwin Aug 26, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

The most common backoff strategies are:

  • none
  • fixed
  • linear
  • exponential

(Each of these can be combined with jitter and with a max cap)

For HTTP traffic, IMO the most common choice is capped exponential backoff with full jitter.

HAProxy and NGINX support only none. Traefik and Envoy support capped exponential backoff with jitter.

Before this change, backoff was specified as a lower bound on the retry interval a semantic that none of these data plane technologies can satisfy.

@mikemorris mikemorris Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

For posterity, my original intent with the phrasing of minimum here was to capture constant, linear and exponential backoff strategies (without being prescriptive, and none could be implemented as simply not supporting backoff at all, as exponential is often preferable but not implemented universally or necessarily with the exact same algorithm in all dataplanes), such that with backoff: 100ms various strategies could plausibly look like:

exponential

min(((Base * 2^(attempt-1)) + Jitter), MaxDelay)

5xx -> wait (100 * 2^1 - 1 = 1) = 100)ms -> 5xx -> wait (100 * 2^2 - 1 = 3) = 300)ms -> 5xx -> wait (100 * 2^3 - 1 = 7) = 700)ms

100ms initial backoff, 1100ms total delays excluding request time

linear

min(((Base * attempt) + Jitter), MaxDelay)

5xx -> wait (100 * 1 = 100)ms -> 5xx -> wait (100 * 2 = 200)ms -> 5xx -> wait (100 * 3 = 300)ms

100ms initial backoff, 600ms total delays excluding request time

constant

Base + Jitter

5xx -> wait 100ms -> 5xx -> wait 100ms -> 5xx -> wait 100ms

100ms initial backoff, 300ms total delays excluding request time

That said, I think the revisions here do capture the same intent I had, with a bit more precision in specifics of jitter (which I think is typically added though, not subtracted, which is how I got to a minimum value rather than maximum) and max delay implementation variables. I'm good with leaving this impl-specific for v1.7, but I am still curious whether a minimum value (with explicit behavior exceptions for Retry-After headers as described at https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-retrypolicy-rate-limited-retry-back-off) is actually able to be successfully tested in conformance.

EDIT: After investigating more closely in #5347 (comment), I'm now confident backoff can't move to Extended with conformance tests, and should graduate to standard as implementation-specific.

Signed-off-by: Norwin Schnyder <norwin.schnyder+github@gmail.com>
@kubernetes-prow kubernetes-prow Bot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 26, 2026
@snorwin

snorwin commented Aug 26, 2026

Copy link
Copy Markdown
Member Author

/retest

@snorwin

snorwin commented Sep 8, 2026

Copy link
Copy Markdown
Member Author

@kubernetes-sigs/gateway-api-maintainers if we want HTTP retries graduating in v1.7, this needs to be merged soon, PTAL.

@rikatz

rikatz commented Sep 16, 2026

Copy link
Copy Markdown
Member

/lgtm
/approve
/hold cancel
I think this is overdue. Given we are moving backoff to implementation specific, and with a proper definition, we should move forward on it. If we decide to promote this to extended, we can

@kubernetes-prow kubernetes-prow Bot added lgtm "Looks good to me", indicates that a PR is ready to be merged. and removed do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. labels Sep 16, 2026
@kubernetes-prow

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: rikatz, snorwin

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

The pull request process is described here

Details Needs approval from an approver in each of these files:

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

@kubernetes-prow kubernetes-prow Bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Sep 16, 2026
@kubernetes-prow
kubernetes-prow Bot merged commit 65b6c78 into kubernetes-sigs:main Sep 16, 2026
20 of 21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/gep PRs related to Gateway Enhancement Proposal(GEP) lgtm "Looks good to me", indicates that a PR is ready to be merged. release-note-none Denotes a PR that doesn't merit a release note. size/M Denotes a PR that changes 30-99 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants