Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

Sidecar Injection and Your First Mesh App

Enable automatic sidecar injection with a namespace label, deploy a small shop app, confirm the istio-proxy container, and fix common injection problems.

Installing Istio does nothing to your applications by itself. A pod joins the mesh only when it has an Envoy sidecar, and that sidecar is added when the pod is created. This lesson shows the mechanism, deploys a small three-service shop, and teaches the checks that tell you whether a pod really is in the mesh.

Automatic injection

istiod registers a Kubernetes mutating admission webhook. When the API server receives a new pod in a namespace that opts in, it sends the pod spec to istiod, which returns it with extra containers added. Opt in with a label:

Terminal
kubectl create namespace shop
kubectl label namespace shop istio-injection=enabled

Only pods created after the label exists get a sidecar. Running pods must be restarted:

Terminal
kubectl rollout restart deployment -n shop

You can opt a single pod out by adding the annotation sidecar.istio.io/inject: "false" to its pod template, or opt a single pod in, in a namespace that is not labelled, with the label sidecar.istio.io/inject: "true".

flowchart LR
    U["kubectl apply"] --> A["API server"]
    A --> W["Mutating webhook (istiod)"]
    W --> A
    A --> N["Pod with app + istio-proxy"]

The webhook edits the pod before it is stored, so the sidecar looks like part of your own Deployment.

Revisions change the label: with a revisioned control plane you use istio.io/rev=<revision> instead of istio-injection. Revisions make safe control plane upgrades possible later in the track.

The shop application

Three services: web calls catalog, which calls inventory. A minimal manifest for one of them:

YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: catalog
  namespace: shop
spec:
  replicas: 2
  selector:
    matchLabels: { app: catalog, version: v1 }
  template:
    metadata:
      labels: { app: catalog, version: v1 }
    spec:
      containers:
        - name: catalog
          image: registry.example.com/shop/catalog:1.0
          ports:
            - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: catalog
  namespace: shop
spec:
  selector: { app: catalog }
  ports:
    - name: http
      port: 80
      targetPort: 8080

Two Istio conventions are already visible:

  • Labels app and version. Istio uses them for telemetry and for splitting traffic by version.
  • Port names start with the protocol (http, grpc, tcp...). Istio guesses a protocol from the name (or from appProtocol); a port named just web may be treated as opaque TCP and lose HTTP features. This is the most common beginner mistake.

Verify the sidecar

Terminal
kubectl get pods -n shop

The READY column now shows 2/2 (application + istio-proxy) instead of 1/1. List container names:

Terminal
kubectl get pod -n shop -l app=catalog \
  -o jsonpath='{.items[0].spec.containers[*].name}'

Expect your container name plus istio-proxy. Pods may also show an init container, istio-init, unless the CNI plugin is used.

Next, ask Istio about the proxies:

Terminal
istioctl proxy-status
istioctl analyze -n shop

proxy-status lists each connected proxy and whether its config is synced. analyze checks the namespace and its resources for common errors such as a missing injection label or a bad port name, and prints warnings with codes (for example IST0108 for an unknown resource).

Common problems

Symptom Likely cause
Pods show 1/1 Label missing, or pods created before labelling: restart them
Pod stuck Init:0/1 istio-init cannot set iptables (missing NET_ADMIN): use the CNI plugin
App fails at start but works later App calls the network before the proxy is ready: holdApplicationUntilProxyStarts
Jobs never complete The sidecar keeps running after the job container exits: use native sidecars or tell the proxy to quit
host-network pods ignored Sidecars are not injected for hostNetwork: true pods

A stand-in injector

This stand-in mimics the webhook's decision and edit on a Python dictionary. It shows that injection is a pure transformation of the pod spec; it is not Istio's real template.

Python Stand-in: a mutating webhook

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: a port-name lint

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does Istio add the sidecar to a pod?

    istiod's webhook modifies the pod before it is stored, adding istio-proxy (and usually istio-init).
  2. 2. You labelled the namespace, but existing pods show 1/1. What now?

    Injection happens at pod creation; running pods need a restart, for example kubectl rollout restart.
  3. 3. Why should a Service port be named http rather than web?

    Without a protocol prefix or appProtocol, HTTP routing and metrics features are not applied.
  4. 4. Which pods are never injected?

    Host-network pods share the node's network namespace, so redirection rules would be unsafe and are skipped.

Summary

  • Label a namespace with istio-injection=enabled (or istio.io/rev=...), then restart pods.
  • The webhook adds istio-proxy; READY 2/2 is the first sign.
  • Name ports with a protocol prefix, and label workloads with app and version.
  • istioctl proxy-status and istioctl analyze are your first diagnostics.
  • Opt out per pod with sidecar.istio.io/inject: "false".

Next: The Problems a Mesh Solves