Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.1.x (latest)
  • 2.0.x
  • 1.9.x
  • 1.8.x
  • 1.7.x
  • 1.6.x
  • 1.5.x
  • 1.4.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
    • Introduction to Kong Mesh
    • What is Service Mesh?
    • How Kong Mesh works
    • Deployments
    • Version support policy
    • Stability
    • Release notes
    • Installation Options
    • Kubernetes
    • Helm
    • OpenShift
    • Docker
    • Amazon ECS
    • Amazon Linux
    • Red Hat
    • CentOS
    • Debian
    • Ubuntu
    • macOS
    • Windows
    • Explore Kong Mesh with the Kubernetes demo app
    • Explore Kong Mesh with the Universal demo app
    • Standalone deployment
    • Deploy a standalone control plane
    • Multi-zone deployment
    • Deploy a multi-zone global control plane
    • License
    • Overview
    • Data plane proxy
    • Data plane on Kubernetes
    • Data plane on Universal
    • Gateway
    • Zone Ingress
    • Zone Egress
    • CLI
    • GUI
    • Observability
    • Inspect API
    • Kubernetes Gateway API
    • Networking
    • Service Discovery
    • DNS
    • Kong Mesh CNI
    • Transparent Proxying
    • IPv6 support
    • Non-mesh traffic
    • Secure access across Kong Mesh components
    • Secrets
    • Kong Mesh API Access Control
    • API server authentication
    • Data plane proxy authentication
    • Zone proxy authentication
    • Data plane proxy membership
    • Dataplane Health
    • Fine-tuning
    • Control Plane Configuration
    • Upgrades
    • Requirements
    • Introduction
    • General notes about Kong Mesh policies
    • Applying Policies
    • How Kong Mesh chooses the right policy to apply
    • Understanding TargetRef policies
    • Protocol support in Kong Mesh
    • Mesh
    • Mutual TLS
    • Traffic Permissions
    • Traffic Route
    • Traffic Metrics
    • Traffic Trace
    • Traffic Log
    • Locality-aware Load Balancing
    • Fault Injection
    • Health Check
    • Circuit Breaker
    • Proxy Template
    • External Service
    • Retry
    • Timeout
    • Rate Limit
    • Virtual Outbound
    • MeshGateway
    • MeshGatewayRoute
    • Service Health Probes
    • MeshAccessLog (Beta)
    • MeshCircuitBreaker (Beta)
    • MeshFaultInjection (Beta)
    • MeshHealthCheck (Beta)
    • MeshHTTPRoute (Beta)
    • MeshProxyPatch (Beta)
    • MeshRateLimit (Beta)
    • MeshRetry (Beta)
    • MeshTimeout (Beta)
    • MeshTrace (Beta)
    • MeshTrafficPermission (Beta)
    • Overview
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPA policy support
    • MeshOPA (beta)
    • Multi-zone authentication
    • FIPS support
    • Certificate Authority rotation
    • Role-Based Access Control
    • UBI Images
    • Windows Support
    • Auditing
    • HTTP API
    • Annotations and labels in Kubernetes mode
    • Kong Mesh data collection
      • Mesh
      • CircuitBreaker
      • ExternalService
      • FaultInjection
      • HealthCheck
      • MeshGateway
      • MeshGatewayRoute
      • ProxyTemplate
      • RateLimit
      • Retry
      • Timeout
      • TrafficLog
      • TrafficPermission
      • TrafficRoute
      • TrafficTrace
      • VirtualOutbound
      • Dataplane
      • ZoneEgress
      • ZoneIngress
      • kuma-cp
      • kuma-dp
      • kumactl
    • Kuma-cp configuration reference
    • Open source License
    • Contribute to Mesh

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Usage
    • Example
    • HTTP
    • GRPC
    • TCP
  • Matching
  • Builtin Gateway support
Kong Mesh
2.1.x (latest)
  • Home
  • Kong Mesh
  • Policies
  • Retry

Retry

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

This policy enables Kong Mesh 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

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: Retry
mesh: default
metadata:
  name: web-to-backend-retry-policy
spec:
  sources:
  - match:
      kuma.io/service: web_default_svc_80
  destinations:
  - match:
      kuma.io/service: backend_default_svc_80
  conf:
    http:
      numRetries: 5
      perTryTimeout: 200ms
      backOff:
        baseInterval: 20ms
        maxInterval: 1s
      retriableStatusCodes:
      - 500
      - 504
      retriableMethods:
      - GET
    grpc:
      numRetries: 5
      perTryTimeout: 200ms
      backOff:
        baseInterval: 20ms
        maxInterval: 1s
      retryOn:
      - cancelled
      - deadline_exceeded
      - internal
      - resource_exhausted
      - unavailable
    tcp:
      maxConnectAttempts: 3

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

type: Retry
name: web-to-backend-retry-policy
mesh: default
sources:
- match:
    kuma.io/service: web
destinations:
- match:
    kuma.io/service: backend
conf:
  http:
    numRetries: 5
    perTryTimeout: 200ms
    backOff:
      baseInterval: 20ms
      maxInterval: 1s
    retriableStatusCodes:
    - 500
    - 504
    retriableMethods:
    - GET
    - DELETE
  grpc:
    numRetries: 5
    perTryTimeout: 200ms
    backOff:
      baseInterval: 20ms
      maxInterval: 1s
    retryOn:
    - cancelled
    - deadline_exceeded
    - internal
    - resource_exhausted
    - unavailable
  tcp:
    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

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

    retriableStatusCodes:
    - 418
    - 502
    - 503
    - 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:

      yaml retryOn: - gateway_error - connect_failure - 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:

      yaml retryOn: - cancelled - deadline_exceeded - internal - resource_exhausted - 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.

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023