Chapter 2. Sidecar injection To use Istio's capabilities within a service mesh, each pod needs a sidecar proxy, configured and managed by the Istio control plane. 2.1. About sidecar injection Sidecar injection is enabled using labels at the namespace or pod level. These labels also indicate the specific control plane managing the proxy. When you apply a valid injection label to the pod template defined in a deployment, any new pods created by that deployment automatically receive a sidecar. Similarly, applying a pod injection label at the namespace level ensures any new pods in that namespace include a sidecar. Note Injection happens at pod creation through an admission controller, so changes appear on individual pods rather than the deployment resources. To confirm sidecar injection, check the pod details directly using oc describe , where you can see the injected Istio proxy container. 2.2. Identifying the revision name The label required to enable sidecar injection is determined by the specific control plane instance, known as a revision. Each revision is managed by an IstioRevision resource, which is automatically created and managed by the Istio resource, so manual creation or modification of IstioRevision resources is generally unnecessary. The naming of an IstioRevision depends on the spec.updateStrategy.type setting in the Istio resource. If set to InPlace , the revision shares the Istio resource name. If set to RevisionBased , the revision name follows the format <Istio resource name>-v<version> . Typically, each Istio resource corresponds to a single IstioRevision . However, during a revision-based upgrade, multiple IstioRevision resources may exist, each representing a distinct control plane instance. To see available revision names, use the following command: USD oc get istiorevisions You should see output similar to the following example: Example output NAME READY STATUS IN USE VERSION AGE my-mesh-v1-23-0 True Healthy False v1.23.0 114s 2.2.1. Enabling sidecar injection with default revision When the service mesh's IstioRevision name is default , it's possible to use the following labels on a namespace or a pod to enable sidecar injection: Resource Label Enabled value Disabled value Namespace istio-injection enabled disabled Pod sidecar.istio.io/inject true false Note You can also enable injection by setting the istio.io/rev: default label in the namespace or pod. 2.2.2. Enabling sidecar injection with other revisions When the IstioRevision name is not default , use the specific IstioRevision name with the istio.io/rev label to map the pod to the desired control plane and enable sidecar injection. To enable injection, set the istio.io/rev: default label in either the namespace or the pod, as adding it to both is not required. For example, with the revision shown above, the following labels would enable sidecar injection: Resource Enabled label Disabled label Namespace istio.io/rev=my-mesh-v1-23-0 istio-injection=disabled Pod istio.io/rev=my-mesh-v1-23-0 sidecar.istio.io/inject="false" Note When both istio-injection and istio.io/rev labels are applied, the istio-injection label takes precedence and treats the namespace as part of the default revision. 2.3. Enabling sidecar injection To demonstrate different approaches for configuring sidecar injection, the following procedures use the Bookinfo application. Prerequisites You have installed the Red Hat OpenShift Service Mesh Operator, created an Istio resource, and the Operator has deployed Istio. You have created the IstioCNI resource, and the Operator has deployed the necessary IstioCNI pods. You have created the namespaces that are to be part of the mesh, and they are discoverable by the Istio control plane. Optional: You have deployed the workloads to be included in the mesh. In the following examples, the Bookinfo has been deployed to the bookinfo namespace, but sidecar injection (step 5) has not been configured. 2.3.1. Enabling sidecar injection with namespace labels In this example, all workloads within a namespace receive a sidecar proxy injection, making it the best approach when the majority of workloads in the namespace should be included in the mesh. Procedure Verify the revision name of the Istio control plane using the following command: USD oc get istiorevisions You should see output similar to the following example: Example output NAME TYPE READY STATUS IN USE VERSION AGE default Local True Healthy False v1.23.0 4m57s Since the revision name is default, you can use the default injection labels without referencing the exact revision name. Verify that workloads already running in the desired namespace show 1/1 containers as READY by using the following command. This confirms that the pods are running without sidecars. USD oc get pods -n bookinfo You should see output similar to the following example: Example output NAME READY STATUS RESTARTS AGE details-v1-65cfcf56f9-gm6v7 1/1 Running 0 4m55s productpage-v1-d5789fdfb-8x6bk 1/1 Running 0 4m53s ratings-v1-7c9bd4b87f-6v7hg 1/1 Running 0 4m55s reviews-v1-6584ddcf65-6wqtw 1/1 Running 0 4m54s reviews-v2-6f85cb9b7c-w9l8s 1/1 Running 0 4m54s reviews-v3-6f5b775685-mg5n6 1/1 Running 0 4m54s To apply the injection label to the bookinfo namespace, run the following command at the CLI: USD oc label namespace bookinfo istio-injection=enabled namespace/bookinfo labeled To ensure sidecar injection is applied, redeploy the existing workloads in the bookinfo namespace. Use the following command to perform a rolling update of all workloads: USD oc -n bookinfo rollout restart deployments Verification Verify the rollout by checking that the new pods display 2/2 containers as READY , confirming successful sidecar injection by running the following command: USD oc get pods -n bookinfo You should see output similar to the following example: Example output NAME READY STATUS RESTARTS AGE details-v1-7745f84ff-bpf8f 2/2 Running 0 55s productpage-v1-54f48db985-gd5q9 2/2 Running 0 55s ratings-v1-5d645c985f-xsw7p 2/2 Running 0 55s reviews-v1-bd5f54b8c-zns4v 2/2 Running 0 55s reviews-v2-5d7b9dbf97-wbpjr 2/2 Running 0 55s reviews-v3-5fccc48c8c-bjktn 2/2 Running 0 55sz 2.3.2. Exclude a workload from the mesh You can exclude specific workloads from sidecar injection within a namespace where injection is enabled for all workloads. Note This example is for demonstration purposes only. The bookinfo application requires all workloads to be part of the mesh for proper functionality. Procedure Open the application's Deployment resource in an editor. In this case, exclude the ratings-v1 service. Modify the spec.template.metadata.labels section of your Deployment resource to include the label sidecar.istio.io/inject: false to disable sidecar injection. kind: Deployment apiVersion: apps/v1 metadata: name: ratings-v1 namespace: bookinfo labels: app: ratings version: v1 spec: template: metadata: labels: sidecar.istio.io/inject: 'false' Note Adding the label to the top-level labels section of the Deployment does not affect sidecar injection. Updating the deployment triggers a rollout, creating a new ReplicaSet with updated pod(s). Verification Verify that the updated pod(s) do not contain a sidecar container and show 1/1 containers as Running by running the following command: USD oc get pods -n bookinfo You should see output similar to the following example: Example output NAME READY STATUS RESTARTS AGE details-v1-6bc7b69776-7f6wz 2/2 Running 0 29m productpage-v1-54f48db985-gd5q9 2/2 Running 0 29m ratings-v1-5d645c985f-xsw7p 1/1 Running 0 7s reviews-v1-bd5f54b8c-zns4v 2/2 Running 0 29m reviews-v2-5d7b9dbf97-wbpjr 2/2 Running 0 29m reviews-v3-5fccc48c8c-bjktn 2/2 Running 0 29m 2.3.3. Enabling sidecar injection with pod labels This approach allows you to include individual workloads for sidecar injection instead of applying it to all workloads within a namespace, making it ideal for scenarios where only a few workloads need to be part of a service mesh. This example also demonstrates the use of a revision label for sidecar injection, where the Istio resource is created with the name my-mesh . A unique Istio resource name is required when multiple Istio control planes are present in the same cluster or during a revision-based control plane upgrade. Procedure Verify the revision name of the Istio control plane by running the following command: USD oc get istiorevisions You should see output similar to the following example: Example output NAME TYPE READY STATUS IN USE VERSION AGE my-mesh Local True Healthy False v1.23.0 47s Since the revision name is my-mesh , use the revision label istio.io/rev=my-mesh to enable sidecar injection. Verify that workloads already running show 1/1 containers as READY , indicating that the pods are running without sidecars by running the following command: USD oc get pods -n bookinfo You should see output similar to the following example: Example output NAME READY STATUS RESTARTS AGE details-v1-65cfcf56f9-gm6v7 1/1 Running 0 4m55s productpage-v1-d5789fdfb-8x6bk 1/1 Running 0 4m53s ratings-v1-7c9bd4b87f-6v7hg 1/1 Running 0 4m55s reviews-v1-6584ddcf65-6wqtw 1/1 Running 0 4m54s reviews-v2-6f85cb9b7c-w9l8s 1/1 Running 0 4m54s reviews-v3-6f5b775685-mg5n6 1/1 Running 0 4m54s Open the application's Deployment resource in an editor. In this case, update the ratings-v1 service. Update the spec.template.metadata.labels section of your Deployment to include the appropriate pod injection or revision label. In this case, istio.io/rev: my-mesh : kind: Deployment apiVersion: apps/v1 metadata: name: ratings-v1 namespace: bookinfo labels: app: ratings version: v1 spec: template: metadata: labels: istio.io/rev: my-mesh Note Adding the label to the Deployment's top-level `labels section does not impact sidecar injection. Updating the deployment triggers a rollout, creating a new ReplicaSet with the updated pod(s). Verification Verify that only the ratings-v1 pod now shows 2/2 containers READY , indicating that the sidecar has been successfully injected by running the following command: USD oc get pods -n bookinfo You should see output similar to the following example: Example output NAME READY STATUS RESTARTS AGE details-v1-559cd49f6c-b89hw 1/1 Running 0 42m productpage-v1-5f48cdcb85-8ppz5 1/1 Running 0 42m ratings-v1-848bf79888-krdch 2/2 Running 0 9s reviews-v1-6b7444ffbd-7m5wp 1/1 Running 0 42m reviews-v2-67876d7b7-9nmw5 1/1 Running 0 42m reviews-v3-84b55b667c-x5t8s 1/1 Running 0 42m Repeat for other workloads that you wish to include in the mesh. 2.4. Additional resources About admission controllers Istio sidecar injection problems Bookinfo application Scoping service mesh with discovery selectors

Commands:
oc get istiorevisions
NAME READY STATUS IN USE VERSION AGE my-mesh-v1-23-0 True Healthy False v1.23.0 114s
oc get istiorevisions
NAME TYPE READY STATUS IN USE VERSION AGE default Local True Healthy False v1.23.0 4m57s
oc get pods -n bookinfo
NAME READY STATUS RESTARTS AGE details-v1-65cfcf56f9-gm6v7 1/1 Running 0 4m55s productpage-v1-d5789fdfb-8x6bk 1/1 Running 0 4m53s ratings-v1-7c9bd4b87f-6v7hg 1/1 Running 0 4m55s reviews-v1-6584ddcf65-6wqtw 1/1 Running 0 4m54s reviews-v2-6f85cb9b7c-w9l8s 1/1 Running 0 4m54s reviews-v3-6f5b775685-mg5n6 1/1 Running 0 4m54s
oc label namespace bookinfo istio-injection=enabled namespace/bookinfo labeled
oc -n bookinfo rollout restart deployments
oc get pods -n bookinfo
NAME READY STATUS RESTARTS AGE details-v1-7745f84ff-bpf8f 2/2 Running 0 55s productpage-v1-54f48db985-gd5q9 2/2 Running 0 55s ratings-v1-5d645c985f-xsw7p 2/2 Running 0 55s reviews-v1-bd5f54b8c-zns4v 2/2 Running 0 55s reviews-v2-5d7b9dbf97-wbpjr 2/2 Running 0 55s reviews-v3-5fccc48c8c-bjktn 2/2 Running 0 55sz
kind: Deployment apiVersion: apps/v1 metadata: name: ratings-v1 namespace: bookinfo labels: app: ratings version: v1 spec: template: metadata: labels: sidecar.istio.io/inject: 'false'
oc get pods -n bookinfo
NAME READY STATUS RESTARTS AGE details-v1-6bc7b69776-7f6wz 2/2 Running 0 29m productpage-v1-54f48db985-gd5q9 2/2 Running 0 29m ratings-v1-5d645c985f-xsw7p 1/1 Running 0 7s reviews-v1-bd5f54b8c-zns4v 2/2 Running 0 29m reviews-v2-5d7b9dbf97-wbpjr 2/2 Running 0 29m reviews-v3-5fccc48c8c-bjktn 2/2 Running 0 29m
oc get istiorevisions
NAME TYPE READY STATUS IN USE VERSION AGE my-mesh Local True Healthy False v1.23.0 47s
oc get pods -n bookinfo
NAME READY STATUS RESTARTS AGE details-v1-65cfcf56f9-gm6v7 1/1 Running 0 4m55s productpage-v1-d5789fdfb-8x6bk 1/1 Running 0 4m53s ratings-v1-7c9bd4b87f-6v7hg 1/1 Running 0 4m55s reviews-v1-6584ddcf65-6wqtw 1/1 Running 0 4m54s reviews-v2-6f85cb9b7c-w9l8s 1/1 Running 0 4m54s reviews-v3-6f5b775685-mg5n6 1/1 Running 0 4m54s
kind: Deployment apiVersion: apps/v1 metadata: name: ratings-v1 namespace: bookinfo labels: app: ratings version: v1 spec: template: metadata: labels: istio.io/rev: my-mesh
oc get pods -n bookinfo
NAME READY STATUS RESTARTS AGE details-v1-559cd49f6c-b89hw 1/1 Running 0 42m productpage-v1-5f48cdcb85-8ppz5 1/1 Running 0 42m ratings-v1-848bf79888-krdch 2/2 Running 0 9s reviews-v1-6b7444ffbd-7m5wp 1/1 Running 0 42m reviews-v2-67876d7b7-9nmw5 1/1 Running 0 42m reviews-v3-84b55b667c-x5t8s 1/1 Running 0 42m