# Istio Service Mesh Demo Stack

> Service mesh with sidecar injection, traffic management, and observability.

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: istiod, envoy, kiali, jaeger, prometheus, grafana
- Tags: istio, service-mesh, kubernetes, envoy, traffic-management
- Source: https://docker.recipes/devops/istio-service-mesh

## Overview

Istiod is Istio's unified control plane that manages the entire service mesh infrastructure, handling configuration distribution, certificate management, and proxy lifecycle. This stack demonstrates core service mesh capabilities by combining Istiod with Envoy sidecars, Kiali for topology visualization, Jaeger for distributed tracing, and Prometheus/Grafana for metrics collection and monitoring. The configuration creates two sample microservices with dedicated Envoy proxy sidecars that intercept and manage all network traffic.

This demonstration environment showcases how Istio implements the sidecar proxy pattern, where each service communicates through its dedicated Envoy proxy rather than directly with other services. The Envoy proxies collect telemetry data, enforce security policies, and enable advanced traffic management features like circuit breaking, load balancing, and canary deployments. Jaeger captures distributed traces across service boundaries, while Kiali provides a visual representation of service dependencies and traffic flows.

Development teams adopting microservices architectures will find this stack valuable for understanding service mesh concepts before implementing Istio in Kubernetes clusters. Platform engineers can use this environment to prototype traffic management policies, test observability configurations, and demonstrate service mesh benefits to stakeholders. The stack serves as an educational tool that removes Kubernetes complexity while preserving core Istio functionality.

## Features

- Istiod control plane managing Envoy proxy configurations and certificate distribution
- Sidecar proxy pattern with dedicated Envoy containers for each microservice
- Kiali service mesh topology visualization with traffic flow indicators
- Jaeger distributed tracing with OpenTelemetry protocol support
- Prometheus metrics collection from Envoy proxies and Istio components
- Grafana dashboards for service mesh observability and performance monitoring
- Protocol sniffing for automatic traffic detection and routing
- mTLS certificate management through Istiod's built-in certificate authority

## Use cases

- Learning service mesh concepts before deploying Istio in production Kubernetes clusters
- Prototyping traffic management policies and observability configurations
- Demonstrating microservices communication patterns to development teams
- Testing distributed tracing implementation across multiple service boundaries
- Evaluating service mesh overhead and performance impact on application latency
- Training platform engineers on Envoy proxy configuration and management
- Developing custom Grafana dashboards for service mesh monitoring

## Prerequisites

- Docker Engine 20.10+ with Docker Compose v2 support
- 8GB RAM minimum (2GB for Jaeger, 1GB each for Prometheus/Grafana, 4GB for remaining components)
- Understanding of microservices architecture and inter-service communication
- Basic knowledge of load balancing, proxies, and network traffic management
- Familiarity with observability concepts including metrics, traces, and logs
- Available ports: 3000, 8081-8082, 9090, 15010-15014, 16686, 20001

## docker-compose.yml

```yaml
services:
  # Simulated Istio control plane
  istiod:
    image: istio/pilot:latest
    ports:
      - "15010:15010"
      - "15012:15012"
      - "15014:15014"
    environment:
      - PILOT_ENABLE_PROTOCOL_SNIFFING_FOR_OUTBOUND=true
      - PILOT_ENABLE_PROTOCOL_SNIFFING_FOR_INBOUND=true
    networks:
      - istio_net

  # Sample microservice with Envoy sidecar
  service-a:
    image: nginx:alpine
    networks:
      - istio_net

  service-a-envoy:
    image: envoyproxy/envoy:v1.28-latest
    volumes:
      - ./envoy-service-a.yaml:/etc/envoy/envoy.yaml
    ports:
      - "8081:8080"
    depends_on:
      - service-a
    networks:
      - istio_net

  service-b:
    image: nginx:alpine
    networks:
      - istio_net

  service-b-envoy:
    image: envoyproxy/envoy:v1.28-latest
    volumes:
      - ./envoy-service-b.yaml:/etc/envoy/envoy.yaml
    ports:
      - "8082:8080"
    depends_on:
      - service-b
    networks:
      - istio_net

  # Kiali service mesh visualization
  kiali:
    image: quay.io/kiali/kiali:latest
    ports:
      - "20001:20001"
    environment:
      - AUTH_STRATEGY=anonymous
    networks:
      - istio_net

  # Distributed tracing
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"
      - "14268:14268"
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    networks:
      - istio_net

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    networks:
      - istio_net

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    volumes:
      - grafana_data:/var/lib/grafana
    networks:
      - istio_net

volumes:
  prometheus_data:
  grafana_data:

networks:
  istio_net:
```

## .env

```bash
# Istio Service Mesh Demo
GRAFANA_PASSWORD=secure_grafana_password

# Kiali at http://localhost:20001
# Jaeger at http://localhost:16686
# Services at http://localhost:8081, 8082
```

## Usage notes

- Kiali mesh visualization at http://localhost:20001
- Jaeger tracing at http://localhost:16686
- Envoy sidecars handle traffic
- Demo setup - use Kubernetes for production
- Traffic management via Envoy configs

## Troubleshooting

- Kiali shows empty topology: Verify Envoy proxies are properly configured and generating telemetry data to Prometheus
- Jaeger traces not appearing: Check COLLECTOR_OTLP_ENABLED environment variable and ensure Envoy is configured to send traces to port 14268
- Envoy proxy startup failures: Validate envoy.yaml configuration files exist in working directory with correct cluster and listener definitions
- Istiod connection errors: Ensure pilot ports 15010-15014 are accessible and PILOT_ENABLE_PROTOCOL_SNIFFING variables are set
- Grafana dashboard shows no data: Verify Prometheus is scraping Envoy admin endpoints and Grafana data source points to prometheus:9090
- Service communication timeouts: Check Envoy cluster configurations match actual service names and ports in Docker network

