Skip to content

Service Mesh Cheat Sheet

Name origin: Istio is Greek for "sail" — continuing the Kubernetes nautical naming theme. Envoy (the sidecar proxy) means "messenger" or "representative." The service mesh concept was popularized by Buoyant's Linkerd in 2016, but Istio (Google/IBM/Lyft, 2017) became the most widely adopted. The "sidecar" pattern injects a proxy container alongside every application container — all traffic flows through the proxy, enabling mTLS, retries, and observability without changing application code.

Istio Architecture

┌─────────────────────────────────────────┐
│              Control Plane              │
│  ┌─────────┐ ┌────────┐ ┌───────────┐  │
│  │  Istiod  │ = Pilot + Citadel + Galley│
│  └────┬────┘ └────────┘ └───────────┘  │
│       │ xDS API (config push)           │
├───────┼─────────────────────────────────┤
│       ▼         Data Plane              │
│  ┌─────────┐    ┌─────────┐            │
│  │ Envoy   │◄──►│ Envoy   │            │
│  │ Sidecar │    │ Sidecar │            │
│  └────┬────┘    └────┬────┘            │
│       │              │                  │
│  ┌────▼────┐    ┌────▼────┐            │
│  │ App A   │    │ App B   │            │
│  └─────────┘    └─────────┘            │
└─────────────────────────────────────────┘

Key Commands

# Install Istio
istioctl install --set profile=demo

# Enable sidecar injection
kubectl label namespace default istio-injection=enabled

# Check injection status
kubectl get namespace -L istio-injection

# Analyze configuration issues
istioctl analyze -n <namespace>

# Check proxy status
istioctl proxy-status

# View proxy config for a pod
istioctl proxy-config routes <pod-name>

# Debug envoy listeners/clusters/endpoints
istioctl proxy-config listeners <pod>
istioctl proxy-config clusters <pod>
istioctl proxy-config endpoints <pod>

Traffic Management

# VirtualService — route traffic
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: my-app
spec:
  hosts: ["my-app"]
  http:
  - match:
    - headers:
        x-canary: { exact: "true" }
    route:
    - destination:
        host: my-app
        subset: canary
  - route:
    - destination:
        host: my-app
        subset: stable
      weight: 90
    - destination:
        host: my-app
        subset: canary
      weight: 10

# DestinationRule — define subsets + policies
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: my-app
spec:
  host: my-app
  trafficPolicy:
    connectionPool:
      tcp: { maxConnections: 100 }
      http: { h2UpgradePolicy: DEFAULT }
    outlierDetection:
      consecutive5xxErrors: 3
      interval: 30s
      baseEjectionTime: 30s
  subsets:
  - name: stable
    labels: { version: v1 }
  - name: canary
    labels: { version: v2 }

Debug clue: When debugging Istio routing issues, istioctl proxy-config is your X-ray. The three subcommands to remember: listeners (what ports is the proxy accepting?), clusters (what backends does it know about?), routes (what rules map requests to backends?). If traffic is not flowing, one of these three is misconfigured.

mTLS Configuration

# Strict mTLS for namespace
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
  namespace: production
spec:
  mtls:
    mode: STRICT  # STRICT | PERMISSIVE | DISABLE

Fault Injection (Testing)

http:
- fault:
    delay:
      percentage: { value: 10 }
      fixedDelay: 5s
    abort:
      percentage: { value: 5 }
      httpStatus: 503
  route:
  - destination: { host: my-app }

Port Naming Convention

Istio requires protocol-prefixed port names: - http-web, http-api — HTTP traffic - grpc-backend — gRPC traffic - tcp-db — TCP traffic - https-secure — HTTPS traffic

Unnamed ports default to TCP (no L7 features).

Common Gotchas

Issue Symptom Fix
Port not named 503 errors, no L7 routing Add http- prefix to port name
Strict mTLS + non-mesh client Connection refused Use PERMISSIVE mode or mesh the client
Missing sidecar No mesh features Check namespace label
Init container needs network Init fails with connection errors Use holdApplicationUntilProxyStarts: true