Guide to installing Istio with istioctl, deploying Bookinfo, and demonstrating automatic namespace and manual per-workload sidecar injection in Kubernetes
In this lesson you’ll install Istio into an existing Kubernetes cluster, deploy the Bookinfo sample application, and demonstrate both automatic namespace injection and manual (per-workload) injection of the Istio sidecar proxy.This guide follows a step-by-step flow:
Deploy the Bookinfo sample (pre-Istio).
Install istioctl.
Install the Istio control plane (demo profile).
Enable automatic sidecar injection for a namespace.
Manually inject the sidecar into an individual workload in an unlabeled namespace.
Prerequisites
Requirement
Why it matters
A running Kubernetes cluster with kubectl configured
You need cluster access to deploy resources and inspect pods
Cluster privileges to install cluster components and label namespaces
Installing Istio and modifying namespace labels requires sufficient RBAC permissions
Optional: Familiarity with Kubernetes kubectl basics
4) Enable automatic sidecar injection for a namespace
Use istioctl analyze to surface common configuration hints. For example, analyze the default namespace:
istioctl analyze -n default
If the namespace is not enabled for automatic injection, you may see an info message such as:
Info [IST0102] (Namespace default) The namespace is not enabled for Istio injection. Run 'kubectl label namespace default istio-injection=enabled' to enable it, or 'kubectl label namespace default istio-injection=disabled' to explicitly mark it as not needing injection.
Enable automatic sidecar injection for the namespace (for this demo we use default):
Important: labeling a namespace does not restart existing pods. To apply injection to running workloads you must restart them (or delete/recreate them). Restart one or more deployments so the sidecar is injected:
5) Manual (per-workload) injection into an unlabeled namespace
Automatic namespace injection is convenient, but there are cases where you want to inject only specific workloads within a namespace. Manual injection—by annotating the pod or deployment manifest—lets you do that without labeling the namespace.Create a new namespace named db (do not label it for injection):
kubectl create ns dbkubectl get ns --show-labels
Run a simple Redis pod without injection:
kubectl run redis-no-proxy --image=redis -n dbkubectl get pods -n db
You will see redis-no-proxy running with only one container (no istio-proxy).Analyze the namespace to confirm it’s not enabled for injection:
istioctl analyze -n db
You should receive the same IST0102 hint indicating the namespace is not enabled for injection.To inject the sidecar for a single workload without labeling the namespace, add the injector annotation sidecar.istio.io/inject: "true" to that pod or deployment. A simple way is to create the pod manifest locally and apply it.Create a pod manifest using a dry-run:
kubectl run redis-istio-proxy --image=redis -n db --dry-run=client -o yaml > pod.yaml
Edit pod.yaml and add the injector annotation under metadata, for example:
metadata: name: redis-istio-proxy namespace: db annotations: sidecar.istio.io/inject: "true"
Apply the manifest:
kubectl apply -f pod.yaml
After applying, check pods in db:
kubectl get pods -n db
You should see two pods:
redis-no-proxy with 1/1 (application container only)
redis-istio-proxy with 2/2 (application container + istio-proxy)
Describe the injected pod to inspect the proxy container and Istio environment variables:
kubectl describe pod redis-istio-proxy -n db
Excerpt showing both containers and Istio metadata:
This demonstrates per-workload injection via annotation, without labeling the entire namespace.
Automatic namespace injection (labeling the namespace) is the simpler and recommended approach for most environments. Use the annotation sidecar.istio.io/inject: "true" when you need to inject only specific workloads in an otherwise unlabeled namespace. Note: some legacy helpers such as istioctl kube-inject have been deprecated or removed in recent Istio releases, so prefer annotation-based injection or istioctl-based installation workflows.
Installed istioctl (client v1.26.3) and the Istio control plane using the demo profile.
Deployed the Bookinfo sample before installing Istio to illustrate pre- and post-injection behavior.
Enabled automatic sidecar injection by labeling a namespace, then restarted specific workloads to have the istio-proxy injected.
Demonstrated manual, per-workload injection by annotating a pod manifest so the admission webhook would add the sidecar in an otherwise unlabeled namespace.
Keep both automatic and manual injection workflows in mind — they are commonly tested and useful in real-world cluster operations and troubleshooting.Links and references
