ASMCircuitBreaker CRD reference - Alibaba Cloud Service Mesh

Service Mesh (ASM) lets you declaratively configure circuit breaking using the ASMCircuitBreaker Custom Resource Definition (CRD). This topic describes the fields of ASMCircuitBreaker.

Configuration examples

Example 1: Client-side circuit breaking

Note

This example requires an ASM instance of version 1.25.6.74 or later.

The following example shows how to configure client-side circuit breaking. When the sleep application accesses the httpbin application, if more than 60% of requests fail or more than 10 slow requests occur within 10 seconds, the circuit breaker trips. A status code of 499 is returned.

Expand to view the YAML file

apiVersion: istio.alibabacloud.com/v1
kind: ASMCircuitBreaker
metadata:
  name: client-break
spec:
  workloadSelector:
    labels:
      app: sleep
  applyToTraffic: sidecar_outbound
  configs:
    - target_services:
      - name: httpbin
        port: 8000
      breaker_config:
        slow_request_rt: 0.1s # The response time threshold for a request to be considered slow.
        break_duration: 90s # The duration for which the circuit breaker remains open.
        window_size: 10s # The time window for request statistics is 10s.
        max_slow_requests: 10 # The maximum number of slow requests is 10.
        min_request_amount: 3 # Start calculating the error rate after 3 requests.
        error_percent:
          value: 60 # More than 60% of requests have errors.
        custom_response:
          header_to_add:
            x-envoy-circuitbreak: "true"
          body: "hello, break!"
          status_code: 499

Example 2: Waypoint circuit breaking

This example applies only to the Ambient mode and requires an ASM instance of version 1.25.6.74 or later.

This example configures a circuit breaking rule for an application on the waypoint named default. The circuit breaking rule is the same as in Example 1.

Expand to view the YAML file

apiVersion: istio.alibabacloud.com/v1
kind: ASMCircuitBreaker
metadata:
  name: test
spec:
  workloadSelector:
    labels:
      gateway.networking.k8s.io/gateway-name: default
  applyToTraffic: waypoint
  configs:
    - target_services:
      - name: httpbin
        port: 8000
      breaker_config:
        slow_request_rt: 0.1s
        break_duration: 90s
        window_size: 10s
        max_slow_requests: 10
        min_request_amount: 3
        error_percent:
          value: 60
        custom_response:
          header_to_add:
            x-envoy-circuitbreak: "true"
          body: "hello, break!"
          status_code: 499

apiVersion

If your ASM instance is version 1.15.3.105 or later, use apiVersion: istio.alibabacloud.com/v1. If you have configured this in an Alibaba Cloud Container Service for Kubernetes (ACK) cluster, change the apiVersion: istio.alibabacloud.com/v1beta1 field in the corresponding ASMCircuitBreaker CRD to apiVersion: istio.alibabacloud.com/v1, and then redeploy.
If your ASM instance is earlier than version 1.15.3.105, use apiVersion: istio.alibabacloud.com/v1beta1.

spec

The following table describes the fields in the spec section. For more information about the features and use cases of ASMCircuitBreaker, see Use route-level circuit breaking in ASM.

Field

Type

Required

Description

applyToTraffic

string

The type of traffic to which the circuit breaking policy applies. Valid values:

sidecar_inbound: Inbound traffic to a sidecar. This is traffic received by an application with a mounted sidecar proxy, where the application acts as a server.
sidecar_outbound: Outbound traffic from a sidecar. This is traffic sent by an application with a mounted sidecar proxy, where the application acts as a client.
waypoint: Traffic processed by a waypoint proxy in Ambient mode.
gateway: Gateway traffic.

The default value is sidecar_outbound.

Note

This field is supported only in ASM 1.25 and later versions.

ASMCircuitBreakerSpec

Field	Type	Required	Description
workloadSelector	map<string, string>	Yes	Uses one or more labels to select a specific set of pods or virtual machines (VMs) to which the circuit breaking configuration applies. The label search is scoped to the namespace where the resource is located. For more information, see WorkloadSelector.
isGateway	bool	No	Specifies whether the configuration applies to a gateway. If set to true, the configuration applies to a gateway. The default value is false.
configs	CircuitBreakerConfig[]	Yes	The circuit breaking configurations. You can specify multiple configurations.

CircuitBreakerConfig

Field	Type	Required	Description
name	string	No	The name of a single circuit breaking configuration.
match	CircuitBreakerMatch	No	The match conditions.
breaker_config	BreakerConfig	No	The route-level circuit breaking configuration.
target_services	TargetServiceRef[]	No	The services to which the circuit breaking policy applies. Note This field is supported only in ASM 1.25 and later versions.

TargetServiceRef

Note

These fields are supported only in ASM 1.25 and later.

Field	Type	Required	Description
kind	string	No	The kind of the service to which the circuit breaking policy applies. Valid values: `Service` `ServiceEntry` `VirtualService` The default value is `Service`.
name	string	Yes	The name of the service to which the circuit breaking policy applies.
namespace	string	No	The namespace where the service to which the circuit breaking policy applies is located. The default value is the namespace where you define the circuit breaking policy.
port	int32	No	The port of the service to which the circuit breaking policy applies.
section_name	string	No	An additional property of the service. This field is valid only for a `VirtualService`. `VirtualService`: The value is the name of a route defined in the `VirtualService`.

Example 1

The following example applies the policy to port 8000 of the httpbin Service in the default namespace.

target_services:
- kind: Service
  namespace: default
  name: httpbin
  port: 8000

Example 2

Assume that the following ServiceEntry exists in the current instance.

apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: se-httpbin-external
spec:
  hosts:
  - httpbin.test.com
  location: MESH_EXTERNAL
  ports:
  - name: http
    number: 80
    protocol: HTTP
  - name: https
    number: 443
    protocol: HTTPS
  resolution: DNS

The following policy applies to port 80 of this ServiceEntry.

target_services:
- kind: ServiceEntry
  namespace: default
  name: se-httpbin-external
  port: 80

Example 3

Assume that the following VirtualService exists in the current instance.

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: vs-httpbin
spec:
  hosts:
  - httpbin.test.com
  http:
  - name: default
    route:
    - destination:
        host: httpbin
        port:
          number: 8000

The following policy applies to the HTTP routing rule named default that is defined in the VirtualService.

target_services:
- kind: VirtualService
  namespace: default
  name: vs-httpbin
  section_name: default

CircuitBreakerMatch

Field	Type	Required	Description
vhost	VirtualHostMatch	No	The match conditions for a virtual host.

BreakerConfig

Field	Type	Required	Description
window_size	Duration	No	The time window for statistics. The default value is 10s. The maximum value is 12s.
break_duration	Duration	No	The duration for which the circuit breaker remains open. The default value is 30s.
slow_request_rt	Duration	No	Defines the response latency threshold for a slow request. A request is considered slow if its response time exceeds this value.
average_request_rt	Duration	For ASM instances earlier than 1.14: Yes For ASM instances 1.14 and later: No	Defines the average response time for the service, for example, 0.01s.
max_slow_requests	uint32	No	The maximum number of slow requests. This must be an integer, for example, 1000. New requests are rejected if this number is exceeded.
error_percent	Percent	No	The error percentage. If the percentage of requests with 5xx errors in the time window exceeds this value, new requests are rejected.
gateway_error_percent	Percent	No	The gateway error percentage. If the percentage of requests with gateway errors (502, 503, 504) in the time window exceeds this value, new requests are rejected. This field is valid only for ASM instances of version 1.24.6.54 or later.
min_request_amount	uint32	No	The minimum number of requests. This field corresponds to the error_percent condition. The default value is 0. You can configure a minimum number of requests to prevent the circuit breaker from tripping due to a small number of failures.
custom_response	CustomResponse	No	The custom response to return when a request is rejected by the circuit breaker.

CustomResponse

Field	Type	Required	Description
status_code	int32	No	The HTTP response status code.
header_to_add	map[string]string	No	The headers to add to the custom response.
body	string	No	The body of the custom response.

VirtualHostMatch

Field	Type	Required	Description
name	string	No	The name of the virtual host to match.
port	int	No	The request port to match.
route	RouteMatch	Yes	The name of the API routing rule to match.

RouteMatch

Field	Type	Required	Description
name_match	string	Gateway: Yes Sidecar: No	The name of the route to match. This corresponds to a single route name in a VirtualService.
header_match	HeaderMatcher[]	No	Matches the headers of a service request. You can specify multiple headers. Important To use this field, your ASM instance must be version 1.16 or later, and the corresponding gateway instance and sidecar must be the latest versions. For more information about how to upgrade an ASM instance, see Upgrade an ASM instance. For more information about how to upgrade a sidecar proxy, see Upgrade a sidecar proxy.

HeaderMatcher

Field		Type	Required	Description
name		string	No	The header name.
Choose one of the following	regex_match	string	No	Matches the value using a regular expression.
	exact_match	string	No	Performs an exact match.
	prefix_match	string	No	Performs a prefix match. Matches a value that starts with the specified prefix.
	suffix_match	string	No	Performs a suffix match. Matches a value that ends with the specified suffix.
	present_match	bool	No	If set to true, the header must be present, regardless of its value. If set to false, the header must not be present.
invert_match		bool	No	The default value is false. If set to true, the match result is inverted. If set to false, the original match result is used.