Retries

Specify the number of times and duration you want kgateway to try a connection to an unresponsive backend service.

About retries

A retry specifies the maximum number of times kgateway attempts to connect to a backend service if the initial call fails. Retries can enhance service availability and application performance by making sure that calls don’t fail permanently because of transient problems such as a temporarily overloaded service or network.

To configure retries, you can use the following settings in the RouteOption resource:

• options.retries.retryOn : The condition under which to retry forwarding the request to the backend service. This setting exposes the x-envoy-retry-on Envoy header.
• options.retries.numRetries: The number of allowed retries. The default value is 1.
• options.retries.perTryTimeout: The timeout duration for each retry attempt. This setting exposes the x-envoy-expected-rq-timeout-ms header.

Before you begin

1. Follow the Get started guide to install kgateway.

2. Follow the Sample app guide to create an API gateway proxy with an HTTP listener and deploy the httpbin sample app.

3. Get the external address of the gateway and save it in an environment variable.

   Cloud Provider LoadBalancerPort-forward for local testing

   export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-system http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
   echo $INGRESS_GW_ADDRESS  

   kubectl port-forward deployment/http -n kgateway-system 8080:8080

Set up retries

Use a RouteOption resource to specify retries for a specific route.

1. Create a RouteOption custom resource to specify your retry rules. In the following example, the request is retried up to 3 times when a connection failure is detected. For each retry a timeout of 5 seconds is set.

   kubectl apply -n httpbin -f- <<EOF
   apiVersion: gateway.kgateway.dev/v1alpha1
   kind: RouteOption
   metadata:
     name: retry
     namespace: httpbin
   spec:
     options:
       retries:
         retryOn: 'connect-failure'
         numRetries: 3
         perTryTimeout: '5s'
   EOF

2. Create an HTTPRoute resource for the httpbin app that references the RouteOption resource that you created.

   kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: httpbin-retry
     namespace: httpbin
   spec:
     parentRefs:
     - name: http
       namespace: kgateway-system
     hostnames:
       - retry.example
     rules:
       - filters:
           - type: ExtensionRef
             extensionRef:
               group: gateway.solo.io
               kind: RouteOption
               name: retry
         backendRefs:
           - name: httpbin
             port: 8000
   EOF

3. Send a request to the httpbin app on the retry.example domain. Verify that the request succeeds and that you see a X-Envoy-Expected-Rq-Timeout-Ms header. If the header is present, kgateway expects requests to the httpbin app to succeed within the set timeout.

   LoadBalancer IP address or hostnamePort-forward for local testing

   curl -vik http://$INGRESS_GW_ADDRESS:8080/headers -H "host: retry.example:8080"

   curl -vik localhost:8080/headers -H "host: retry.example"

   Example output for a successful response:

   {
    "headers": {
      "Accept": [
        "*/*"
      ],
      "Host": [
        "timeout.example:8080"
      ],
      "User-Agent": [
        "curl/7.77.0"
      ],
      "X-Envoy-Expected-Rq-Timeout-Ms": [
        "5000"
      ],
      "X-Forwarded-Proto": [
        "http"
      ],
      "X-Request-Id": [
        "0ae53bc3-2644-44f2-8603-158d2ccf9f78"
      ]
    }
   }
   

4. Optional: Remove the resources that you created.

   kubectl delete httproute httpbin-retry -n httpbin
   kubectl delete routeoption retry -n httpbin