All Products
Search
Document Center

Alibaba Cloud Service Mesh:ASMSwimLaneGroup and ASMSwimLane field reference

Last Updated:Mar 11, 2026

Service Mesh (ASM) provides two CustomResourceDefinitions (CRDs) for traffic lane management: ASMSwimLaneGroup and ASMSwimLane. Together, they let you isolate specific service versions or services with certain characteristics into independent runtime environments called traffic lanes, then route matching requests to those versions.

How these CRDs work together

An ASMSwimLaneGroup defines what to isolate: the services that participate in traffic lanes and the ingress gateway that routes requests to them. An ASMSwimLane defines how to isolate: which pod versions belong to a lane and what routing rules apply.

The relationship:

  • One ASMSwimLaneGroup groups multiple services and specifies a shared ingress gateway.

  • Multiple ASMSwimLane resources associate with that group through the label swimlane-group: <group-name>. Each lane targets a specific version of the grouped services.

ASM supports two lane modes:

  • Strict mode (isPermissive: false or unset) -- Every lane must contain all services defined in the group.

  • Permissive mode (isPermissive: true) -- Lanes can contain a subset of the group's services. Requests to missing services fall back to a baseline lane.

Configuration example

The following YAML creates a lane group named mock for three services (mocka, mockb, mockc) in the default namespace. Two lanes, v1 and v2, match pods by their version label. A virtual service is generated from the Istio gateway ingressgateway in istio-system to route requests to each lane.

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

When these resources are applied, calls between mocka, mockb, and mockc stay within the same version. The v1 lane only routes to v1 pods, and the v2 lane only routes to v2 pods.

ASMSwimLaneGroup fields

ASMSwimLaneGroup defines a traffic lane group -- the shared configuration for services and ingress routing across multiple lanes.

ASMSwimLaneGroupSpec

The spec section is the core configuration.

FieldTypeRequiredDescription
servicesClusterServiceRef[]YesServices in a Kubernetes cluster that participate in traffic lanes.
ingressSwimLaneGroupIngressConfigurationYesIngress gateway configuration for routing requests to different service versions.
isPermissiveboolNoLane group mode. true: permissive mode. false or unset: strict mode. For details, see Overview of traffic lanes.
permissiveModeConfigurationPermissiveSwimLaneGroupConfigurationNoPermissive mode settings. Required when isPermissive is true.

ClusterServiceRef

References a Kubernetes service that participates in traffic lanes.

FieldTypeRequiredDescription
namestringYesName of the Kubernetes service.
namespacestringYesNamespace of the Kubernetes service.
clusterClusterRefNoReference to the Kubernetes cluster. Use this when the ASM instance manages multiple clusters.

ClusterRef

Identifies a Kubernetes cluster added to the ASM instance.

FieldTypeRequiredDescription
namestringNoDisplay name of the Kubernetes cluster.
idstringNoID of the Kubernetes cluster.

SwimLaneGroupIngressConfiguration

Configures the ingress gateway that routes requests to services in the lane group.

FieldTypeRequiredDescription
gatewaySwimLaneGatewayConfigurationYesIstio gateway associated with the ingress gateway.
ingressRoutingSwimLaneGroupIngressRouteConfigurationNoRequest routing strategy for the lane group.
Note

Requires ASM v1.21.6.92 or later.

SwimLaneGatewayConfiguration

Specifies the Istio gateway associated with the ingress gateway.

FieldTypeRequiredDescription
namestringYesName of the Istio gateway.
namespacestringYesNamespace of the Istio gateway.
typestringYesType of the Istio gateway. Set this to ASM, which indicates an Istio gateway provided by ASM.

SwimLaneGroupIngressRouteConfiguration

Defines the request routing strategy for the lane group.

FieldTypeRequiredDescription
ingressRoutingStrategystringNoRouting strategy. Valid values: rule_based (default) -- each lane defines its own routing rules via ingressRules. weighted -- requests are distributed across lanes by weight using a shared routing rule.
weightedRoutingRuleWeightedSwimLaneIngressConfigurationNoUnified request matching rule for weight-based routing. Takes effect only when ingressRoutingStrategy is weighted.

WeightedSwimLaneIngressConfiguration

Defines the unified request matching rule used with weight-based routing.

FieldTypeRequiredDescription
hosts[]stringYesHosts to match against. Must be declared in the Istio gateway associated with the lane group.
requestMatchesSwimLaneIngressRequestMatchNoURI and header matching conditions.

PermissiveSwimLaneGroupConfiguration

Configures permissive mode for a traffic lane group. Required when isPermissive is true.

FieldTypeRequiredDescription
routeHeaderstringYesRequest header that determines which lane a request belongs to as it travels through the call chain. Requests entering through the ingress gateway must carry this header.
traceHeaderstringYesEnd-to-end (E2E) pass-through header that propagates across the call chain. Must be unique per request when it differs from routeHeader. Example: x-b3-trace-id.
fallbackTargetstringNoName of the baseline lane. When a request cannot reach the target service version in its designated lane, the request falls back to the same service in this baseline lane.

ASMSwimLane fields

ASMSwimLane defines a single traffic lane -- a set of service versions that are isolated together. Associate a lane with a lane group by adding the label swimlane-group: <group-name> to the ASMSwimLane resource.

ASMSwimLaneSpec

The spec section is the core configuration.

FieldTypeRequiredDescription
labelSelectormap<string, string>YesLabels used to match pods for services in this lane. Typically uses version labels, such as version: v1.
servicesClusterServiceRef[]NoServices deployed in this lane. In strict mode, omit this field -- every lane must include all services from the group. In permissive mode, specify the services in this lane. The list must be a subset of the group's services field. Requests to services missing from this lane are forwarded to the baseline lane.
ingressRulesSwimLaneIngressRule[]NoRouting rules that ASM automatically converts into a virtual service for the ingress gateway. If omitted, create a virtual service manually.
ingressWeightSwimLaneIngressWeightNoRouting weight for this lane when the group uses weight-based routing (ingressRoutingStrategy: weighted).

SwimLaneIngressRule

Defines a routing rule for the ingress gateway. ASM converts each rule into part of a virtual service.

FieldTypeRequiredDescription
onlineboolYesWhether this rule is active. The virtual service is generated only when this is true.
hostsstring[]YesHosts to match. Maps to the hosts field in the generated virtual service.
namestringNoName of this routing rule. Maps to the name field under http in the generated virtual service.
matchSwimLaneIngressRequestMatchNoRequest matching conditions. Maps to the match field under http in the generated virtual service.
routeSwimLaneIngressRouteYesDestination service for matched requests. Maps to the route field under http in the generated virtual service.

SwimLaneIngressWeight

Specifies routing weight for a lane when weight-based routing is used.

FieldTypeRequiredDescription
weightintNoRouting weight for this lane. Defaults to 0. ASM uses the weights of all lanes to calculate the request distribution ratio.
destinationRouteDestinationYesDestination service for weight-based routing.

SwimLaneIngressRequestMatch

Defines conditions for matching requests by URI or headers.

FieldTypeRequiredDescription
uriStringMatchNoURI matching condition. Supports exact, prefix, and regex (RE2 syntax).
headersmap<string, StringMatch>NoHeader matching conditions. Keys are header names in lowercase with hyphens (for example, x-request-id). Values define the match type.

StringMatch

Defines how to match a string value. Specify exactly one field.

FieldTypeRequiredDescription
exactstringNoExact string match.
prefixstringNoPrefix match.
regexstringNoRE2 regular expression match. See RE2 syntax.

SwimLaneIngressRoute

Specifies the destination service for matched requests.

FieldTypeRequiredDescription
destinationRouteDestinationYesDestination service.

RouteDestination

Identifies the target Kubernetes service.

FieldTypeRequiredDescription
hoststringYesFully qualified domain name of the Kubernetes service. Example: mocka.default.svc.cluster.local.
portNumintNoService port number. Example: 8000.
Note

Requires ASM v1.21.4.104 or later.

Related topics