nginx/nginx

Support more robust retries

Open

#1263 opened on Apr 13, 2026

View on GitHub
 (4 comments) (0 reactions) (0 assignees)C (30,331 stars) (7,903 forks)batch import
enhancementgood first issuerefined

Description

Feature Overview

In NGINX Gateway Fabric, we're looking to support Gateway API HTTPRoute Retries.

The API defines the following fields relating to retries:

  • codes defines the HTTP response status codes for which a backend request should be retried.
  • attempts specifies the maximum number of times an individual request from the gateway to a backend should be retried. If the maximum number of retries has been attempted without a successful response from the backend, the Gateway MUST return an error.
  • backoff specifies the minimum duration a Gateway should wait between retry attempts. An implementation MAY use an exponential or alternative backoff strategy for subsequent retry attempts, MAY cap the maximum backoff duration to some amount greater than the specified minimum, and MAY add arbitrary jitter to stagger requests, as long as unsuccessful backend requests are not retried before the configured minimum duration.

backend = upstream gateway/implementation = NGINX

This feature has a relationship with HTTPRoute Timeouts. See the Gateway API reference for more details.

The existing proxy_next_upstream directives seem to get close to supporting this feature, but not quite what we need.

The idea is that NGINX Gateway Fabric would take the values specified by a user in these two API fields and convert them to an NGINX configuration that satisfies the requirements set by the API specification.

Alternatives Considered

We originally looked at how to utilize proxy_next_upstream for this, however I don't believe it behaves quite how we want. This functionality retries the next server and then errors out if none are left. If a user wants 5 attempts, but only has 1 upstream server, this won't work. There could be a workaround by duplicating the same server 5 times in the upstream, but this seems a bit hacky. They also may have 3 servers, so which one would we duplicate? It's not a clean solution.

Also proxy_next_upstream_timeout appears to be a full timeout, instead of per-retry. It also doesn't support exponential backoff or jitter, which isn't technically required by the spec, but may be nice to support anyway.

Additional Context

API specification: https://gateway-api.sigs.k8s.io/reference/spec/#httprouteretry API design/proposal: https://gateway-api.sigs.k8s.io/geps/gep-1731/

Contributor guide

Tech stack
c
Domain
backendapi
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
5
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
over 1 week
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
NGINX configuration basicsHTTP retry conceptsGateway API specification
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
15
Research direction
Start by reviewing the existing proxy next upstream implementation in the NGINX source code (src/http/ngx http upstream.c). Understand the Gateway API retry specification from the linked GEP 1731 document. Then consider how to map the 'codes', 'attempts', and 'backoff' fields to NGINX configuration directives, possibly by introducing a new retry module or extending existing upstream logic. Evaluate the feasibility of using proxy next upstream with workarounds or if a custom retry mechanism is needed.