Install a sidecar proxy by enabling automatic injection - Alibaba Cloud Service Mesh

When multiple services communicate within a Kubernetes cluster, you need centralized control over network features such as load balancing, service discovery, traffic control, retries, and timeouts -- without modifying application code. Alibaba Cloud Service Mesh (ASM) solves this by injecting a sidecar proxy (an Envoy instance) alongside each application container. The sidecar proxy intercepts all inbound and outbound traffic and enforces routing rules and service governance policies that the Istio control plane pushes in real time. Each service in your application requires a sidecar proxy to run in the pod of the service.

To add sidecar proxies to your workloads, label a namespace to enable automatic injection, then restart the pods in that namespace.

How injection works

When you enable sidecar proxy injection for a namespace, ASM registers a Kubernetes mutating admission webhook. Each time a pod is created in that namespace, the webhook adds an istio-proxy container to the pod. After injection, a pod runs two containers:

Application container -- your service
Sidecar proxy container (istio-proxy) -- an Envoy instance that intercepts all inbound and outbound HTTP traffic and communicates with the Pilot component on the Istio control plane

Because injection happens at pod creation time, existing pods do not receive a sidecar proxy until you restart them.

Prerequisites

Before you begin, make sure that you have:

An ASM instance with a Kubernetes cluster added to the mesh
kubectl configured to connect to the cluster
Permissions to label namespaces and restart workloads

Step 1: Enable automatic sidecar proxy injection

By default, automatic sidecar proxy injection is disabled for all namespaces. You can manually inject a sidecar proxy by updating the Kubernetes configuration of the corresponding pod, or you can use the automatic injection feature. To enable automatic injection, label the target namespace:

kubectl label namespace <namespace> istio-injection=enabled --overwrite

Replace <namespace> with the namespace of your application. If you do not specify this parameter, the default namespace is used.

Verify the label:

kubectl get namespace <namespace> --show-labels

The output should include istio-injection=enabled.

Note

You can also enable sidecar proxy injection through the ASM console. For more information, see Manage global namespaces.

Step 2: Restart pods to trigger injection

Sidecar proxies are injected only when pods are created. To inject sidecar proxies into existing workloads, restart them.

Restart a deployment (recommended)

Use kubectl rollout restart to perform a rolling restart. This gradually replaces old pods with new ones that include the sidecar proxy:

kubectl rollout restart deployment <deployment-name> -n <namespace>

Restart a specific pod

To restart an individual pod, run the following command:

kubectl get pod <pod-name> -n <namespace> -o yaml | kubectl replace --force -f -

Important

This command force-deletes and recreates the pod, which causes a brief traffic interruption for that pod. Test this approach in a non-production environment first to confirm that your service tolerates the interruption. Run multiple restarts to verify stability before applying this method in production.

Step 3: Verify sidecar proxy injection

After restarting, confirm that the sidecar proxy was injected.

Check the READY column

Run the following command:

kubectl get pods -n <namespace>

Before injection, pods show 1/1 in the READY column (application container only). After injection, pods show 2/2 (application container + sidecar proxy container):

NAME                          READY   STATUS    RESTARTS   AGE
my-app-6b7d8f9c4d-abc12      2/2     Running   0          30s
my-app-6b7d8f9c4d-def34      2/2     Running   0          28s

If a pod still shows 1/1, verify that the namespace label is set correctly and that the pod was created after labeling.

Confirm the istio-proxy container

For a detailed check, describe a specific pod:

kubectl describe pod <pod-name> -n <namespace>

Look for istio-proxy in the Containers section of the output. The istio-proxy container is the Envoy sidecar proxy. Its presence confirms that the pod is part of the ASM data plane.

What's next

Injection policies -- Control which pods receive sidecar proxies by using labels and selectors. You can also adjust the resource configuration of the sidecar injector based on the size and load of your cluster. See Configure sidecar proxy injection policies.
Sidecar proxy settings -- Adjust resource limits, lifecycle hooks, traffic interception mode, and observability settings through the ASM console. See Configure sidecar proxies.
Annotation-based configuration -- Modify sidecar proxy resources and behavior (such as termination drain duration and istio-proxy start sequence) by using pod annotations. See Configure a sidecar proxy by adding resource annotations.
Bypass sidecar proxies -- For traffic that should not pass through sidecar proxies, configure bypass rules. See Configure settings to allow traffic to bypass sidecar proxies.