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: falseor 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.
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.
| Field | Type | Required | Description |
|---|---|---|---|
services | ClusterServiceRef[] | Yes | Services in a Kubernetes cluster that participate in traffic lanes. |
ingress | SwimLaneGroupIngressConfiguration | Yes | Ingress gateway configuration for routing requests to different service versions. |
isPermissive | bool | No | Lane group mode. true: permissive mode. false or unset: strict mode. For details, see Overview of traffic lanes. |
permissiveModeConfiguration | PermissiveSwimLaneGroupConfiguration | No | Permissive mode settings. Required when isPermissive is true. |
ClusterServiceRef
References a Kubernetes service that participates in traffic lanes.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name of the Kubernetes service. |
namespace | string | Yes | Namespace of the Kubernetes service. |
cluster | ClusterRef | No | Reference to the Kubernetes cluster. Use this when the ASM instance manages multiple clusters. |
ClusterRef
Identifies a Kubernetes cluster added to the ASM instance.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | Display name of the Kubernetes cluster. |
id | string | No | ID of the Kubernetes cluster. |
SwimLaneGroupIngressConfiguration
Configures the ingress gateway that routes requests to services in the lane group.
| Field | Type | Required | Description |
|---|---|---|---|
gateway | SwimLaneGatewayConfiguration | Yes | Istio gateway associated with the ingress gateway. |
ingressRouting | SwimLaneGroupIngressRouteConfiguration | No | Request 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.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name of the Istio gateway. |
namespace | string | Yes | Namespace of the Istio gateway. |
type | string | Yes | Type 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.
| Field | Type | Required | Description |
|---|---|---|---|
ingressRoutingStrategy | string | No | Routing 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. |
weightedRoutingRule | WeightedSwimLaneIngressConfiguration | No | Unified 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.
| Field | Type | Required | Description |
|---|---|---|---|
hosts | []string | Yes | Hosts to match against. Must be declared in the Istio gateway associated with the lane group. |
requestMatches | SwimLaneIngressRequestMatch | No | URI and header matching conditions. |
PermissiveSwimLaneGroupConfiguration
Configures permissive mode for a traffic lane group. Required when isPermissive is true.
| Field | Type | Required | Description |
|---|---|---|---|
routeHeader | string | Yes | Request 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. |
traceHeader | string | Yes | End-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. |
fallbackTarget | string | No | Name 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.
| Field | Type | Required | Description |
|---|---|---|---|
labelSelector | map<string, string> | Yes | Labels used to match pods for services in this lane. Typically uses version labels, such as version: v1. |
services | ClusterServiceRef[] | No | Services 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. |
ingressRules | SwimLaneIngressRule[] | No | Routing rules that ASM automatically converts into a virtual service for the ingress gateway. If omitted, create a virtual service manually. |
ingressWeight | SwimLaneIngressWeight | No | Routing 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.
| Field | Type | Required | Description |
|---|---|---|---|
online | bool | Yes | Whether this rule is active. The virtual service is generated only when this is true. |
hosts | string[] | Yes | Hosts to match. Maps to the hosts field in the generated virtual service. |
name | string | No | Name of this routing rule. Maps to the name field under http in the generated virtual service. |
match | SwimLaneIngressRequestMatch | No | Request matching conditions. Maps to the match field under http in the generated virtual service. |
route | SwimLaneIngressRoute | Yes | Destination 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.
| Field | Type | Required | Description |
|---|---|---|---|
weight | int | No | Routing weight for this lane. Defaults to 0. ASM uses the weights of all lanes to calculate the request distribution ratio. |
destination | RouteDestination | Yes | Destination service for weight-based routing. |
SwimLaneIngressRequestMatch
Defines conditions for matching requests by URI or headers.
| Field | Type | Required | Description |
|---|---|---|---|
uri | StringMatch | No | URI matching condition. Supports exact, prefix, and regex (RE2 syntax). |
headers | map<string, StringMatch> | No | Header 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.
| Field | Type | Required | Description |
|---|---|---|---|
exact | string | No | Exact string match. |
prefix | string | No | Prefix match. |
regex | string | No | RE2 regular expression match. See RE2 syntax. |
SwimLaneIngressRoute
Specifies the destination service for matched requests.
| Field | Type | Required | Description |
|---|---|---|---|
destination | RouteDestination | Yes | Destination service. |
RouteDestination
Identifies the target Kubernetes service.
| Field | Type | Required | Description |
|---|---|---|---|
host | string | Yes | Fully qualified domain name of the Kubernetes service. Example: mocka.default.svc.cluster.local. |
portNum | int | No | Service port number. Example: 8000. Note Requires ASM v1.21.4.104 or later. |
Related topics
Overview of traffic lanes: Concepts, use cases, and comparison between strict and permissive modes.
Use traffic lanes in strict mode to manage end-to-end traffic
Use traffic lanes in permissive mode to manage end-to-end traffic