Retry

New to Kuma? Don’t use this policy, check MeshRetry instead. If you want to use the Retry policy, remember that it requires the TrafficRoute policy to function properly.

Retry is an outbound policy. Dataplanes whose configuration is modified are in the sources matcher.

This policy enables Kuma to know how to behave if there is a failed scenario (i.e. HTTP request) which could be retried.

Usage

As usual, we can apply sources and destinations selectors to determine how retries will be performed across our data plane proxies.

The policy let you configure retry behaviour for HTTP, GRPC and TCP protocols.

Example

  1. apiVersion: kuma.io/v1alpha1
  2. kind: Retry
  3. mesh: default
  4. metadata:
  5.   name: web-to-backend-retry-policy
  6. spec:
  7.   sources:
  8.   - match:
  9.       kuma.io/service: web_default_svc_80
  10.   destinations:
  11.   - match:
  12.       kuma.io/service: backend_default_svc_80
  13.   conf:
  14.     http:
  15.       numRetries: 5
  16.       perTryTimeout: 200ms
  17.       backOff:
  18.         baseInterval: 20ms
  19.         maxInterval: 1s
  20.       retriableStatusCodes:
  21.       - 500
  22.       - 504
  23.       retriableMethods:
  24.       - GET
  25.     grpc:
  26.       numRetries: 5
  27.       perTryTimeout: 200ms
  28.       backOff:
  29.         baseInterval: 20ms
  30.         maxInterval: 1s
  31.       retryOn:
  32.       - cancelled
  33.       - deadline_exceeded
  34.       - internal
  35.       - resource_exhausted
  36.       - unavailable
  37.     tcp:
  38.       maxConnectAttempts: 3

We will apply the configuration with kubectl apply -f [..].

  1. type: Retry
  2. name: web-to-backend-retry-policy
  3. mesh: default
  4. sources:
  5. - match:
  6.     kuma.io/service: web
  7. destinations:
  8. - match:
  9.     kuma.io/service: backend
  10. conf:
  11.   http:
  12.     numRetries: 5
  13.     perTryTimeout: 200ms
  14.     backOff:
  15.       baseInterval: 20ms
  16.       maxInterval: 1s
  17.     retriableStatusCodes:
  18.     - 500
  19.     - 504
  20.     retriableMethods:
  21.     - GET
  22.     - DELETE
  23.   grpc:
  24.     numRetries: 5
  25.     perTryTimeout: 200ms
  26.     backOff:
  27.       baseInterval: 20ms
  28.       maxInterval: 1s
  29.     retryOn:
  30.     - cancelled
  31.     - deadline_exceeded
  32.     - internal
  33.     - resource_exhausted
  34.     - unavailable
  35.   tcp:
  36.     maxConnectAttempts: 3

We will apply the configuration with kumactl apply -f [..] or via the HTTP API.

HTTP

  • numRetries (optional)

    Amount of attempts which will be made on failed (and retriable) requests

  • perTryTimeout (optional)

    Amount of time after which retry attempt should timeout (i.e. all the values: 30000000ns, 30ms, 0.03s, 0.0005m are equivalent and can be used to express the same timeout value, equal to 30ms)

  • backOff (optional)

    Configuration of durations which will be used in exponential backoff strategy between retries

    • baseInterval (required)

      Base amount of time which should be taken between retries (i.e. 30ms, 0.03s, 0.0005m)

    • maxInterval (optional)

      A maximal amount of time which will be taken between retries (i.e. 1s, 0.5m)

  • retriableStatusCodes (optional)

    A list of status codes which will cause the request to be retried. When this field will be provided it will overwrite the default behaviour of accepting as retriable codes: 502, 503 and 504 and if they also should be considered as retriable you have to manually place them in the list

    For example to add a status code 418:

    1. retriableStatusCodes:
    2. - 418
    3. - 502
    4. - 503
    5. - 504

    If both retriableStatusCodes is provided in addition to retryOn (below), but the latter doesn’t contain retriable_status_codes as a condition, it will be automatically added.

  • retryOn (optional)

    List of conditions which will cause a retry.

    Acceptable values

    • all_5xx
    • gateway_error
    • reset
    • connect_failure
    • envoy_ratelimited
    • retriable_4xx
    • refused_stream
    • retriable_status_codes
    • retriable_headers
    • http3_post_connect_failure

    Note that if retryOn is not defined or if it’s empty, the policy will default to the equivalent of:

    1. retryOn:
    2.  - gateway_error
    3.  - connect_failure
    4.  - refused_stream

    Providing retriable_status_codes without also providing retriableStatusCodes (above) will fail policy validation.

  • retriableMethods (optional)

    A list of HTTP methods in which a request’s method must be contained before that request can be retried. The default behavior is that all methods are retriable.

GRPC

You can configure your GRPC Retry policy in similar fashion as the HTTP one with the only difference of the retryOn property which replace the retriableStatusCodes from the HTTP policy

  • retryOn (optional)

    List of values which will cause retry.

    Acceptable values

    • cancelled
    • deadline_exceeded
    • internal
    • resource_exhausted
    • unavailable

    Note that if retryOn is not defined or if it’s empty, the policy will default to all values and is equivalent to:

    1. retryOn:
    2.  - cancelled
    3.  - deadline_exceeded
    4.  - internal
    5.  - resource_exhausted
    6.  - unavailable

TCP

  • maxConnectAmount (required)

    A maximal amount of TCP connection attempts which will be made before giving up

    This policy will make attempt to retry the TCP connection which fail to be established and will be applied in the scenario when both, the dataplane, and the TCP service matched as a destination will be down.

Matching

Retry is an Outbound Connection Policy. The only supported value for destinations.match is kuma.io/service.

Builtin Gateway support

Retries can be configured on each route by matching the Retry connection policy to the backend destination tags.

All options