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 parameter 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.

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 parameter to `ASM`. It indicates that the Istio gateway is created in ASM.

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.

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 parameter is set to true.
hosts	string[]	Yes	The domain name that matches 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.

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`.

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.