Traffic Labelling and Routing of ASM (1): The Definition of Traffic Label

By Xining Wang

Alibaba Cloud Service Mesh (ASM) allows you to configure traffic labels so that you can manage traffic based on the labels. You can route application traffic with specific labels to different services or versions. You can perform traffic control, such as circuit breaking and throttling, based on labels. ASM adds the TrafficLabel CustomResourceDefinition (CRD). You can use this CRD to define traffic label logics and configure traffic labels for namespaces and workloads.

This article describes how to configure traffic labels and provides descriptions of the fields in the CRD and configuration examples.

TrafficLabel

An ASM instance of version 1.17 or later supports apiVersion: istio.alibabacloud.com/v1 in the TrafficLabel CRD. If you have configured TrafficLabel in the Container Service for Kubernetes (ACK) cluster, change apiVersion: istio.alibabacloud.com/v1beta1 in the TrafficLabel CRD to apiVersion: istio.alibabacloud.com/v1 and then configure TrafficLabel again.
If the version of your ASM instance is earlier than 1.17, we recommend that you update the ASM instance to version 1.17 or later, or submit a ticket to obtain technical support.

For example, use the following parameter definitions in 1.17 or later:

apiVersion: istio.alibabacloud.com/v1
kind: TrafficLabel
metadata:
  name: example
  namespace: default
spec:
  workloadSelector:
    labels:
      app: httpbin
  rules:
  - labels:
      - name: asm-labels-test
        valueFrom:
        - $getLabel(ASM_TRAFFIC_TAG)

Version 1.17 or Later

If the version of the ASM instance is upgraded to 1.17 or later, use apiVersion: istio.alibabacloud.com/v1.

apiVersion: istio.alibabacloud.com/v1
kind: TrafficLabel
metadata:
  name: example
  namespace: default
spec:
  workloadSelector:
    labels:
      app: httpbin
  rules:
  - labels:
      - name: asm-labels-test-a
        valueFrom:
        - $getInboundRequestHeader(headerName)
        - $getExternalInboundRequestHeader(contextId, headerName) 
        - $getLocalOutboundRequestHeader(headerName)
        - $getLabel(labelName)

Spec

Field	Type	Description	Required
workloadSelector	WorkloadSelector	Indicates the workload range in which the selector applies the traffic label. If this field is left empty, the selector applies the traffic label to all workloads in the current namespace.	No
rules	[]TrafficLabelRule	Defines rules for traffic labels.	Yes

Attribute Field of WorkloadSelector

Field	Type	Description	Required
labels	map	Traffic labels that are applied to workloads. You can configure one or more labels.	No

TrafficLabelRule

Field	Type	Description	Required
labels	[]Label	The names and values of the labels that you want to configure.	Yes

Label

Field	Type	Description	Required
name	string	The name of the traffic label. The name must comply with the naming conventions of HTTP request headers.	Yes
valueFrom	[]string	The value of the traffic label. The value is obtained based on the variable order you set. The label value is preferentially obtained from the first variable. If it is unavailable, the second variable is checked and so on. For more information, see valueFrom.	Yes

valueFrom

The valueFrom field supports the following four variables: $getInboundRequestHeader(headerName), $getExternalInboundRequestHeader(headerName, contextId), $getLocalOutboundRequestHeader(headerName), and $getLabel(labelName).

The concise descriptions of the four variables are as follows.

Definition	Supported Workloads	Description
`$getInboundRequestHeader(headerName)`	Gateways	This variable indicates that the value of the header named headerName is obtained from the request that enters the gateway.
`$getExternalInboundRequestHeader(headerName, contextId)`	Sidecar Proxies	This variable indicates that the value of the header named headerName is obtained from the request that enters the sidecar proxy.
`$getLocalOutboundRequestHeader(headerName)`	Sidecar Proxies	This variable indicates that the value of the header named headerName is obtained from the request that the application sends to the sidecar proxy.
`$getLabel(labelName)`	Gateway or sidecar proxies	This variable indicates that the value of the label named labelName is obtained from the gateway pod or the pod of the sidecar container.

The detailed descriptions are as follows.

`$getInboundRequestHeader(headerName)`

This variable indicates that the value of the header named headerName is obtained from the request that enters the gateway. According to this function variable, the value of the traffic label is obtained from an inbound request header. The headerName parameter is the key of a request header. If the parameter is left empty, x-asm-prefer-tag is used by default.

Note: It takes effect only for the gateways, but not for the Sidecar proxies.

As shown in the following figure, the ingress gateway adds a new request header to the outbound request.

• The name of the request header is the label name (such as asm-labels-test-a in the preceding example) that is defined in the TrafficLabel CRD and the value is tagValue.

`$getExternalInboundRequestHeader(headerName, contextId)`

This variable indicates that the value of the header named headerName is obtained from the request that enters the sidecar proxy. According to this function variable, the value of the traffic label is obtained from the context of a traffic request. The variable contains the following parameters:

• The parameter headerName is the key of the request header. This parameter value is mandatory, such as x-asm-prefer-tag.

• The parameter contextId is a request header field that runs through the entire call chain. The value can be a specified inbound request header or a trace ID in the tracing system. This parameter is mandatory and cannot be left empty.

Note: It takes effect only for the sidecar proxies, but not for the gateways.

A sidecar proxy involves inbound traffic and outbound traffic. Traffic labeling is to label the outbound traffic. By default, a sidecar proxy obtains the value from the inbound request header whose name is headerName and uses this value as the label value tagValue for the traffic.

To add tagValue to an outbound request, the sidecar proxy keeps map in its internal logic. contextId is a request header field that runs through the entire call chain. The value can be a specified inbound request header or x-request-id.

When an application container initiates an outbound request, the sidecar proxy searches for the context map by using contextId. If the associated tagValue is found, the sidecar proxy adds two new request headers to the outbound request:

• The name of one request header is headerName and the value is tagValue.

• The name of the other request header is the label name (such as asm-labels-test-a in the preceding example) that is defined in the TrafficLabel CRD, and the value is tagValue.

Note

• By default, map is stored in the memory of an Envoy proxy for 30 seconds.

• When an application is connected to a tracing system, a trace ID is used in the request throughout the entire call chain. Therefore, you can use the trace ID as the contextId. Different tracing systems use different trace IDs. For more information, see Tracing.

• Although the Istio proxy can automatically send the tracing spans, the applications still need to propagate relevant HTTP headers, so that the spans sent by Istio proxies can be correctly correlated into a single trace. For more information, see: https://www.alibabacloud.com/help/en/alibaba-cloud-service-mesh/latest/enable-distributed-tracing-in-asm#h2-url-2

• If the corresponding HTTP header is not propagated, the Sidecar proxy will fail to find the corresponding traffic label value from map* because the outbound traffic cannot be associated with contextId.

`$getLocalOutboundRequestHeader(headerName)`

This variable indicates that the value of the header named headerName is obtained from the request that the application sends to the sidecar proxy. According to this function variable, the value of the traffic label is obtained from an inbound request header. The headerName parameter is the key of a request header. You can specify the parameter based on the actual request header of the application container.

Note: This variable takes effect only for sidecar proxies. It does not take effect for gateways.

As shown in the following figure, when the application container to which the sidecar proxy is injected initiates an outbound request, the sidecar proxy adds a request header to the outbound request.

• The name of the request header is the label name (such as asm-labels-test-a in the preceding example) that is defined in the TrafficLabel CRD and the value is tagValue.

`$getLabel(labelName)`

This variable indicates that the value of the label named labelName is obtained from the gateway pod or the pod of the sidecar container, and the value is added to the outbound traffic. If labelName is left empty, this variable obtains the value of the ASM_TRAFFIC_TAG label from the workload pod by default.

In the following example, the value of ASM_TRAFFIC_TAG is test. You can obtain test through $getLabel(ASM_TRAFFIC_TAG).

apiVersion: apps/v1
kind: Deployment
metadata:
  name: productpage-v1
  labels:
    app: productpage
    version: v1
spec:
  replicas: 1
  selector:
    matchLabels:
      app: productpage
      version: v1
  template:
    metadata:
      annotations:
        sidecar.istio.io/logLevel: debug
      labels:
        app: productpage
        version: v1
        ASM_TRAFFIC_TAG: test
    spec:
      serviceAccountName: bookinfo-productpage
      containers:
      - name: productpage
        image: docker.io/istio/examples-bookinfo-productpage-v1:1.16.2
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 9080
        volumeMounts:
        - name: tmp
          mountPath: /tmp
      volumes:
      - name: tmp
        emptyDir: {
   }

Version 1.16 or Earlier

We recommend that you upgrade it to 1.17 or submit a ticket for technical support.

Examples

Note: The following examples are based on 1.17 or later.

Example 1: Label traffic for a workload

You can define workloadSelector to select the workload based on the label and then label the traffic of the workloads in a namespace.

For example, after deploying the Bookinfo application according to the document for newcomers, you can label the productpage workload according to the following example.

apiVersion: istio.alibabacloud.com/v1
kind: TrafficLabel
metadata:
  name: productpage
  namespace: default
spec:
  workloadSelector:
    labels:
      app: productpage
  rules:
  - labels:
      - name: asm-labels-test-a
        valueFrom:
        - $getExternalInboundRequestHeader(header1, x-request-id)
        - $getLabel(header2)

1) Save the above content to a file named productpage-trafficlabel.yaml and run the following command:

kubectl apply -n default  -f productpage-trafficlabel.yaml

2) View the proxy configuration of the productpage workload:

kubectl exec -it -n default deploy/productpage-v1 -c istio-proxy -- curl localhost:15000/config_dump

You can see the preceding filter configuration in type.googleapis.com/envoy.config.listener.v3.Listener/envoy.filters.network.http_connection_manager/http_filters under Listener Config (type.googleapis.com/envoy.admin.v3.ListenersConfigDump) or dynamic_listeners. This indicates that the traffic label is configured.

{
   
              "name": "com.aliyun.traffic_label",
              "typed_config": {
   
               "@type": "type.googleapis.com/envoy.config.filter.traffic_label.v3alpha.TrafficLabel",

              }
             },

3) In addition, view the proxy configurations of other workloads, such as details Pod, and you can see that no relevant filter is available:

kubectl exec -it -n default deploy/details-v1 -c istio-proxy -- curl localhost:15000/config_dump |grep type.googleapis.com/envoy.config.filter.traffic_label.v3alpha.TrafficLabel

After you run the preceding command, an empty result is returned.

Example 2: Label traffic at the namespace level

If you leave the workloadSelector field empty, the label is added to the traffic of all workloads in the namespace. For example, the following configuration will label the traffic of all workloads in the default namespace.

apiVersion: istio.alibabacloud.com/v1
kind: TrafficLabel
metadata:
  name: all-workload-for-ns
  namespace: default
spec:
  rules:
  - labels:
      - name: asm-labels-test-b
        valueFrom:
        - $getExternalInboundRequestHeader(header1, x-request-id)
        - $getLabel(header2)

1) Save the above content to a file named all-workload-for-ns-trafficlabel.yaml and run the following command:

kubectl apply -n default -f all-workload-for-ns-trafficlabel.yaml

2) View the proxy configurations of a workload such as details Pod, and you can see that the relevant filter is available:

kubectl exec -it -n default deploy/details-v1 -c istio-proxy -- curl localhost:15000/config_dump |grep type.googleapis.com/envoy.config.filter.traffic_label.v3alpha.TrafficLabel

Expected output:

"@type": "type.googleapis.com/envoy.config.filter.traffic_label.v3alpha.TrafficLabel",

Community

Traffic Labelling and Routing of ASM (1): The Definition of Traffic Label

TrafficLabel

Version 1.17 or Later

Spec

Attribute Field of WorkloadSelector

TrafficLabelRule

Label

valueFrom

`$getInboundRequestHeader(headerName)`

`$getExternalInboundRequestHeader(headerName, contextId)`

`$getLocalOutboundRequestHeader(headerName)`

`$getLabel(labelName)`

Version 1.16 or Earlier

Examples

Example 1: Label traffic for a workload

Example 2: Label traffic at the namespace level

Read previous post:

Read next post:

Xi Ning Wang(王夕宁)

You may also like

Comments

Xi Ning Wang(王夕宁)

Related Products

Alibaba Cloud Service Mesh

Cloud-Native Applications Management Solution

Managed Service for Prometheus

PolarDB for Xscale