Inject sidecar proxies with Cloud Service Mesh

This document covers how to configure sidecar proxy injection with Cloud Service Meshto enhance network security, reliability, and observability. These functions areabstracted away from the application's primary container and implemented in acommon out-of-process proxy (the sidecar), delivered as a separate container inthe same Pod. This provides theCloud Service Mesh's features without redesigning yourproduction applications to participate in a service mesh.

Automatic sidecar proxy injection (auto-injection) occurs when Cloud Service Meshdetects a namespace label you configure for the workload's Pod. The proxyintercepts all inbound and outbound traffic to the workloads and communicateswith Cloud Service Mesh.

Permissions required for these tasks

To perform the tasks on this page, you must have theroles/container.clusterAdmin or a higher role. See Google Kubernetes Engine roles for details on the permissions included in this role.

Enabling automatic sidecar injection

The recommended way to inject sidecar proxies is to use the webhooks-basedautomatic sidecar injector, although you can manually update your Pods'Kubernetes configuration.

To enable auto-injection, you label your namespaces with thedefault injection labelsif the default tag is set up, or with therevision label to your namespace.The label that you add also depends on whether you deployedmanaged Cloud Service Mesh (with thefleet API or withasmcli), orinstalled the in-cluster control plane. The label is used by the sidecarinjector webhook to associate injected sidecars with a particular control planerevision.

To enable auto-injection:

In-cluster

  1. Use the following command to locate the revision label onistiod:

    kubectl -n istio-system get pods -l app=istiod --show-labels

    The output looks similar to the following:

    NAMEREADYSTATUSRESTARTSAGELABELSistiod-asm-11910-9-5788d57586-bljj41/1Running023happ=istiod,istio.io/rev=asm-11910-9,istio=istiod,pod-template-hash=5788d57586istiod-asm-11910-9-5788d57586-vsklm1/1Running123happ=istiod,istio.io/rev=asm-11910-9,istio=istiod,pod-template-hash=5788d57586

    In the output, under theLABELS column, note the value of theistiodrevision label, which follows the prefixistio.io/rev=. In thisexample, the value isasm-11910-9.

    Note: You can substituteistio.io/rev with theistio-injection=enabled label if thedefault tag is configured. Verify the default tag exists by running istioctl tag list with theistioctl fromOUTPUT_DIR.

  2. Apply the revision label to namespaces and remove the istio-injection label(if it exists). In the following command,NAMESPACE isthe name of the namespace where you want to enable auto-injection, andREVISION is the revision label you noted in theprevious step.

    kubectl label namespaceNAMESPACE  istio-injection- istio.io/rev=REVISION --overwrite

    You can ignore the message"istio-injection not found" in theoutput. That means that the namespace didn't previously have theistio-injection label, which you should expect in newinstallations of Cloud Service Mesh or new deployments. Because auto-injectionbehavior is undefined when a namespace has both theistio-injectionand the revision label, allkubectl label commands in theCloud Service Mesh documentation explicitly ensure that only one is set.

  3. Restart the affected pods, using the steps in the next section.

Managed service mesh

  1. Use the following command to locate the available release channels:

    kubectl -n istio-system get controlplanerevision

    The output is similar to the following:

    NAME                AGEasm-managed         6d7h

    In the output, select the value under theNAME column is theREVISION label that corresponds to the availablerelease channelfor the Cloud Service Mesh version. Apply this label to your namespaces, andremove theistio-injection label (if it exists).In the following command, replaceREVISION with therevision label you noted above, and replaceNAMESPACE with the name of the namespace where youwant to enable auto-injection:

    kubectl label namespaceNAMESPACE  istio-injection- istio.io/rev=REVISION --overwrite

    You can ignore the message"istio-injection not found" in theoutput. That means that the namespace didn't previously have theistio-injection label, which you should expect in newinstallations of Cloud Service Mesh or new deployments. Because auto-injectionbehavior is undefined when a namespace has both theistio-injectionand the revision label, allkubectl label commands in theCloud Service Mesh documentation explicitly ensure that only one is set.

  2. Restart the affected pods, using the steps in the next section.

  3. If you also deployed the optionalGoogle-managed data plane,annotate thedemo namespace as follows:

    kubectl annotate --overwrite namespaceYOUR_NAMESPACE \mesh.cloud.google.com/proxy='{"managed":"true"}'

Restart Pods to update sidecar proxies

Warning: Unless you have a load balancer or router setup forblue-green deployments,make sure you test restarting Pods in a staging environment to verify that yourservices can handle any potential traffic interruption.

With automatic sidecar injection, you can update the sidecars for existing Podswith a Pod restart:

How you restart Pods depends on if they were created as part of aDeployment.

  1. If you used a Deployment, restart the Deployment, which restarts all Podswith sidecars:

    kubectl rollout restart deployment -nYOUR_NAMESPACE

    If you didn't use a Deployment, delete the Pods, and they are automaticallyrecreated with sidecars:

    kubectl delete pod -nYOUR_NAMESPACE --all

  2. Check that all the Pods in the namespace have sidecars injected:

    kubectl get pod -nYOUR_NAMESPACE

    In the following example output from the previous command, notice that theREADY column indicates there are two containers for each of yourworkloads: the primary container and the container for the sidecar proxy.

    NAME                    READY   STATUS    RESTARTS   AGEYOUR_WORKLOAD           2/2     Running   0          20s...

What's next

Learn more about:

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.