ingress/docs/content/reference/routing-configuration/http/middlewares/retry.md

title, description

title	description
Hanzo Ingress HTTP Retry Documentation	Configure Hanzo Ingress's HTTP Retry middleware, so you can retry requests to a backend server until it succeeds. Read the technical documentation.

The retry middleware retries requests a given number of times to a backend server if that server does not reply.
As soon as the server answers, the middleware stops retrying, regardless of the response status.

The Retry middleware has an optional configuration to enable an exponential backoff.

Configuration Examples

# Retry 4 times with exponential backoff
http:
  middlewares:
    test-retry:
      retry:
        attempts: 4
        initialInterval: 100ms
        timeout: 60s
        maxRequestBodyBytes: 1024
        status: 
          - "400"
          - "500-599"
        disableRetryOnNetworkError: true
        retryNonIdempotentMethod: true

# Retry 4 times with exponential backoff
[http.middlewares]
  [http.middlewares.test-retry.retry]
    attempts = 4
    initialInterval = "100ms"
    timeout = "60s"
    maxRequestBodyBytes = 1024
    status = ["400","500-599"]
    disableRetryOnNetworkError = true
    retryNonIdempotentMethod = true

# Retry 4 times with exponential backoff
labels:
  - "ingress.http.middlewares.test-retry.retry.attempts=4"
  - "ingress.http.middlewares.test-retry.retry.initialinterval=100ms"
  - "ingress.http.middlewares.test-retry.retry.timeout=60s"
  - "ingress.http.middlewares.test-retry.retry.maxrequestbodybytes=1024"
  - "ingress.http.middlewares.test-retry.retry.status=400,500-599"
  - "ingress.http.middlewares.test-retry.retry.disableretryonnetworkerror=true"
  - "ingress.http.middlewares.test-retry.retry.retrynonidempotentmethod=true"

// Retry 4 times with exponential backoff

{
  // ...
  "Tags" : [
    "ingress.http.middlewares.test-retry.retry.attempts=4",
    "ingress.http.middlewares.test-retry.retry.initialinterval=100ms",
    "ingress.http.middlewares.test-retry.retry.timeout=60s",
    "ingress.http.middlewares.test-retry.retry.maxrequestbodybytes=1024",
    "ingress.http.middlewares.test-retry.retry.status=400,500-599",
    "ingress.http.middlewares.test-retry.retry.disableretryonnetworkerror=true",
    "ingress.http.middlewares.test-retry.retry.retrynonidempotentmethod=true"
  ]
}

# Retry 4 times with exponential backoff
apiVersion: hanzo.ai/v1alpha1
kind: Middleware
metadata:
  name: test-retry
spec:
  retry:
    attempts: 4
    initialInterval: 100ms
    timeout: 60s
    maxRequestBodyBytes: 1024
    status: 
      - "400"
      - "500-599"
    disableRetryOnNetworkError: true
    retryNonIdempotentMethod: true

Configuration Options

Field	Description	Default	Required
attempts	number of times the request should be retried.		Yes
initialInterval	First wait time in the exponential backoff series. The maximum interval is calculated as twice the initialInterval. If unspecified, requests will be retried immediately. Defined in seconds or as a valid duration format, see time.ParseDuration.	0	No
timeout	How much time the middleware is allowed to retry the request. Defined in seconds or as a valid duration format, see time.ParseDuration.	0	No
maxRequestBodyBytes	Defines the maximum size for the request body. Default is -1, which means no limit. More information here.	-1	No
status	Defines the range of HTTP status codes to retry on. More information here.	[]	No
disableRetryOnNetworkError	This option disables the retry if an error occurs when transmitting the request to the server. More information here.	false	No
retryNonIdempotentMethod	Activates the retry for non-idempotent methods (POST, LOCK, PATCH)	false	No

maxRequestBodyBytes

The maxRequestBodyBytes option controls the maximum size of request bodies that will be sent to the server.

⚠️ Important Security Consideration

By default, maxRequestBodyBytes is not set (value: -1), which means request body size is unlimited. This can have significant security and performance implications:

• Security Risk: Attackers can send extremely large request bodies, potentially causing DoS attacks or memory exhaustion
• Performance Impact: Large request bodies consume memory and processing resources, affecting overall system performance
• Resource Consumption: Unlimited body size can lead to unexpected resource usage patterns

Recommended Configuration

It is strongly recommended to set an appropriate maxRequestBodyBytes value for your use case:

# For most web applications (1MB limit)
maxRequestBodyBytes: 1048576  # 1MB in bytes

# For API endpoints expecting larger payloads (10MB limit)  
maxRequestBodyBytes: 10485760  # 10MB in bytes

# For file upload authentication (100MB limit)
maxRequestBodyBytes: 104857600  # 100MB in bytes

Guidelines for Setting maxRequestBodyBytes

• Web Forms: 1-5MB is typically sufficient for most form submissions
• API Endpoints: Consider your largest expected JSON/XML payload + buffer
• File Uploads: Set based on your maximum expected file size
• High-Traffic Services: Use smaller limits to prevent resource exhaustion

disableRetryOnNetworkError and status

The disableRetryOnNetworkError option disables the retry if an error occurs when transmitting the request to the server, at the TCP layer. However, if you want to retry only for specific HTTP status codes, you can configure the status option with the relevant status codes to retry on.

If disableRetryOnNetworkError is set to true, you must define the status option. Otherwise, the middleware will raise a configuration error.