# Linkerd Service Mesh Stack

> Lightweight service mesh with automatic mTLS, traffic splitting, and observability.

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: linkerd, viz, jaeger, prometheus, grafana
- Tags: linkerd, service-mesh, mtls, cncf, rust
- Source: https://docker.recipes/devops/linkerd-service-mesh

## Overview

Linkerd is an ultralight service mesh for Kubernetes and containerized applications, originally developed by Buoyant and now a CNCF graduated project. Built with Rust and Go, Linkerd provides automatic mutual TLS encryption, intelligent load balancing, and comprehensive observability for microservices communication without requiring code changes. This stack demonstrates Linkerd's core functionality using the popular Emojivoto demo application along with full observability infrastructure. The combination of Linkerd's control plane, visualization components, Jaeger for distributed tracing, Prometheus for metrics collection, and Grafana for dashboards creates a complete service mesh observability platform. This setup showcases how Linkerd automatically encrypts service-to-service communication, provides traffic metrics, and integrates with cloud-native observability tools. Platform engineers and SREs looking to understand service mesh concepts, evaluate Linkerd's capabilities, or prototype microservices observability solutions will find this stack invaluable for hands-on learning and proof-of-concept deployments.

## Features

- Automatic mutual TLS encryption between all meshed services without certificate management
- Linkerd's ultralight Rust-based proxy with minimal latency and resource overhead
- Real-time service topology visualization through Linkerd's web dashboard
- Traffic splitting and canary deployment capabilities via Linkerd's traffic policies
- Distributed tracing integration with Jaeger for request flow analysis
- Prometheus metrics collection for Linkerd proxy and application telemetry
- Pre-configured Grafana dashboards for service mesh observability
- Emojivoto demo application demonstrating real microservices mesh behavior

## Use cases

- Service mesh proof-of-concept for evaluating Linkerd versus Istio or Consul Connect
- Microservices security demonstration showing automatic mTLS encryption capabilities
- Developer training environment for learning service mesh concepts and observability
- CI/CD pipeline testing for applications destined for Linkerd-enabled Kubernetes clusters
- Performance benchmarking of service mesh overhead using realistic demo applications
- Distributed tracing workshop setup for understanding microservices request flows
- Local development environment mimicking production Linkerd mesh behavior

## Prerequisites

- Docker Engine 20.10+ with Docker Compose V2 for multi-container orchestration
- Minimum 4GB available RAM for Linkerd components, Prometheus, Grafana, and demo services
- Available ports 3000, 8080-8085, 9090, 9995, 14268, and 16686 for service access
- Basic understanding of service mesh concepts and microservices architecture
- Familiarity with Prometheus metrics and Grafana dashboard navigation
- Knowledge of distributed tracing concepts for effective Jaeger usage

## docker-compose.yml

```yaml
services:
  # Simulated Linkerd control plane
  linkerd-controller:
    image: ghcr.io/linkerd/controller:stable-2.14.0
    ports:
      - "8085:8085"
      - "9995:9995"
    networks:
      - linkerd_net

  # Linkerd Viz extension
  linkerd-viz:
    image: ghcr.io/linkerd/metrics-api:stable-2.14.0
    ports:
      - "8084:8084"
    networks:
      - linkerd_net

  # Web dashboard
  linkerd-web:
    image: ghcr.io/linkerd/web:stable-2.14.0
    ports:
      - "8080:8080"
    environment:
      - LINKERD_CONTROLLER_API_ADDR=linkerd-controller:8085
    depends_on:
      - linkerd-controller
    networks:
      - linkerd_net

  # Sample meshed service
  emojivoto-web:
    image: docker.l5d.io/buoyantio/emojivoto-web:v11
    ports:
      - "8081:8080"
    networks:
      - linkerd_net

  emojivoto-emoji-svc:
    image: docker.l5d.io/buoyantio/emojivoto-emoji-svc:v11
    networks:
      - linkerd_net

  emojivoto-voting-svc:
    image: docker.l5d.io/buoyantio/emojivoto-voting-svc:v11
    networks:
      - linkerd_net

  # Distributed tracing
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"
      - "14268:14268"
    networks:
      - linkerd_net

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

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

volumes:
  prometheus_data:
  grafana_data:

networks:
  linkerd_net:
```

## .env

```bash
# Linkerd Service Mesh
GRAFANA_PASSWORD=secure_grafana_password

# Dashboard at http://localhost:8080
# Emojivoto demo at http://localhost:8081
# Jaeger at http://localhost:16686
```

## Usage notes

- Dashboard at http://localhost:8080
- Emojivoto demo at http://localhost:8081
- Automatic mTLS between services
- Lightweight Rust-based proxy
- Demo setup - use Kubernetes for production

## Troubleshooting

- Linkerd web dashboard shows 'Controller API unavailable': Verify linkerd-controller container is running and port 8085 is accessible
- Emojivoto services not appearing in topology: Check that emojivoto containers are on the linkerd_net network and controllers are healthy
- Prometheus not scraping Linkerd metrics: Ensure prometheus.yml includes Linkerd endpoints and containers can communicate on linkerd_net
- Jaeger traces not appearing: Verify Linkerd proxy trace sampling configuration and Jaeger collector port 14268 connectivity
- Grafana dashboards showing no data: Confirm Prometheus data source configuration and verify Prometheus is successfully scraping targets
- High memory usage: Linkerd proxy and Prometheus can be memory-intensive; allocate at least 4GB total system memory for stable operation

