openapi: 3.1.0 info: title: Kuma Dataplane MeshRetry API description: Kuma API version: v1alpha1 x-ref-schema-name: DataplaneOverview security: - BasicAuth: [] - BearerAuth: [] - {} tags: - name: MeshRetry paths: /meshes/{mesh}/meshretries/{name}: get: operationId: getMeshRetry summary: Returns MeshRetry entity tags: - MeshRetry parameters: - in: path name: mesh schema: type: string required: true description: name of the mesh - in: path name: name schema: type: string required: true description: name of the MeshRetry responses: '200': $ref: '#/components/responses/MeshRetryItem' '404': $ref: '#/components/responses/NotFound' put: operationId: putMeshRetry summary: Creates or Updates MeshRetry entity tags: - MeshRetry parameters: - in: path name: mesh schema: type: string required: true description: name of the mesh - in: path name: name schema: type: string required: true description: name of the MeshRetry requestBody: description: Put request required: true content: application/json: schema: $ref: '#/components/schemas/MeshRetryItem' responses: '200': $ref: '#/components/responses/MeshRetryCreateOrUpdateSuccessResponse' '201': $ref: '#/components/responses/MeshRetryCreateOrUpdateSuccessResponse' delete: operationId: deleteMeshRetry summary: Deletes MeshRetry entity tags: - MeshRetry parameters: - in: path name: mesh schema: type: string required: true description: name of the mesh - in: path name: name schema: type: string required: true description: name of the MeshRetry responses: '200': $ref: '#/components/responses/MeshRetryDeleteSuccessResponse' '404': $ref: '#/components/responses/NotFound' /meshes/{mesh}/meshretries: get: operationId: getMeshRetryList summary: Returns a list of MeshRetry in the mesh. tags: - MeshRetry parameters: - in: query name: offset description: offset in the list of entities required: false schema: type: integer example: 0 - in: query name: size description: the number of items per page required: false schema: type: integer default: 100 maximum: 1000 minimum: 1 - in: query name: filter description: filter by labels when multiple filters are present, they are ANDed required: false schema: type: object properties: key: type: string value: type: string example: label.k8s.kuma.io/namespace: my-ns - in: path name: mesh schema: type: string required: true description: name of the mesh responses: '200': $ref: '#/components/responses/MeshRetryList' components: responses: NotFound: description: Not Found content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundError' MeshRetryItem: description: Successful response content: application/json: schema: $ref: '#/components/schemas/MeshRetryItem' MeshRetryDeleteSuccessResponse: description: Successful response content: application/json: schema: type: object MeshRetryList: description: List content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/MeshRetryItem' total: type: number description: The total number of entities next: type: string description: URL to the next page MeshRetryCreateOrUpdateSuccessResponse: description: Successful response content: application/json: schema: type: object properties: warnings: type: array readOnly: true description: 'warnings is a list of warning messages to return to the requesting Kuma API clients. Warning messages describe a problem the client making the API request should correct or be aware of. ' items: type: string schemas: MeshRetryItem: type: object description: MeshRetry configures automatic retry behavior for failed requests to improve service reliability. It supports configurable retry conditions, limits, timeouts, and backoff strategies for HTTP, gRPC, and TCP traffic, helping services recover from transient failures. required: - type - name - spec properties: type: description: the type of the resource type: string enum: - MeshRetry mesh: description: Mesh is the name of the Kuma mesh this resource belongs to. It may be omitted for cluster-scoped resources. type: string default: default kri: description: A unique identifier for this resource instance used by internal tooling and integrations. Typically derived from resource attributes and may be used for cross-references or indexing type: string readOnly: true example: kri_mr_default_zone-east_kuma-demo_mypolicy1_ name: description: Name of the Kuma resource type: string labels: additionalProperties: type: string description: The labels to help identity resources type: object spec: description: Spec is the specification of the Kuma MeshRetry resource. properties: targetRef: description: 'TargetRef is a reference to the resource the policy takes an effect on. The resource could be either a real store object or virtual resource defined inplace.' properties: kind: description: Kind of the referenced resource enum: - Mesh - MeshSubset - MeshGateway - MeshService - MeshExternalService - MeshMultiZoneService - MeshServiceSubset - MeshHTTPRoute - Dataplane type: string labels: additionalProperties: type: string description: 'Labels are used to select group of MeshServices that match labels. Either Labels or Name and Namespace can be used.' type: object mesh: description: Mesh is reserved for future use to identify cross mesh resources. type: string name: description: 'Name of the referenced resource. Can only be used with kinds: `MeshService`, `MeshServiceSubset` and `MeshGatewayRoute`' type: string namespace: description: 'Namespace specifies the namespace of target resource. If empty only resources in policy namespace will be targeted.' type: string proxyTypes: description: 'ProxyTypes specifies the data plane types that are subject to the policy. When not specified, all data plane types are targeted by the policy.' items: enum: - Sidecar - Gateway type: string type: array sectionName: description: 'SectionName is used to target specific section of resource. For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.' type: string tags: additionalProperties: type: string description: 'Tags used to select a subset of proxies by tags. Can only be used with kinds `MeshSubset` and `MeshServiceSubset`' type: object required: - kind type: object to: description: To list makes a match between the consumed services and corresponding configurations items: properties: default: description: 'Default is a configuration specific to the group of destinations referenced in ''targetRef''' properties: grpc: description: GRPC defines a configuration of retries for GRPC traffic properties: backOff: description: 'BackOff is a configuration of durations which will be used in an exponential backoff strategy between retries.' properties: baseInterval: description: 'BaseInterval is an amount of time which should be taken between retries. Must be greater than zero. Values less than 1 ms are rounded up to 1 ms. If not specified then the default value is "25ms".' type: string maxInterval: description: 'MaxInterval is a maximal amount of time which will be taken between retries. Default is 10 times the "BaseInterval".' type: string type: object numRetries: description: 'NumRetries is the number of attempts that will be made on failed (and retriable) requests. If not set, the default value is 1.' format: int32 type: integer perTryTimeout: description: 'PerTryTimeout is the maximum amount of time each retry attempt can take before it times out. If not set, the global request timeout for the route will be used. Setting this value to 0 will disable the per-try timeout.' type: string rateLimitedBackOff: description: 'RateLimitedBackOff is a configuration of backoff which will be used when the upstream returns one of the headers configured.' properties: maxInterval: description: 'MaxInterval is a maximal amount of time which will be taken between retries. If not specified then the default value is "300s".' type: string resetHeaders: description: 'ResetHeaders specifies the list of headers (like Retry-After or X-RateLimit-Reset) to match against the response. Headers are tried in order, and matched case-insensitive. The first header to be parsed successfully is used. If no headers match the default exponential BackOff is used instead.' items: properties: format: description: The format of the reset header. enum: - Seconds - UnixTimestamp type: string name: description: The Name of the reset header. maxLength: 256 minLength: 1 pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$ type: string required: - format - name type: object type: array type: object retryOn: description: RetryOn is a list of conditions which will cause a retry. example: - Canceled - DeadlineExceeded - Internal - ResourceExhausted - Unavailable items: enum: - Canceled - DeadlineExceeded - Internal - ResourceExhausted - Unavailable type: string type: array type: object http: description: HTTP defines a configuration of retries for HTTP traffic properties: backOff: description: 'BackOff is a configuration of durations which will be used in exponential backoff strategy between retries.' properties: baseInterval: description: 'BaseInterval is an amount of time which should be taken between retries. Must be greater than zero. Values less than 1 ms are rounded up to 1 ms. If not specified then the default value is "25ms".' type: string maxInterval: description: 'MaxInterval is a maximal amount of time which will be taken between retries. Default is 10 times the "BaseInterval".' type: string type: object hostSelection: description: 'HostSelection is a list of predicates that dictate how hosts should be selected when requests are retried.' items: properties: predicate: description: Type is requested predicate mode. enum: - OmitPreviousHosts - OmitHostsWithTags - OmitPreviousPriorities type: string tags: additionalProperties: type: string description: 'Tags is a map of metadata to match against for selecting the omitted hosts. Required if Type is OmitHostsWithTags' type: object updateFrequency: default: 2 description: 'UpdateFrequency is how often the priority load should be updated based on previously attempted priorities. Used for OmitPreviousPriorities.' format: int32 type: integer required: - predicate type: object type: array hostSelectionMaxAttempts: description: 'HostSelectionMaxAttempts is the maximum number of times host selection will be reattempted before giving up, at which point the host that was last selected will be routed to. If unspecified, this will default to retrying once.' format: int64 type: integer numRetries: description: 'NumRetries is the number of attempts that will be made on failed (and retriable) requests. If not set, the default value is 1.' format: int32 type: integer perTryTimeout: description: 'PerTryTimeout is the amount of time after which retry attempt should time out. If left unspecified, the global route timeout for the request will be used. Consequently, when using a 5xx based retry policy, a request that times out will not be retried as the total timeout budget would have been exhausted. Setting this timeout to 0 will disable it.' type: string rateLimitedBackOff: description: 'RateLimitedBackOff is a configuration of backoff which will be used when the upstream returns one of the headers configured.' properties: maxInterval: description: 'MaxInterval is a maximal amount of time which will be taken between retries. If not specified then the default value is "300s".' type: string resetHeaders: description: 'ResetHeaders specifies the list of headers (like Retry-After or X-RateLimit-Reset) to match against the response. Headers are tried in order, and matched case-insensitive. The first header to be parsed successfully is used. If no headers match the default exponential BackOff is used instead.' items: properties: format: description: The format of the reset header. enum: - Seconds - UnixTimestamp type: string name: description: The Name of the reset header. maxLength: 256 minLength: 1 pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$ type: string required: - format - name type: object type: array type: object retriableRequestHeaders: description: 'RetriableRequestHeaders is an HTTP headers which must be present in the request for retries to be attempted.' items: description: 'HeaderMatch describes how to select an HTTP route by matching HTTP request headers.' properties: name: description: 'Name is the name of the HTTP Header to be matched. Name MUST be lower case as they will be handled with case insensitivity (See https://tools.ietf.org/html/rfc7230#section-3.2).' maxLength: 256 minLength: 1 pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$ type: string type: default: Exact description: Type specifies how to match against the value of the header. enum: - Exact - Present - RegularExpression - Absent - Prefix type: string value: description: Value is the value of HTTP Header to be matched. type: string required: - name type: object type: array retriableResponseHeaders: description: 'RetriableResponseHeaders is an HTTP response headers that trigger a retry if present in the response. A retry will be triggered if any of the header matches the upstream response headers.' items: description: 'HeaderMatch describes how to select an HTTP route by matching HTTP request headers.' properties: name: description: 'Name is the name of the HTTP Header to be matched. Name MUST be lower case as they will be handled with case insensitivity (See https://tools.ietf.org/html/rfc7230#section-3.2).' maxLength: 256 minLength: 1 pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$ type: string type: default: Exact description: Type specifies how to match against the value of the header. enum: - Exact - Present - RegularExpression - Absent - Prefix type: string value: description: Value is the value of HTTP Header to be matched. type: string required: - name type: object type: array retryOn: description: 'RetryOn is a list of conditions which will cause a retry. Available values are: [5XX, GatewayError, Reset, Retriable4xx, ConnectFailure, EnvoyRatelimited, RefusedStream, Http3PostConnectFailure, HttpMethodConnect, HttpMethodDelete, HttpMethodGet, HttpMethodHead, HttpMethodOptions, HttpMethodPatch, HttpMethodPost, HttpMethodPut, HttpMethodTrace]. Also, any HTTP status code (500, 503, etc.).' example: - 5XX - GatewayError - Reset - Retriable4xx - ConnectFailure - EnvoyRatelimited - RefusedStream - Http3PostConnectFailure - HttpMethodConnect - HttpMethodDelete - HttpMethodGet - HttpMethodHead - HttpMethodOptions - HttpMethodPatch - HttpMethodPost - HttpMethodPut - HttpMethodTrace - '500' - '503' items: type: string type: array type: object tcp: description: TCP defines a configuration of retries for TCP traffic properties: maxConnectAttempt: description: 'MaxConnectAttempt is a maximal amount of TCP connection attempts which will be made before giving up' format: int32 type: integer type: object type: object targetRef: description: 'TargetRef is a reference to the resource that represents a group of destinations.' properties: kind: description: Kind of the referenced resource enum: - Mesh - MeshSubset - MeshGateway - MeshService - MeshExternalService - MeshMultiZoneService - MeshServiceSubset - MeshHTTPRoute - Dataplane type: string labels: additionalProperties: type: string description: 'Labels are used to select group of MeshServices that match labels. Either Labels or Name and Namespace can be used.' type: object mesh: description: Mesh is reserved for future use to identify cross mesh resources. type: string name: description: 'Name of the referenced resource. Can only be used with kinds: `MeshService`, `MeshServiceSubset` and `MeshGatewayRoute`' type: string namespace: description: 'Namespace specifies the namespace of target resource. If empty only resources in policy namespace will be targeted.' type: string proxyTypes: description: 'ProxyTypes specifies the data plane types that are subject to the policy. When not specified, all data plane types are targeted by the policy.' items: enum: - Sidecar - Gateway type: string type: array sectionName: description: 'SectionName is used to target specific section of resource. For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.' type: string tags: additionalProperties: type: string description: 'Tags used to select a subset of proxies by tags. Can only be used with kinds `MeshSubset` and `MeshServiceSubset`' type: object required: - kind type: object required: - targetRef type: object type: array type: object creationTime: readOnly: true type: string description: Time at which the resource was created format: date-time example: '0001-01-01T00:00:00Z' modificationTime: readOnly: true type: string description: Time at which the resource was updated format: date-time example: '0001-01-01T00:00:00Z' NotFoundError: allOf: - $ref: '#/components/schemas/Error' - type: object properties: status: type: integer enum: - 404 example: 404 description: 'The HTTP status code for NotFoundError MUST be 404. ' title: type: string example: Not Found type: type: string example: https://httpstatuses.com/404 detail: type: string example: The requested resource was not found InvalidParameters: type: object title: Invalid Parameters required: - field - reason - source properties: field: type: string description: The name of the field that caused the error. reason: type: string description: 'A short, human-readable description of the problem. _Should_ be provided as "Sentence case" for direct use in a UI. ' rule: type: string description: 'May be provided as a hint to the user to help understand the type of failure. Additional guidance may be provided in additional fields, i.e. `choices`. ' choices: type: array description: 'Optional field to provide a list of valid choices for the field that caused the error. ' items: type: string source: type: string description: 'The location of the field that caused the error. ' enum: - body - query - header - path Error: type: object title: Error description: 'Standard error. Follows the [AIP #193 - Errors](https://kong-aip.netlify.app/aip/193/) specification. ' x-examples: Example 1: status: 404 title: Not Found type: https://kongapi.info/konnect/not-found instance: portal:trace:2287285207635123011 detail: The requested document was not found required: - status - title - instance - type - detail properties: status: type: integer description: The HTTP status code. example: 404 title: type: string description: 'A short, human-readable summary of the problem. It **should not** change between occurrences of a problem, except for localization. Should be provided as "Sentence case" for potential direct use in a UI ' example: Not Found type: type: string description: 'A unique identifier for this error. When dereferenced it must provide human-readable documentation for the problem. ' example: Not Found instance: type: string example: portal:trace:2287285207635123011 description: 'Used to return the correlation ID back to the user, in the format `:trace:`. ' detail: type: string example: The requested team was not found description: 'A human readable explanation specific to this occurrence of the problem. This field may contain request/entity data to help the user understand what went wrong. Enclose variable values in square brackets. _Should_ be provided as "Sentence case" for direct use in a UI ' invalid_parameters: type: array description: 'All 400 errors **MUST** return an `invalid_parameters` key in the response. Used to indicate which fields have invalid values when validated. ' items: $ref: '#/components/schemas/InvalidParameters' securitySchemes: BasicAuth: type: http scheme: basic BearerAuth: type: http scheme: bearer