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
We will apply the configuration with kubectl apply -f [..]
.
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 to30ms
) -
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
and504
and if they also should be considered asretriable
you have to manually place them in the listFor example to add a status code
418
:If both
retriableStatusCodes
is provided in addition toretryOn
(below), but the latter doesn’t containretriable_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:Providing
retriable_status_codes
without also providingretriableStatusCodes
(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:
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
$schema: http://json-schema.org/draft-04/schema#
$ref: #/definitions/Retry
definitions
Retry
- ## Retry
- Type:
object
- This schema accepts additional properties.
- Properties
- sources
- List of selectors to match dataplanes that retry policy should be configured for
- Type:
array
- Items
- $ref: #/definitions/kuma.mesh.v1alpha1.Selector
- destinations
- List of selectors to match services that need to be health checked.
- Type:
array
- Items
- $ref: #/definitions/kuma.mesh.v1alpha1.Selector
- conf
- +required
- $ref: #/definitions/kuma.mesh.v1alpha1.Retry.Conf
- sources
kuma.mesh.v1alpha1.Retry.Conf
- ## Conf
- Type:
object
- This schema accepts additional properties.
- Properties
kuma.mesh.v1alpha1.Retry.Conf.BackOff
- ## Back Off
- Type:
object
- This schema accepts additional properties.
- Properties
- base_interval
- +required
- Type:
string
- String format must be a "regex"
- The value must match this pattern:
^([0-9]+\.?[0-9]*|\.[0-9]+)s$
- max_interval
- +optional
- Type:
string
- String format must be a "regex"
- The value must match this pattern:
^([0-9]+\.?[0-9]*|\.[0-9]+)s$
- base_interval
kuma.mesh.v1alpha1.Retry.Conf.Grpc
- ## Grpc
- Type:
object
- This schema accepts additional properties.
- Properties
- retry_on
- #### Retry On
- Type:
array
- Items
- The value is restricted to the following:
- "cancelled"
0
- "deadlineexceeded"_
1
- "internal"
2
- "resourceexhausted"_
3
- "unavailable"
4
- num_retries
- +optional
- Type:
integer
- pertrytimeout
- +optional
- Type:
string
- String format must be a "regex"
- The value must match this pattern:
^([0-9]+\.?[0-9]*|\.[0-9]+)s$
- back_off
- +optional
- $ref: #/definitions/kuma.mesh.v1alpha1.Retry.Conf.BackOff
- retry_on
kuma.mesh.v1alpha1.Retry.Conf.Http
- ## Http
- Type:
object
- This schema accepts additional properties.
- Properties
- num_retries
- +optional
- Type:
integer
- pertrytimeout
- +optional
- Type:
string
- String format must be a "regex"
- The value must match this pattern:
^([0-9]+\.?[0-9]*|\.[0-9]+)s$
- back_off
- +optional
- $ref: #/definitions/kuma.mesh.v1alpha1.Retry.Conf.BackOff
- retriablestatuscodes
- +optional
- Type:
array
- Items
- Type:
integer
- retriable_methods
- #### Http Method
- Type:
array
- Items
- The value is restricted to the following:
- "NONE"
0
- "CONNECT"
1
- "DELETE"
2
- "GET"
3
- "HEAD"
4
- "OPTIONS"
5
- "PATCH"
6
- "POST"
7
- "PUT"
8
- "TRACE"
9
- retry_on
- #### Http Retry On
- These options correspond with the retryon options in Envoy's documentation: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/httpfilters/routerfilter#config-http-filters-router-x-envoy-retry-on_
- Type:
array
- Items
- The value is restricted to the following:
- "all5xx"_
0
- "gatewayerror"_
1
- "reset"
2
- "connectfailure"_
3
- "envoyratelimited"_
4
- "retriable4xx"_
5
- "refusedstream"_
6
- "retriablestatuscodes"
7
- "retriableheaders"_
8
- "http3postconnectfailure"_
9
- num_retries
kuma.mesh.v1alpha1.Retry.Conf.Tcp
- ## Tcp
- Type:
object
- This schema accepts additional properties.
- Properties
- maxconnectattempts
- +optional
- Type:
integer
- maxconnectattempts
kuma.mesh.v1alpha1.Selector
- ## Selector
- Selector defines structure for selecting tags for given dataplane
- Type:
object
- This schema accepts additional properties.
- Properties
- match
- Tags to match, can be used for both source and destinations
- Type:
object
- This schema accepts additional properties.
- Properties
- match
Generated with json-schema-md-doc