Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Sidecar injection

Sidecar proxies are deployed into each application pod to intercept network traffic and enable service mesh features like security, observability, and traffic management.

3.1. About sidecar injection
Copy link

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.

3.2. Identifying the revision name
Copy link

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: 

$ 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

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:

Expand
ResourceLabelEnabled valueDisabled 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.

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:

Expand
ResourceEnabled labelDisabled 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.

3.3. Enabling sidecar injection
Copy link

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. For more information, see "Deploying the Bookinfo application".

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

  1. Verify the revision name of the Istio control plane using the following command: 

    $ 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.

  2. 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. 

    $ 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

  3. To apply the injection label to the 

    bookinfo
    namespace, run the following command at the CLI: 

    $ oc label namespace bookinfo istio-injection=enabled
namespace/bookinfo labeled

  4. 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: 

    $ oc -n bookinfo rollout restart deployments

Verification

  1. Verify the rollout by checking that the new pods display 

    2/2
    containers as 
    READY
    , confirming successful sidecar injection by running the following command: 

    $ 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          55s

3.3.2. Exclude a workload from the mesh
Copy link

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

  1. Open the application’s 
    Deployment
    resource in an editor. In this case, exclude the 
    ratings-v1
    service.

  2. 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

  1. Verify that the updated pod(s) do not contain a sidecar container and show 

    1/1
    containers as 
    Running
    by running the following command: 

    $ 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

3.3.3. Enabling sidecar injection with pod labels
Copy link

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

  1. Verify the revision name of the Istio control plane by running the following command: 

    $ 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.

  2. Verify that workloads already running show 

    1/1
    containers as 
    READY
    , indicating that the pods are running without sidecars by running the following command: 

    $ 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

  3. Open the application’s 
    Deployment
    resource in an editor. In this case, update the 
    ratings-v1
    service.

  4. 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 top-level 

    labels
    section of the 
    Deployment
    resource does not impact sidecar injection.

    Updating the deployment triggers a rollout, creating a new ReplicaSet with the updated pod(s).

Verification

  1. 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: 

    $ 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

  2. Repeat for other workloads that you wish to include in the mesh.

To use the 

istio-injection=enabled
label when your revision name is not 
default
, you must create an 
IstioRevisionTag
resource with the name 
default
that references your 
Istio
resource.

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 in "Deploying the Bookinfo application" procedure) has not been configured. For more information, see "Deploying the Bookinfo application".

Procedure

  1. Find the name of your 

    Istio
    resource by running the following command: 

    $ oc get istio

    Example output

    NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
default   1           1       1        default-v1-24-3   Healthy   v1.24.3   11s

    In this example, the 

    Istio
    resource has the name 
    default
    , but the underlying revision is called 
    default-v1-24-3
    .

  2. Create the 

    IstioRevisionTag
    resource in a YAML file:

    Example IstioRevistionTag resource YAML file

    apiVersion: sailoperator.io/v1
kind: IstioRevisionTag
metadata:
  name: default
spec:
  targetRef:
    kind: Istio
    name: default

  3. Apply the 

    IstioRevisionTag
    resource by running the following command: 

    $ oc apply -f istioRevisionTag.yaml

  4. Verify that the 

    IstioRevisionTag
    resource has been created successfully by running the following command: 

    $ oc get istiorevisiontags.sailoperator.io

    Example output

    NAME      STATUS    IN USE   REVISION          AGE
default   Healthy   True     default-v1-24-3   4m23s

    In this example, the new tag is referencing your active revision, 

    default-v1-24-3
    . Now you can use the 
    istio-injection=enabled
    label as if your revision was called 
    default
    .

  5. Confirm that the pods are running without sidecars by running the following command. Any workloads that are already running in the desired namespace should show 

    1/1
    containers in the 
    READY
    column. 

    $ oc get pods -n bookinfo

    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

  6. Apply the injection label to the 

    bookinfo
    namespace by running the following command: 

    $ oc label namespace bookinfo istio-injection=enabled \
namespace/bookinfo labeled

  7. To ensure sidecar injection is applied, redeploy the workloads in the 

    bookinfo
    namespace by running the following command: 

    $ oc -n bookinfo rollout restart deployments

Verification

  1. Verify the rollout by running the following command and confirming that the new pods display 

    2/2
    containers in the 
    READY
    column: 

    $ oc get pods -n bookinfo

    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          55s

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top