The MeshCircuitBreaker API from Kuma — 2 operation(s) for meshcircuitbreaker.
openapi: 3.1.0
info:
title: Kuma Dataplane MeshCircuitBreaker API
description: Kuma API
version: v1alpha1
x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: MeshCircuitBreaker
paths:
/meshes/{mesh}/meshcircuitbreakers/{name}:
get:
operationId: getMeshCircuitBreaker
summary: Returns MeshCircuitBreaker entity
tags:
- MeshCircuitBreaker
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 MeshCircuitBreaker
responses:
'200':
$ref: '#/components/responses/MeshCircuitBreakerItem'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: putMeshCircuitBreaker
summary: Creates or Updates MeshCircuitBreaker entity
tags:
- MeshCircuitBreaker
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 MeshCircuitBreaker
requestBody:
description: Put request
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MeshCircuitBreakerItem'
responses:
'200':
$ref: '#/components/responses/MeshCircuitBreakerCreateOrUpdateSuccessResponse'
'201':
$ref: '#/components/responses/MeshCircuitBreakerCreateOrUpdateSuccessResponse'
delete:
operationId: deleteMeshCircuitBreaker
summary: Deletes MeshCircuitBreaker entity
tags:
- MeshCircuitBreaker
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 MeshCircuitBreaker
responses:
'200':
$ref: '#/components/responses/MeshCircuitBreakerDeleteSuccessResponse'
'404':
$ref: '#/components/responses/NotFound'
/meshes/{mesh}/meshcircuitbreakers:
get:
operationId: getMeshCircuitBreakerList
summary: Returns a list of MeshCircuitBreaker in the mesh.
tags:
- MeshCircuitBreaker
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/MeshCircuitBreakerList'
components:
responses:
NotFound:
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundError'
MeshCircuitBreakerItem:
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/MeshCircuitBreakerItem'
MeshCircuitBreakerCreateOrUpdateSuccessResponse:
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
MeshCircuitBreakerDeleteSuccessResponse:
description: Successful response
content:
application/json:
schema:
type: object
MeshCircuitBreakerList:
description: List
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/MeshCircuitBreakerItem'
total:
type: number
description: The total number of entities
next:
type: string
description: URL to the next page
schemas:
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
MeshCircuitBreakerItem:
type: object
description: MeshCircuitBreaker protects services from cascading failures by limiting connections and detecting unhealthy instances. It provides connection limits to prevent overload and outlier detection to temporarily remove failing endpoints from the load balancing pool.
required:
- type
- name
- spec
properties:
type:
description: the type of the resource
type: string
enum:
- MeshCircuitBreaker
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_mcb_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 MeshCircuitBreaker resource.
properties:
from:
description: From list makes a match between clients and corresponding configurations
items:
properties:
default:
description: 'Default is a configuration specific to the group of destinations
referenced in ''targetRef'''
properties:
connectionLimits:
description: 'ConnectionLimits contains configuration of each circuit breaking limit,
which when exceeded makes the circuit breaker to become open (no traffic
is allowed like no current is allowed in the circuits when physical
circuit breaker ir open)'
properties:
maxConnectionPools:
description: 'The maximum number of connection pools per cluster that are concurrently
supported at once. Set this for clusters which create a large number of
connection pools.'
format: int32
type: integer
maxConnections:
description: 'The maximum number of connections allowed to be made to the upstream
cluster.'
format: int32
type: integer
maxPendingRequests:
description: 'The maximum number of pending requests that are allowed to the upstream
cluster. This limit is applied as a connection limit for non-HTTP
traffic.'
format: int32
type: integer
maxRequests:
description: 'The maximum number of parallel requests that are allowed to be made
to the upstream cluster. This limit does not apply to non-HTTP traffic.'
format: int32
type: integer
maxRetries:
description: 'The maximum number of parallel retries that will be allowed to
the upstream cluster.'
format: int32
type: integer
type: object
outlierDetection:
description: 'OutlierDetection contains the configuration of the process of dynamically
determining whether some number of hosts in an upstream cluster are
performing unlike the others and removing them from the healthy load
balancing set. Performance might be along different axes such as
consecutive failures, temporal success rate, temporal latency, etc.
Outlier detection is a form of passive health checking.'
properties:
baseEjectionTime:
description: 'The base time that a host is ejected for. The real time is equal to
the base time multiplied by the number of times the host has been
ejected.'
type: string
detectors:
description: Contains configuration for supported outlier detectors
properties:
failurePercentage:
description: 'Failure Percentage based outlier detection functions similarly to success
rate detection, in that it relies on success rate data from each host in
a cluster. However, rather than compare those values to the mean success
rate of the cluster as a whole, they are compared to a flat
user-configured threshold. This threshold is configured via the
outlierDetection.failurePercentageThreshold field.
The other configuration fields for failure percentage based detection are
similar to the fields for success rate detection. As with success rate
detection, detection will not be performed for a host if its request
volume over the aggregation interval is less than the
outlierDetection.detectors.failurePercentage.requestVolume value.
Detection also will not be performed for a cluster if the number of hosts
with the minimum required request volume in an interval is less than the
outlierDetection.detectors.failurePercentage.minimumHosts value.'
properties:
minimumHosts:
description: 'The minimum number of hosts in a cluster in order to perform failure
percentage-based ejection. If the total number of hosts in the cluster is
less than this value, failure percentage-based ejection will not be
performed.'
format: int32
type: integer
requestVolume:
description: 'The minimum number of total requests that must be collected in one
interval (as defined by the interval duration above) to perform failure
percentage-based ejection for this host. If the volume is lower than this
setting, failure percentage-based ejection will not be performed for this
host.'
format: int32
type: integer
threshold:
description: 'The failure percentage to use when determining failure percentage-based
outlier detection. If the failure percentage of a given host is greater
than or equal to this value, it will be ejected.'
format: int32
type: integer
type: object
gatewayFailures:
description: 'In the default mode (outlierDetection.splitExternalLocalOriginErrors is
false) this detection type takes into account a subset of 5xx errors,
called "gateway errors" (502, 503 or 504 status code) and local origin
failures, such as timeout, TCP reset etc.
In split mode (outlierDetection.splitExternalLocalOriginErrors is true)
this detection type takes into account a subset of 5xx errors, called
"gateway errors" (502, 503 or 504 status code) and is supported only by
the http router.'
properties:
consecutive:
description: 'The number of consecutive gateway failures (502, 503, 504 status codes)
before a consecutive gateway failure ejection occurs.'
format: int32
type: integer
type: object
localOriginFailures:
description: 'This detection type is enabled only when
outlierDetection.splitExternalLocalOriginErrors is true and takes into
account only locally originated errors (timeout, reset, etc).
If Envoy repeatedly cannot connect to an upstream host or communication
with the upstream host is repeatedly interrupted, it will be ejected.
Various locally originated problems are detected: timeout, TCP reset,
ICMP errors, etc. This detection type is supported by http router and
tcp proxy.'
properties:
consecutive:
description: 'The number of consecutive locally originated failures before ejection
occurs. Parameter takes effect only when splitExternalAndLocalErrors
is set to true.'
format: int32
type: integer
type: object
successRate:
description: 'Success Rate based outlier detection aggregates success rate data from
every host in a cluster. Then at given intervals ejects hosts based on
statistical outlier detection. Success Rate outlier detection will not be
calculated for a host if its request volume over the aggregation interval
is less than the outlierDetection.detectors.successRate.requestVolume
value.
Moreover, detection will not be performed for a cluster if the number of
hosts with the minimum required request volume in an interval is less
than the outlierDetection.detectors.successRate.minimumHosts value.
In the default configuration mode
(outlierDetection.splitExternalLocalOriginErrors is false) this detection
type takes into account all types of errors: locally and externally
originated.
In split mode (outlierDetection.splitExternalLocalOriginErrors is true),
locally originated errors and externally originated (transaction) errors
are counted and treated separately.'
properties:
minimumHosts:
description: 'The number of hosts in a cluster that must have enough request volume to
detect success rate outliers. If the number of hosts is less than this
setting, outlier detection via success rate statistics is not performed
for any host in the cluster.'
format: int32
type: integer
requestVolume:
description: 'The minimum number of total requests that must be collected in one
interval (as defined by the interval duration configured in
outlierDetection section) to include this host in success rate based
outlier detection. If the volume is lower than this setting, outlier
detection via success rate statistics is not performed for that host.'
format: int32
type: integer
standardDeviationFactor:
anyOf:
- type: integer
- type: string
description: 'This factor is used to determine the ejection threshold for success rate
outlier ejection. The ejection threshold is the difference between
the mean success rate, and the product of this factor and the standard
deviation of the mean success rate: mean - (standard_deviation *
success_rate_standard_deviation_factor).
Either int or decimal represented as string.'
x-kubernetes-int-or-string: true
type: object
totalFailures:
description: 'In the default mode (outlierDetection.splitExternalAndLocalErrors is
false) this detection type takes into account all generated errors:
locally originated and externally originated (transaction) errors.
In split mode (outlierDetection.splitExternalLocalOriginErrors is true)
this detection type takes into account only externally originated
(transaction) errors, ignoring locally originated errors.
If an upstream host is an HTTP-server, only 5xx types of error are taken
into account (see Consecutive Gateway Failure for exceptions).
Properly formatted responses, even when they carry an operational error
(like index not found, access denied) are not taken into account.'
properties:
consecutive:
description: 'The number of consecutive server-side error responses (for HTTP traffic,
5xx responses; for TCP traffic, connection failures; for Redis, failure
to respond PONG; etc.) before a consecutive total failure ejection
occurs.'
format: int32
type: integer
type: object
type: object
disabled:
description: When set to true, outlierDetection configuration won't take any effect
type: boolean
healthyPanicThreshold:
anyOf:
- type: integer
- type: string
description: 'Allows to configure panic threshold for Envoy cluster. If not specified,
the default is 50%. To disable panic mode, set to 0%.
Either int or decimal represented as string.'
x-kubernetes-int-or-string: true
interval:
description: 'The time interval between ejection analysis sweeps. This can result in
both new ejections and hosts being returned to service.'
type: string
maxEjectionPercent:
description: 'The maximum % of an upstream cluster that can be ejected due to outlier
detection. Defaults to 10% but will eject at least one host regardless of
the value.'
format: int32
type: integer
splitExternalAndLocalErrors:
description: 'Determines whether to distinguish local origin failures from external
errors. If set to true the following configuration parameters are taken
into account: detectors.localOriginFailures.consecutive'
type: boolean
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
rules:
description: 'Rules defines inbound circuit breaker configurations. Currently limited to
selecting all inbound traffic, as L7 matching is not yet implemented.'
items:
properties:
default:
description: Default contains configuration of the inbound circuit breaker
properties:
connectionLimits:
description: 'ConnectionLimits contains configuration of each circuit breaking limit,
which when exceeded makes the circuit breaker to become open (no traffic
is allowed like no current is allowed in the circuits when physical
circuit breaker ir open)'
properties:
maxConnectionPools:
description: 'The maximum number of connection pools per cluster that are concurrently
supported at once. Set this for clusters which create a large number of
connection pools.'
format: int32
type: integer
maxConnections:
description: 'The maximum number of connections allowed to be made to the upstream
cluster.'
format: int32
type: integer
maxPendingRequests:
description: 'The maximum number of pending requests that are allowed to the upstream
cluster. This limit is applied as a connection limit for non-HTTP
traffic.'
format: int32
type: integer
maxRequests:
description: 'The maximum number of parallel requests that are allowed to be made
to the upstream cluster. This limit does not apply to non-HTTP traffic.'
format: int32
type: integer
maxRetries:
description: 'The maximum number of parallel retries that will be allowed to
the upstream cluster.'
format: int32
type: integer
type: object
outlierDetection:
description: 'OutlierDetection contains the configuration of the process of dynamically
determining whether some number of hosts in an upstream cluster are
performing unlike the others and removing them from the healthy load
balancing set. Performance might be along different axes such as
consecutive failures, temporal success rate, temporal latency, etc.
Outlier detection is a form of passive health checking.'
properties:
baseEjectionTime:
description: 'The base time that a host is ejected for. The real time is equal to
the base time multiplied by the number of times the host has been
ejected.'
type: string
detectors:
description: Contains configuration for supported outlier detectors
properties:
failurePercentage:
description: 'Failure Percentage based outlier detection functions similarly to success
rate detection, in that it relies on success rate data from each host in
a cluster. However, rather than compare those values to the mean success
rate of the cluster as a whole, they are compared to a flat
user-configured threshold. This threshold is configured via the
outlierDetection.failurePercentageThreshold field.
The other configuration fields for failure percentage based detection are
similar to the fields for success rate detection. As with success rate
detection, detection will not be performed for a host if its request
volume over the aggregation interval is less than the
outlierDetection.detectors.failurePercentage.requestVolume value.
Detection also will not be performed for a cluster if the number of hosts
with the minimum required request volume in an interval is less than the
outlierDetection.detectors.failurePercentage.minimumHosts value.'
properties:
minimumHosts:
description: 'The minimum number of hosts in a cluster in order to perform failure
percentage-based ejection. If the total number of hosts in the cluster is
less than t
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kuma/refs/heads/main/openapi/kuma-meshcircuitbreaker-api-openapi.yml