このページは、まだ日本語ではご利用いただけません。翻訳中です。
Mesh Health Check
This policy uses new policy matching algorithm. Do not combine with HealthCheck.
This policy enables Kong Mesh to keep track of the health of every data plane proxy, with the goal of minimizing the number of failed requests in case a data plane proxy is temporarily unhealthy.
By creating a MeshHealthCheck
resource you instruct a data plane proxy to keep track of the health status for any other data plane proxy.
When health-checks are properly configured,
a data plane proxy will never send a request to another data plane proxy that is considered unhealthy.
When an unhealthy proxy returns to a healthy state,
Kong Mesh will resume sending requests to it again.
This policy provides active checks. If you want to configure passive checks, please utilize the MeshCircuitBreaker policy. Data plane proxies with active checks will explicitly send requests to other data plane proxies to determine if target proxies are healthy or not. This mode generates extra traffic to other proxies and services as described in the policy configuration.
TargetRef support matrix
targetRef |
Allowed kinds |
---|---|
targetRef.kind |
Mesh , MeshSubset
|
to[].targetRef.kind |
Mesh , MeshService
|
To learn more about the information in this table, see the matching docs.
Configuration
The MeshHealthCheck
policy supports both L4/TCP and L7/HTTP/gRPC checks.
Protocol selection
The health check protocol is selected by picking the most specific protocol
and falls back to more general protocol when specified protocol has disabled=true
in policy definition.
See protocol fallback example.
Examples
Health check from web to backend service
apiVersion: kuma.io/v1alpha1
kind: MeshHealthCheck
metadata:
name: web-to-backend-check
namespace: kuma-demo
labels:
kuma.io/mesh: default
spec:
targetRef:
kind: MeshSubset
tags:
kuma.io/service: web
to:
- targetRef:
kind: MeshService
name: backend
namespace: kuma-demo
sectionName: http
default:
interval: 10s
timeout: 2s
unhealthyThreshold: 3
healthyThreshold: 1
http:
path: "/health"
expectedStatuses:
- 200
- 201
Protocol fallback
apiVersion: kuma.io/v1alpha1
kind: MeshHealthCheck
metadata:
name: web-to-backend-check
namespace: kuma-demo
labels:
kuma.io/mesh: default
spec:
targetRef:
kind: MeshSubset
tags:
kuma.io/service: web
to:
- targetRef:
kind: MeshService
name: backend
namespace: kuma-demo
sectionName: http
default:
interval: 10s
timeout: 2s
unhealthyThreshold: 3
healthyThreshold: 1
tcp: {}
http:
disabled: true
gRPC health check from cart to payment service
apiVersion: kuma.io/v1alpha1
kind: MeshHealthCheck
metadata:
name: web-to-backend-check
namespace: kuma-demo
labels:
kuma.io/mesh: default
spec:
targetRef:
kind: MeshSubset
tags:
kuma.io/service: web
to:
- targetRef:
kind: MeshService
name: backend
namespace: kuma-demo
sectionName: http
default:
interval: 15s
timeout: 5s
unhealthyThreshold: 3
healthyThreshold: 2
grpc:
serviceName: grpc.health.v1.CustomHealth
Common configuration
-
interval
- (optional) interval between consecutive health checks, if not specified then equal to1m
-
timeout
- (optional) maximum time to wait for a health check response, if not specified then equal to15s
-
unhealthyThreshold
- (optional) number of consecutive unhealthy checks before considering a host unhealthy, if not specified then equal to 5 -
healthyThreshold
- (optional) number of consecutive healthy checks before considering a host healthy, if not specified then equal to 1 -
initialJitter
- (optional) if specified, Envoy will start health checking after a random time in milliseconds between 0 andinitialJitter
. This only applies to the first health check -
intervalJitter
- (optional) if specified, during every interval Envoy will addintervalJitter
to the wait time -
intervalJitterPercent
- (optional) if specified, during every interval Envoy will addintervalJitter
*intervalJitterPercent
/ 100 to the wait time. IfintervalJitter
andintervalJitterPercent
are both set, both of them will be used to increase the wait time. -
healthyPanicThreshold
- allows to configure panic threshold for Envoy cluster. If not specified, the default is 50%. To disable panic mode, set to 0%. -
failTrafficOnPanic
- (optional) if set to true, Envoy will not consider any hosts when the cluster is in ‘panic mode’. Instead, the cluster will fail all requests as if all hosts are unhealthy. This can help avoid potentially overwhelming a failing service. -
noTrafficInterval
- (optional) a special health check interval that is used when a cluster has never had traffic routed to it. This lower interval allows cluster information to be kept up to date, without sending a potentially large amount of active health checking traffic for no reason. Once a cluster has been used for traffic routing, Envoy will shift back to using the standard health check interval that is defined. Note that this interval takes precedence over any other. The default value for “no traffic interval” is 60 seconds. -
eventLogPath
- (optional) specifies the path to the file where Envoy can log health check events. If empty, no event log will be written. -
alwaysLogHealthCheckFailures
- (optional) if set to true, health check failure events will always be logged. If set to false, only the initial health check failure event will be logged. The default value is false. -
reuseConnection
- (optional) reuse health check connection between health checks. Default is true.
Protocol specific configuration
HTTP
HTTP health checks are executed using HTTP2
-
disabled
- (optional) - if true HTTP health check is disabled -
path
- (optional) HTTP path to be used during the health checks, if not specified then equal to “/” -
expectedStatuses
(optional) - list of HTTP response statuses which are considered healthy- only statuses in the range
[100, 600)
are allowed - by default, when this property is not provided only responses with
status code
200
are being considered healthy
- only statuses in the range
-
requestHeadersToAdd
(optional) - HeaderModifier list of HTTP headers which should be added to each health check request
HeaderModifier
-
set
- (optional) - list of headers to set. Overrides value if the header exists.-
name
- header’s name -
value
- header’s value
-
-
add
- (optional) - list of headers to add. Appends value if the header exists.-
name
- header’s name -
value
- header’s value
-
TCP
-
disabled
- (optional) - if true TCP health check is disabled -
send
- (optional) - Base64 encoded content of the message which should be sent during the health checks -
receive
- (optional) - list of Base64 encoded blocks of strings which should be found in the returning message which should be considered as healthy- when checking the response, “fuzzy” matching is performed such that each block must be found, and in the order specified, but not necessarily contiguous;
- if
receive
section won’t be provided or will be empty, checks will be performed as “connect only” and will be marked as successful when TCP connection will be successfully established.
gRPC
-
disabled
- (optional) - if true gRPC health check is disabled -
serviceName
- (optional) - service name parameter which will be sent to gRPC service -
authority
- (optional) - value of the :authority header in the gRPC health check request, by default name of the cluster this health check is associated with
All policy options
Spec is the specification of the Kuma MeshHealthCheck resource.
Type: object
Properties
- targetRef
- TargetRef is a reference to the resource the policy takes an effect on.The resource could be either a real store object or virtual resourcedefined inplace.
- Type:
object
- Properties
- kind
- Kind of the referenced resource
- Type:
string
- The value is restricted to the following:
- "Mesh"
- "MeshSubset"
- "MeshGateway"
- "MeshService"
- "MeshExternalService"
- "MeshMultiZoneService"
- "MeshServiceSubset"
- "MeshHTTPRoute"
- labels
- Labels are used to select group of MeshServices that match labels. Either Labels orName and Namespace can be used.
- Type:
object
- This schema accepts additional properties.
- Properties
- mesh
- Mesh is reserved for future use to identify cross mesh resources.
- Type:
string
- name
- Name of the referenced resource. Can only be used with kinds:
MeshService
,MeshServiceSubset
andMeshGatewayRoute
- Type:
string
- Name of the referenced resource. Can only be used with kinds:
- namespace
- Namespace specifies the namespace of target resource. If empty only resources in policy namespacewill be targeted.
- Type:
string
- proxyTypes
- ProxyTypes specifies the data plane types that are subject to the policy. When not specified,all data plane types are targeted by the policy.
- Type:
array
- Item Count: ≥ 1
- Items
- Type:
string
- The value is restricted to the following:
- "Sidecar"
- "Gateway"
- sectionName
- 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
- Tags used to select a subset of proxies by tags. Can only be used with kinds
MeshSubset
andMeshServiceSubset
- Type:
object
- This schema accepts additional properties.
- Properties
- Tags used to select a subset of proxies by tags. Can only be used with kinds
- kind
- to
- To list makes a match between the consumed services and corresponding configurations
- Type:
array
- Items
- Type:
object
- Properties
- default
- Default is a configuration specific to the group of destinations referenced in'targetRef'
- Type:
object
- Properties
- alwaysLogHealthCheckFailures
- If set to true, health check failure events will always be logged. If setto false, only the initial health check failure event will be logged. Thedefault value is false.
- Type:
boolean
- eventLogPath
- Specifies the path to the file where Envoy can log health check events.If empty, no event log will be written.
- Type:
string
- failTrafficOnPanic
- If set to true, Envoy will not consider any hosts when the cluster is in'panic mode'. Instead, the cluster will fail all requests as if all hostsare unhealthy. This can help avoid potentially overwhelming a failingservice.
- Type:
boolean
- grpc
- GrpcHealthCheck defines gRPC configuration which will instruct the servicethe health check will be made for is a gRPC service.
- Type:
object
- Properties
- authority
- The value of the :authority header in the gRPC health check request,by default name of the cluster this health check is associated with
- Type:
string
- disabled
- If true the GrpcHealthCheck is disabled
- Type:
boolean
- serviceName
- Service name parameter which will be sent to gRPC service
- Type:
string
- authority
- healthyPanicThreshold
- 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.
- healthyThreshold
- Number of consecutive healthy checks before considering a host healthy.
- Type:
integer
- Default:
1
- http
- HttpHealthCheck defines HTTP configuration which will instruct the servicethe health check will be made for is an HTTP service.
- Type:
object
- Properties
- disabled
- If true the HttpHealthCheck is disabled
- Type:
boolean
- expectedStatuses
- List of HTTP response statuses which are considered healthy
- Type:
array
- Items
- Type:
integer
- path
- The HTTP path which will be requested during the health check(ie. /health)
- Type:
string
- Default: "/"
- requestHeadersToAdd
- The list of HTTP headers which should be added to each health checkrequest
- Type:
object
- Properties
- add
- Type:
array
- Item Count: ≤ 16
- Items
- Type:
object
- Properties
- name
required
- Type:
string
- The value must match this pattern:
^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
- Length: between 1 and 256
- Type:
- value
required
- Type:
string
- Type:
- name
- Type:
- set
- Type:
array
- Item Count: ≤ 16
- Items
- Type:
object
- Properties
- name
required
- Type:
string
- The value must match this pattern:
^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
- Length: between 1 and 256
- Type:
- value
required
- Type:
string
- Type:
- name
- Type:
- add
- disabled
- initialJitter
- If specified, Envoy will start health checking after a random time inms between 0 and initialJitter. This only applies to the first healthcheck.
- Type:
string
- interval
- Interval between consecutive health checks.
- Type:
string
- Default: "1m"
- intervalJitter
- If specified, during every interval Envoy will add IntervalJitter to thewait time.
- Type:
string
- intervalJitterPercent
- If specified, during every interval Envoy will add IntervalJitter *IntervalJitterPercent / 100 to the wait time. If IntervalJitter andIntervalJitterPercent are both set, both of them will be used toincrease the wait time.
- Type:
integer
- noTrafficInterval
- The "no traffic interval" is a special health check interval that is usedwhen a cluster has never had traffic routed to it. This lower intervalallows cluster information to be kept up to date, without sending apotentially large amount of active health checking traffic for no reason.Once a cluster has been used for traffic routing, Envoy will shift backto using the standard health check interval that is defined. Note thatthis interval takes precedence over any other. The default value for "notraffic interval" is 60 seconds.
- Type:
string
- reuseConnection
- Reuse health check connection between health checks. Default is true.
- Type:
boolean
- tcp
- TcpHealthCheck defines configuration for specifying bytes to send andexpected response during the health check
- Type:
object
- Properties
- disabled
- If true the TcpHealthCheck is disabled
- Type:
boolean
- receive
- List of Base64 encoded blocks of strings expected as a response. When checking the response,"fuzzy" matching is performed such that each block must be found, andin the order specified, but not necessarily contiguous.If not provided or empty, checks will be performed as "connect only" and be marked as successful when TCP connection is successfully established.
- Type:
array
- Items
- Type:
string
- send
- Base64 encoded content of the message which will be sent during the health check to the target
- Type:
string
- disabled
- timeout
- Maximum time to wait for a health check response.
- Type:
string
- Default: "15s"
- unhealthyThreshold
- Number of consecutive unhealthy checks before considering a hostunhealthy.
- Type:
integer
- Default:
5
- alwaysLogHealthCheckFailures
- targetRef
required
- TargetRef is a reference to the resource that represents a group ofdestinations.
- Type:
object
- Properties
- kind
- Kind of the referenced resource
- Type:
string
- The value is restricted to the following:
- "Mesh"
- "MeshSubset"
- "MeshGateway"
- "MeshService"
- "MeshExternalService"
- "MeshMultiZoneService"
- "MeshServiceSubset"
- "MeshHTTPRoute"
- labels
- Labels are used to select group of MeshServices that match labels. Either Labels orName and Namespace can be used.
- Type:
object
- This schema accepts additional properties.
- Properties
- mesh
- Mesh is reserved for future use to identify cross mesh resources.
- Type:
string
- name
- Name of the referenced resource. Can only be used with kinds:
MeshService
,MeshServiceSubset
andMeshGatewayRoute
- Type:
string
- Name of the referenced resource. Can only be used with kinds:
- namespace
- Namespace specifies the namespace of target resource. If empty only resources in policy namespacewill be targeted.
- Type:
string
- proxyTypes
- ProxyTypes specifies the data plane types that are subject to the policy. When not specified,all data plane types are targeted by the policy.
- Type:
array
- Item Count: ≥ 1
- Items
- Type:
string
- The value is restricted to the following:
- "Sidecar"
- "Gateway"
- sectionName
- 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
- Tags used to select a subset of proxies by tags. Can only be used with kinds
MeshSubset
andMeshServiceSubset
- Type:
object
- This schema accepts additional properties.
- Properties
- Tags used to select a subset of proxies by tags. Can only be used with kinds
- kind
- default
Generated with json-schema-md-doc