HTTP retries

Configure HTTP retries in ambient mesh to automatically retry failed requests before returning an error to the client.

When a waypoint proxy sends a request to an upstream service and the request fails due to a transient error, retries allow the proxy to reattempt the request before returning an error to the client. Retries improve the reliability of services without requiring changes to application code.

Note

HTTP retries require a waypoint proxy because retry logic is applied at Layer 7.

Before you begin

Install an ambient mesh in your cluster.
Label the default namespace to add it to the ambient mesh.
```
kubectl label ns default istio.io/dataplane-mode=ambient
```
Create a waypoint for the default namespace. A waypoint is required because this resiliency feature configures Layer 7 (L7) proxy behavior. For more information on using waypoints, see Configure waypoints.
```
istioctl waypoint apply -n default --enroll-namespace --wait
```

Configure a global retry policy

Use meshConfig.defaultHttpRetryPolicy to apply a retry policy to all inbound HTTP routes on waypoint proxies in the mesh. This setting is useful when you want consistent retry behavior across all services without creating per-service resources.

Upgrade istiod with a defaultHttpRetryPolicy. The following example retries on gateway errors and connection resets, with a 2-second per-attempt timeout and up to 3 attempts.

helm upgrade istiod istio/istiod \
  --namespace istio-system \
  --reuse-values \
  --set meshConfig.defaultHttpRetryPolicy.retryOn="gateway-error,reset" \
  --set meshConfig.defaultHttpRetryPolicy.perTryTimeout="2s" \
  --set meshConfig.defaultHttpRetryPolicy.attempts=3

Verify that the retry policy is applied by checking the istiod mesh config.

kubectl get configmap istio -n istio-system -o jsonpath='{.data.mesh}' | grep -A5 defaultHttpRetryPolicy

Example output:

defaultHttpRetryPolicy:
  attempts: 3
  perTryTimeout: 2s
  retryOn: gateway-error,reset

Configure per-service retries

Use an HTTPRoute resource to configure retries for a specific service. Per-service retry configuration takes precedence over the global defaultHttpRetryPolicy for that service.

Note

The retry field on HTTPRoute is an experimental Gateway API feature. It is supported when traffic is routed through a waypoint proxy in ambient mode.

Deploy the httpbin service and a curl client to test the retry policy.

kubectl apply -f https://raw.githubusercontent.com/istio/istio/1.30.0/samples/httpbin/httpbin.yaml
kubectl apply -f https://raw.githubusercontent.com/istio/istio/1.30.0/samples/curl/curl.yaml

Create an HTTPRoute for your service with a retry rule.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-retry
spec:
  parentRefs:
  - group: ""
    kind: Service
    name: httpbin
    port: 8000
  rules:
  - backendRefs:
    - name: httpbin
      port: 8000
    retry:
      codes:
      - 503
      attempts: 3
      backoff: 100ms
EOF

Verify that the HTTPRoute was accepted.
```
kubectl get httproute httpbin-retry
```
Send a request that returns a 503 to trigger the retry policy.
```
kubectl exec deploy/curl -- curl -s -o /dev/null -w "%{http_code}\n" httpbin:8000/status/503
```
Because httpbin always returns 503 for this endpoint, the waypoint retries up to 3 times before returning the final response to the client:
```
503
```

Cleanup

Delete the sample resources.

kubectl delete httproute httpbin-retry
kubectl delete -f https://raw.githubusercontent.com/istio/istio/1.30.0/samples/httpbin/httpbin.yaml
kubectl delete -f https://raw.githubusercontent.com/istio/istio/1.30.0/samples/curl/curl.yaml

To remove the global retry policy, upgrade istiod without the defaultHttpRetryPolicy values.

Request timeouts Circuit breakers