You are browsing documentation for a version of Kuma that is not the latest release.

Looking for even older versions? Learn more.


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


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.


kind: Retry
mesh: default
  name: web-to-backend-retry-policy
  - match: web
  - match: backend
      numRetries: 5
      perTryTimeout: 200ms
        baseInterval: 20ms
        maxInterval: 1s
      - 500
      - 504
      numRetries: 5
      perTryTimeout: 200ms
        baseInterval: 20ms
        maxInterval: 1s
      - cancelled
      - deadline_exceeded
      - internal
      - resource_exhausted
      - unavailable
      maxConnectAttempts: 3

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


  • 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

    • baseDuration (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:

    - 418
    - 502
    - 503
    - 504

    Note that if you won’t provide retriableStatusCodes, the default behaviour of the policy is to retry:

    • when server responds with one of status codes: 502, 503 or 504,
    • when server won’t respond at all (disconnect/reset/read timeout),
    • when server resets the stream with a REFUSED_STREAM error code.


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:

     - cancelled
     - deadline_exceeded
     - internal
     - resource_exhausted
     - unavailable


  • 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.


Retry is an Outbound Connection Policy. The only supported value for destinations.match is

Last Updated: 11/3/2022, 09:04:22 AM