Description of ASMSwimLaneGroup and ASMSwimLane fields - Alibaba Cloud Service Mesh

Service Mesh (ASM) allows you to implement traffic lane capabilities for the call chains of Services by using ASMSwimLaneGroup and ASMSwimLane CustomResourceDefinitions (CRDs). ASM allows you to isolate Services of specific versions of an application or an application with certain characteristics into an independent runtime environment (known as lane). Then, you can configure lane rules to route requests that meet the rules to the Services of the specific versions of the application or the application with certain characteristics.

Configuration example

The following configuration indicates that a lane group named mock is created for the mocka, mockb, and mockc Services in the default namespace of the Kubernetes cluster. The lane group contains two traffic lanes, v1 and v2. v1 and v2 correspond to the v1 and v2 versions of these Services respectively. The versions are distinguished by the version labels on the pods. When the mocka, mockb, and mockc Services call each other, only Services of the same version are called. This separates Services of v1 and v2. Moreover, a virtual service is created based on the Istio gateway named ingressgateway in the istio-system namespace to route requests to the two lanes.

Show the YAML file

apiVersion: istio.alibabacloud.com/v1
kind: ASMSwimLaneGroup
metadata:
  name: mock
spec:
  ingress:
    gateway:
      name: ingressgateway
      namespace: istio-system
      type: ASM
  services:
  - name: mocka
    namespace: default
  - name: mockb
    namespace: default
  - name: mockc
    namespace: default
---
apiVersion: istio.alibabacloud.com/v1
kind: ASMSwimLane
metadata:
  labels:
    swimlane-group: mock
  name: v1
spec:
  ingressRules:
  - hosts:
    - '*'
    match:
      uri:
        exact: /mock
    name: r1
    online: true
    route:
      destination:
        host: mocka.default.svc.cluster.local
  labelSelector:
    version: v1
---
apiVersion: istio.alibabacloud.com/v1
kind: ASMSwimLane
metadata:
  labels:
    swimlane-group: mock
  name: v2
spec:
  ingressRules:
  - hosts:
    - '*'
    match:
      uri:
        exact: /mock
    name: r2
    online: true
    route:
      destination:
        host: mocka.default.svc.cluster.local
  labelSelector:
    version: v2

Description of ASMSwimLaneGroup fields

ASMSwimLaneGroup defines a traffic lane group. A traffic lane group defines the information that is shared among multiple traffic lanes, including the Services for which traffic lanes need to be created and the Istio gateways based on which the virtual service used for request routing needs to be created. A traffic lane group can be associated with multiple traffic lanes. You can associate a traffic lane with a traffic lane group by specifying swimlane-group: {Name of the traffic lane group}.

ASMSwimLaneGroupSpec

ASMSwimLaneGroupSpec, the spec section in the preceding example, is the core configuration of ASMSwimLaneGroup.

Field	Type	Required	Description
services	ClusterServiceRef[]	Yes	Specifies Services in a Kubernetes cluster for which a lane needs to be created. You can reference a Service in a Kubernetes cluster by specifying the name, namespace, cluster ID, and cluster name of the Kubernetes Service.
ingress	SwimLaneGroupIngressConfiguration	Yes	Specifies the configuration of the ingress gateway of the traffic lane group. The ingress gateway is mainly used to route requests to multiple versions of the Services in the lane group.
isPermissive	bool	No	Specifies the mode of the traffic lane group. Valid values: true: permissive mode. false or left empty: strict mode. For more information about the traffic lanes in strict mode and permissive mode, see Overview of traffic lanes.
permissiveModeConfiguration	PermissiveSwimLaneGroupConfiguration	No	The configuration of the lane group in permissive mode. You must configure this field when the lane group is in permissive mode.

ClusterServiceRef

Each ClusterServiceRef references one Service deployed in a Kubernetes cluster. Lanes are created based on the references of Services.

Field	Type	Required	Description
name	string	Yes	The name of the Kubernetes Service.
namespace	string	Yes	The namespace where the Kubernetes Service resides.
cluster	ClusterRef	No	The reference information about the Kubernetes cluster.

ClusterRef

ClusterRef provides the reference information about the Kubernetes cluster that is added to the ASM instance.

Field	Type	Required	Description
name	string	No	The display name of the Kubernetes cluster.
id	string	No	The ID of the Kubernetes cluster.

SwimLaneGroupIngressConfiguration

SwimLaneGroupIngressConfiguration defines information about the ingress gateway that is used to route requests for Services in the lane group.

Field	Type	Required	Description
gateway	SwimLaneGatewayConfiguration	Yes	The information about the Istio gateway associated with the ingress gateway.
ingressRouting	SwimLaneGroupIngressRouteConfiguration	No	The configurations of request routing rules that are used to route requests for Services in the lane group. Note Only ASM instances of V1.21.6.92 and later support this field.

SwimLaneGatewayConfiguration

SwimLaneGatewayConfiguration defines information about the Istio gateway that is associated with the ingress gateway.

Field	Type	Required	Description
name	string	Yes	The name of the Istio gateway.
namespace	string	Yes	The namespace where the Istio gateway resides.
type	string	Yes	The type of the Istio gateway. You must set this field to `ASM`, which indicates the Istio gateway provided by ASM.

SwimLaneGroupIngressRouteConfiguration

SwimLaneGroupIngressRouteConfiguration specifies the configurations of request routing rules that are used to route requests for Services in the lane group.

Field

Type

Required

Description

ingressRoutingStrategy

string

The policy used to route requests for Services in the lane group. Valid values:

rule_based: the default request routing policy. Each lane uses the ingressRules field to specify its own request routing rule. Requests that match a request routing rule are sent to the corresponding lane.
weighted: the weight-based request routing policy. All Services in the lane group match requests based on a unified request routing rule. The matched requests are sent to Services in different lanes at a specified ratio.

weightedRoutingRule

WeightedSwimLaneIngressConfiguration

The unified request routing rule that is used to match all requests when the weight-based request routing policy is used. This field takes effect only when the ingressRoutingStrategy field is set to weighted.

WeightedSwimLaneIngressConfiguration

WeightedSwimLaneIngressConfiguration specifies the configuration of the unified request matching rule that is used to match all requests when the weight-based request routing policy is used.

Field	Type	Required	Description
hosts	[]string	Yes	The hosts that match requests. The hosts must be declared in the Istio gateway that is associated with the lane group.
requestMatches	SwimLaneIngressRequestMatch	No	The request matching rule that is used to match request URIs and headers.

PermissiveSwimLaneGroupConfiguration

PermissiveSwimLaneGroupConfiguration defines the parameters that need to be specified for a traffic lane group in permissive mode.

Field	Type	Required	Description
routeHeader	string	Yes	The name of the request routing header of a traffic lane in permissive mode. The request routing header is used to determine the lane of a request when the request is passed in a call chain. In permissive mode, when a request is forwarded to an upstream Service through an ingress gateway, the request must carry the request routing header that is used to determine the lane in which the request resides.
traceHeader	string	Yes	The name of the end-to-end (E2E) pass-through request header of a traffic lane in permissive mode. The E2E pass-through request header must have the following characteristics: The E2E pass-through request header is passed in the call chain. The E2E pass-through request header must be different for each request when the E2E pass-through request header is different from the request routing header. The trace ID can be used as the E2E pass-through request header. For example, you can use x-b3-trace-id as the E2E pass-through request header.
fallbackTarget	string	No	The name of the baseline lane in permissive mode. If a request fails to be routed to the Service of the corresponding version in the desired lane, the request is sent back to the corresponding version of the Service in the baseline lane.

Description of ASMSwimLane fields

ASMSwimLane defines a traffic lane. A traffic lane defines information related to specific versions or certain characteristics of a Service. You can add a swimlane-group: {Name of a traffic lane group} label to a traffic lane to associate it with the corresponding traffic lane group.

ASMSwimLaneSpec

ASMSwimLaneSpec, that is, the spec section, is the core configuration of ASMSwimLane.

Field	Type	Required	Description
labelSelector	map<string, string>	Yes	One or more labels used to match pods for Services in the lane. Generally, you can use labels with version information to match pods in a specific lane. For example, you can use the `version: v1` label to match pods for Services of v1.
services	ClusterServiceRef[]	No	Specifies Services that are deployed in the lane. This field is similar to the services field in ASMSwimLaneGroupSpec. You can reference a Service in a Kubernetes cluster by specifying the name, namespace, cluster ID, and cluster name of the Kubernetes Service. If the traffic lane is associated with a lane group in strict mode, you do not need to specify this field. By default, a lane must contain all Services of the lane group. If the traffic lane is associated with a lane group in permissive mode, you must specify this field. In this case, the services field in the ASMSwimLaneSpec section must be a subset of the services field in the ASMSwimLaneGroupSpec section. When Services in a lane call each other, if the Service to be called does not exist in the lane, requests are forwarded to the same Service in the baseline lane.
ingressRules	SwimLaneIngressRule[]	No	The definition of request routing rules for a lane. The definition is automatically converted to a virtual service for the ingress gateway that is associated with the lane group. The virtual service routes requests from the ingress gateway to Services in the lane. If you do not specify the ingressRules field, you can manually create a virtual service for the ingress gateway to route requests to Services in the lane.
ingressWeight	SwimLaneIngressWeight	No	If the lane group uses a weight-based request routing policy, this field specifies the request routing weight of the lane. The lane group forwards a certain proportion of requests to the ingress service of the lane based on the request routing weights declared for different lanes. This field takes effect only when the ingressRoutingStrategy field is set to weighted.

SwimLaneIngressRule

SwimLaneIngressRule specifies routing rules for an ingress gateway to route requests to Services in a lane. The rules are automatically converted to a virtual service for the ingress gateway.

Field	Type	Required	Description
online	bool	Yes	Specifies whether the request routing rules take effect. The corresponding virtual service is created for the ingress gateway only if the online field is set to true.
hosts	string[]	Yes	The hosts that match the request routing rules. This field corresponds to the hosts field in the virtual service.
name	string	No	The name of a request routing rule. It corresponds to the name field under the http section in the virtual service.
match	SwimLaneIngressRequestMatch	No	The conditions that a request must meet so that the request routing rules are matched. This field is automatically converted to the match field under the http section in the virtual service.
route	SwimLaneIngressRoute	Yes	The destination Service to which requests are routed. This field is automatically converted to the route field under the http section in the virtual service.

SwimLaneIngressWeight

Field	Type	Required	Description
weight	int	No	The request routing weight of the lane. If this field is not specified, the request routing weight is 0. The weight value is used together with the request routing weights of other lanes to determine the request routing ratio.
destination	RouteDestination	Yes	This field specifies the destination Service to which requests are forwarded when a weight-based request routing policy is used.

SwimLaneIngressRequestMatch

SwimLaneIngressRequestMatch specifies the conditions that requests must meet so that the request routing rules are matched.

Field

Type

Required

Description

uri

StringMatch

The conditions that a request URI must meet so that the corresponding request is matched. Valid values:

exact: "value": exact string match.
prefix: "value": prefix match.
regex: "value": RE2 regular expression match. For more information, see Syntax.

headers

map<string, StringMatch>

The conditions that a request header must meet so that the corresponding request is matched. Keys in a Map collection must be lowercase and contain hyphens (-). Keys, for example, x-request-id, represent the names of headers. Values in a Map collection are of the StringMatch type. Valid values:

exact: "value": exact string match.
prefix: "value": prefix match.
regex: "value": RE2 regular expression match. For more information, see Syntax.

StringMatch

StringMatch specifies the string match conditions, which define the method to match request URIs and headers.

Field		Type	Required	Description
Specify one of the fields based on the match mode	exact	string	No	Exact string match.
	prefix	string	No	Prefix match.
	regex	string	No	RE2 regular expression match. For more information, see wiki.

SwimLaneIngressRoute

SwimLaneIngressRoute specifies the destination Service to which requests are routed.

Field	Type	Required	Description
destination	RouteDestination	Yes	Specifies the destination Service to which requests are forwarded.

RouteDestination

Field	Type	Required	Description
host	string	Yes	The domain name of the Kubernetes Service. Example: `mocka.default.svc.cluster.local`.
portNum	int	No	The service port of the Kubernetes cluster. Example: `8000`. Note ASM instances of V1.21.4.104 and later support this field.

References

For more information about the concept and use scenarios of traffic lanes, and the comparison between traffic lanes in strict and permissive modes, see Overview of traffic lanes.
For more information about how to use traffic lanes in strict mode to manage end-to-end traffic, see Use traffic lanes in strict mode to manage end-to-end traffic.
For more information about how to use traffic lanes in permissive mode to manage end-to-end traffic, see Use traffic lanes in permissive mode to manage end-to-end traffic.