Configure sidecar injection policies and the sidecar injector - Alibaba Cloud Service Mesh

Service Mesh (ASM) uses a sidecar injector to automatically inject sidecar proxies into new pods. To control which pods receive a sidecar, you configure two matching conditions -- one at the namespace level and one at the pod level. A pod receives a sidecar only when both conditions are met.

This topic explains how injection decisions work, walks through policy configuration, and covers how to tune the sidecar injector for reliability.

How injection decisions work

ASM evaluates two conditions before injecting a sidecar into a pod. Both must be satisfied:

Namespace label -- The namespace where the pod runs must match the namespace-level condition.
Pod label or annotation -- The pod itself must match the pod-level condition.

The following table lists the relevant labels and values:

Resource	Label key	Enabled value	Disabled value
Namespace	`istio-injection`	`enabled`	`disabled`
Pod	`sidecar.istio.io/inject`	`"true"`	`"false"`

A sidecar is automatically injected into a pod only if the pod matches both the namespace label condition and the pod label/annotation condition.

Note

In ASM instances earlier than v1.12, only pod annotations are evaluated. From v1.12 onward, both labels and annotations are supported, and labels take priority over annotations. For example, if a pod has the sidecar.istio.io/inject: "true" label and the sidecar.istio.io/inject: "false" annotation, the label wins.

Prerequisites

Before you begin, make sure that you have:

An ASM instance with an ACK cluster added. For more information, see Add a cluster to an ASM instance

Configure automatic injection policies

Log on to the ASM console. In the left-side navigation pane, choose Service Mesh > Mesh Management.
On the Mesh Management page, click the name of the target ASM instance. In the left-side navigation pane, choose Data Plane Component Management > Sidecar Proxy injection.

In the Injection strategy configuration management section, set the two matching conditions:

Note

If you select Not include istio-injection: disabled for the namespace condition and Not Include sidecar.istio.io/inject: "false" or Selected by NeverInjectSelector for the pod condition, ASM automatically adds the istio-injection: disabled label to the kube-system namespace. This protects system components from unintended injection.

Matching condition	Options
Pod namespace label should meet condition	Include istio-injection: enabled -- Injects sidecars into pods whose namespace has the `istio-injection: enabled` label.
	Not include istio-injection: disabled -- Injects sidecars into pods whose namespace does not have the `istio-injection: disabled` label.
Pod label/annotation should meet condition	Not Include sidecar.istio.io/inject: "false" or Selected by NeverInjectSelector -- Injects sidecars into pods that do not have the `sidecar.istio.io/inject: "false"` label or annotation.
	Include sidecar.istio.io/inject: "true" or Selected by AlwaysInjectSelector -- Injects sidecars into pods that have the `sidecar.istio.io/inject: "true"` label or annotation.

(Optional) Click Show Advanced Settings to configure AlwaysInjectSelector and NeverInjectSelector. These are pod label selectors that override the pod-level condition: Both selectors use the same configuration format. Each selector supports multiple label match expressions, and a pod is selected if it matches any expression. Each expression contains:

Key: The pod label key to match.
Operator: In, NotIn, Exists, or DoesNotExist.
Value: A list of values. Required for In and NotIn operators.

Selector	Effect
AlwaysInjectSelector	Pods matching this selector are treated as having `sidecar.istio.io/inject: "true"`.
NeverInjectSelector	Pods matching this selector are treated as having `sidecar.istio.io/inject: "false"`.

Click Update Settings.

Configure the sidecar injector

The sidecar injector is an admission webhook deployed in the istio-system namespace of your data plane Kubernetes cluster. Its service and workloads use the name prefix istio-sidecar-injector. The injector itself is not a sidecar proxy -- it is the component that injects sidecar proxies into pods.

Adjust the injector's resources and replicas to maintain availability, especially when many pods are created simultaneously.

Log on to the ASM console. In the left-side navigation pane, choose Service Mesh > Mesh Management.
On the Mesh Management page, click the name of the target ASM instance. In the left-side navigation pane, choose Data Plane Component Management > Sidecar Proxy injection.

In the Injection strategy configuration management section, configure the following settings, then click Update Settings.

Setting	Description
Resource Settings for Sidecar Injector	Set Resource Limits (CPU in cores, memory in MiB) and Required Resources (CPU in cores, memory in MiB) for the injector container.
pod replicas	Number of injector pod replicas. Set to 2 or more to maintain availability during high-volume injection.
Rewrite App Probe	Enable or disable health check rewriting during injection. For details, see Enable health check redirection for applications in a service mesh.
Sidecar-injector NodeSelector	Click Add Match Label to specify the Name and Value of node labels. The injector pods are deployed only on nodes with matching labels.

Note

Configure monitoring and alerts for the injector's admission webhook to detect failures early. For more information, see Container Service alert management and kube-apiserver: Monitoring metrics.

Example 1: Namespace-wide injection with per-pod opt-out

This example enables sidecar injection for all pods in a labeled namespace, then disables injection for a specific pod.

Policy settings:

Matching condition	Value
Pod namespace label should meet condition	Include istio-injection: enabled
Pod label/annotation should meet condition	Not Include sidecar.istio.io/inject: "false" or Selected by NeverInjectSelector

Step 1: Set the injection policy

Log on to the ASM console. In the left-side navigation pane, choose Service Mesh > Mesh Management.
Click the target ASM instance. Choose Data Plane Component Management > Sidecar Proxy injection.
In Injection strategy configuration management, select the values from the table above, then click Update Settings.

Step 2: Create a namespace with injection enabled

On the ASM instance details page, choose ASM Instance > Global Namespace in the left-side navigation pane, then click Create.
In the Create Namespace panel, enter a Name (for example, test1). Click Add next to Labels, set Name to istio-injection and Value to enabled, then click OK.
At the top of the page, click Sync Sidecar Auto-Injection from Kubernetes Cluster to sync the namespace to the data plane.

Step 3: Deploy an application and verify injection

Deploy the details application in the test1 namespace. For more information, see Deploy an application in a cluster associated with an ASM instance.
Verify that the sidecar was injected:
- Console: In the ACK console, choose Clusters > your cluster > Workloads > Deployments. Set Namespace to test1 and click the details application. On the Pods tab, confirm the pod contains a Proxy container.
- kubectl:
```
kubectl get pod -n test1 -l app=details -o jsonpath='{.items[0].spec.containers[*].name}'
```
  If injection succeeded, the output includes istio-proxy.

Step 4: Disable injection for a specific pod

In the ACK console, choose Clusters > your cluster > Workloads > Deployments.
In the test1 namespace, click More > Edit YAML in the Actions column of the details application.
Add the opt-out label or annotation:
- ASM v1.12.4 or later: Add the label sidecar.istio.io/inject: 'false' under spec.template.metadata.labels.
- Earlier than ASM v1.12.4: Add the annotation sidecar.istio.io/inject: "false" under spec.template.metadata.annotations.
Click Update. The pod restarts without a sidecar proxy.

Step 5: Verify injection is disabled

Check the details pod again using the console or kubectl:

kubectl get pod -n test1 -l app=details -o jsonpath='{.items[0].spec.containers[*].name}'

The output should not include istio-proxy, confirming that injection is disabled for this pod while other pods in test1 still receive sidecars.

Pod without Proxy image showing disabled injection

Example 2: Per-pod opt-in injection

This example skips namespace-level labeling and lets individual pods opt in to injection through a pod-level label.

Policy settings:

Matching condition	Value
Pod namespace label should meet condition	Not include istio-injection: disabled
Pod label/annotation should meet condition	Include sidecar.istio.io/inject: "true" or Selected by AlwaysInjectSelector

Under this policy, sidecars are injected only into pods that explicitly carry the sidecar.istio.io/inject: "true" label, provided their namespace does not have istio-injection: disabled.

Step 1: Set the injection policy

Log on to the ASM console. In the left-side navigation pane, choose Service Mesh > Mesh Management.
Click the target ASM instance. Choose Data Plane Component Management > Sidecar Proxy injection.
In Injection strategy configuration management, select the values from the table above, then click Update Settings.

Step 2: Create a namespace without labels

Create a namespace named test2 without any injection labels in the ACK cluster. For more information, see Manage namespaces and quotas.

Step 3: Deploy an application and enable injection

Deploy the reviews application in the test2 namespace. For more information, see Deploy an application in a cluster associated with an ASM instance.
In the ACK console, choose Clusters > your cluster > Workloads > Deployments.
Set Namespace to test2. In the Actions column for reviews, click More > View YAML.
Under spec.template.metadata.labels, add the label sidecar.istio.io/inject: "true", then click Update.
Note
Label-based injection requires ASM v1.12.4 or later. To upgrade, see Upgrade an ASM instance.

Step 4: Verify injection

Check the reviews pod:

kubectl get pod -n test2 -l app=reviews -o jsonpath='{.items[0].spec.containers[*].name}'

The output includes istio-proxy, confirming that the sidecar was injected into the opted-in pod.

Verification of individual pod injection

What to do next

Restart running pods: Injection policies apply only to new pods. Restart existing pods for the policy to take effect. For more information, see Restart a pod.
Upgrade sidecar proxies: After upgrading the ASM control plane, update the sidecar proxy version in your applications. For more information, see Upgrade sidecar proxies.
Configure sidecar proxy settings: Customize resource usage, traffic interception, DNS proxy, and lifecycle settings at the global, namespace, workload, or pod level. For more information, see Configure a sidecar proxy.