Proto: retry_timeout_policy.proto

Package: resilience.policy.gloo.solo.io

Reduce transient failures and hanging systems by setting retries and timeouts.

Retries: A retry specifies the maximum number of times an Envoy proxy attempts to connect to a 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. The interval between retries (25ms+) is variable and determined automatically by Istio to prevent the called service from being overwhelmed with requests. The default retry behavior for HTTP requests is to retry twice before returning the error.

Like timeouts, Istio’s default retry behavior might not suit your application needs in terms of latency or availability. For example, too many retries to a failed service can slow things down. Also like timeouts, you can adjust your retry settings on a per-route basis. For more information, see the Istio documentation.

Timeouts: A timeout is the amount of time that an Envoy proxy waits for replies from a service, ensuring that services don’t hang around waiting for replies forever. This allows calls to succeed or fail within a predictable timeframe. By default, the Envoy timeout for HTTP requests is disabled in Istio. For some applications and services, Istio’s default timeout might not be appropriate. For example, a timeout that is too long can result in excessive latency from waiting for replies from failing services. On the other hand, a timeout that is too short can result in calls failing unnecessarily while waiting for an operation that needs responses from multiple services.

To find and use your optimal timeout settings, you can set timeouts dynamically per route. For more information, see the Istio documentation.

Examples

Retry only:

  apiVersion: resilience.policy.gloo.solo.io/v2
kind: RetryTimeoutPolicy
metadata:
  name: retry-only
  namespace: bookinfo
  annotations:
    cluster.solo.io/cluster: $REMOTE_CLUSTER1
spec:
  applyToRoutes:
    - route:
        labels:
          route: ratings # matches on route table route's labels
  config:
    retries:
      attempts: 5 # optional (default is 2)
      perTryTimeout: 2s
      # retryOn specifies the conditions under which retry takes place.
      # One or more policies can be specified using a ‘,’ delimited list.
      retryOn: "connect-failure,refused-stream,unavailable,cancelled,retriable-status-codes"
      # retryRemoteLocalities specifies whether the retries should retry to other localities, will default to false
      retryRemoteLocalities: true

Timeout:

  apiVersion: resilience.policy.gloo.solo.io/v2
kind: RetryTimeoutPolicy
metadata:
  name: retry-timeout
  namespace: bookinfo
  annotations:
    cluster.solo.io/cluster: $REMOTE_CLUSTER1
spec:
  applyToRoutes:
    - route:
        labels:
          route: ratings # matches on route table route's labels
  config:
    requestTimeout: 2s

RetryTimeoutPolicyReport

The resources that the policy selects after it is successfully applied.

FieldDescription
workspaces(repeated RetryTimeoutPolicyReport.WorkspacesEntry)

A list of workspaces in which the policy can apply to workloads.
selectedRoutes(repeated common.gloo.solo.io.RouteReference)

A list of references to all routes selected by the policy.

RetryTimeoutPolicyReport.WorkspacesEntry

FieldDescription
key(string)

value(common.gloo.solo.io.Report)

RetryTimeoutPolicySpec

Specifications for the policy.

FieldDescription
applyToRoutes(repeated common.gloo.solo.io.RouteSelector)

Routes to apply the policy to.

Implementation notes:
  • Only one RetryTimeoutPolicy can apply to a route. Subsequent policies (sorted by creation time) are ignored and put into a FAILED state.
  • If empty, the policy applies to all routes in the workspace.
config(RetryTimeoutPolicySpec.Config)

The details of the retry/timeout policy to apply to the selected routes.

Configuration constraints:
  • This field is required.
  • At least one of retries and request_timeout must be set.

RetryTimeoutPolicySpec.Config

The details of the retry/timeout policy to apply to the selected routes.


Configuration constraints:

  • This field is required.
  • At least one of `retries` and `request_timeout` must be set.
    • FieldDescription
    retries(RetryTimeoutPolicySpec.Config.RetryPolicy)

    Specify retries for failed requests.
    requestTimeout(google.protobuf.Duration)

    Set a timeout on requests that match the selected routes.

    Configuration constraints:
    • The value must be an integer or decimal value and a preferred unit, or multiple of these concatenated. Examples: 1m, 1h, 1.5h, 1s500ms
    • The value cannot have granularity smaller than milliseconds.
    • The value must be at least 1ms.
    • For information about the value format, see the ParseDuration documentation.

    RetryTimeoutPolicySpec.Config.RetryPolicy

    Specify retries for failed requests.

    FieldDescription
    attempts(google.protobuf.Int32Value)

    The number of retries for a failed request. The interval between retries is determined automatically (25ms+).

    Implementation notes:
    • When the requestTimeout or perTryTimeout fields are configured, the actual number of retries attempted also depends on those values.
    • The default value is 2 retries.
    • A value of 0 explicitly disable retries.
    • The maximum number of requests that can be made is 1 + attempts.

    Configuration constraints: If set, this value must be greater than or equal to 0. For information about the value format, see the Google protocol buffer documentation.
    perTryTimeout(google.protobuf.Duration)

    Timeout per retry attempt for a failed request. If unset, this field defaults to 0, which means that no timeout is set.

    Configuration constraints:
    • If attempts is 0, this field must not be set.
    • The value must be an integer or decimal value and a preferred unit, or multiple of these concatenated. Examples: 1m, 1h, 1.5h, 1s500ms
  • The value cannot have granularity smaller than milliseconds.
  • The value must be at least 1ms.
  • For information about the value format, see the ParseDuration documentation.
    • retryOn(string)

    The conditions under which a retry takes place. For more information, see the retry policies and gRPC retry policies in the Envoy docs.

    Configuration constraints:
    • If attempts is 0, this field must not be set.
    • The following values are supported. Specify multiple values in a comma-delimited list.
      • 5xx
      • gateway-error
      • reset
      • connect-failure
      • retriable-4xx
      • refused-stream
      • retriable-status-codes
      • retriable-headers
      • envoy-ratelimited
      • cancelled
      • deadline-exceeded
      • internal
      • resource-exhausted
      • unavailable
      • Any valid http status code
    retryRemoteLocalities(google.protobuf.BoolValue)

    Flag to specify whether the retries should retry to other localities. Defaults to false. For more information, see the retry plugin configuration in the Envoy docs.

    Configuration constraints: If attempts is 0, this field must not be set.

    RetryTimeoutPolicyStatus

    The status of the policy after it is applied to your Gloo environment.

    FieldDescription
    common(common.gloo.solo.io.Status)

    The state and workspace conditions of the applied resource.
    numSelectedRoutes(uint32)

    The number of routes selected by the policy.