# Envoy Proxy

> Modern edge and service proxy designed for cloud-native applications.

- Category: Web Servers & Reverse Proxies
- Difficulty: advanced
- Components: envoy
- Tags: envoy, service-mesh, proxy, cloud-native
- Source: https://docker.recipes/web-servers/envoy-proxy

## Overview

Envoy Proxy is a high-performance C++ distributed proxy designed for single services and applications, as well as a communication bus and universal data plane for large microservice service mesh architectures. Originally built at Lyft to handle their massive scale requirements, Envoy has become the foundation for numerous service mesh implementations including Istio, Ambassador, and Gloo. It excels at L3/L4 filtering, HTTP L7 filtering, HTTP/2 first design, and gRPC proxying while providing advanced load balancing, health checking, rate limiting, circuit breaking, and observability features.

This Envoy deployment creates a powerful edge proxy capable of handling ingress traffic, performing advanced routing decisions, and providing comprehensive observability through its built-in admin interface. The configuration mounts a custom envoy.yaml file that defines listeners for HTTP/HTTPS traffic on ports 80 and 443, while exposing the administrative interface on port 9901 for real-time monitoring and configuration inspection. Envoy's hot reload capability allows configuration changes without dropping connections, making it ideal for production environments requiring zero-downtime updates.

This setup is perfect for platform engineers implementing cloud-native architectures, DevOps teams managing microservice communications, and organizations requiring enterprise-grade traffic management with detailed observability. Envoy's extensive filter ecosystem and xDS API compatibility make it an excellent choice for teams building service meshes or needing advanced proxy features like mutual TLS, JWT validation, rate limiting, and sophisticated routing based on headers, paths, or weighted distributions.

## Features

- Advanced HTTP/2 and gRPC proxying with connection multiplexing and flow control
- Built-in circuit breaker with configurable failure thresholds and automatic recovery
- Comprehensive health checking with active and passive failure detection
- Real-time metrics and tracing integration with Prometheus, Jaeger, and Zipkin
- Hot configuration reload via SIGHUP signal without dropping existing connections
- Sophisticated load balancing algorithms including consistent hashing and zone-aware routing
- Web Assembly (WASM) filter support for custom request/response processing
- Automatic retry logic with exponential backoff and jitter configuration

## Use cases

- API gateway for microservices requiring advanced routing and traffic splitting
- Edge proxy for Kubernetes clusters handling ingress traffic and SSL termination
- Service mesh data plane component for inter-service communication
- Load balancer replacement requiring health checking and circuit breaking
- gRPC proxy for handling protocol translation and connection pooling
- Rate limiting proxy for protecting backend services from traffic spikes
- Observability gateway collecting metrics and traces from distributed systems

## Prerequisites

- Docker Engine 20.10+ and Docker Compose V2 for container orchestration
- Minimum 512MB RAM allocation for Envoy proxy operations and connection handling
- Valid envoy.yaml configuration file with listeners, clusters, and route definitions
- Available ports 80, 443, and 9901 for HTTP, HTTPS, and admin interface access
- Understanding of Envoy configuration concepts including listeners, filters, and clusters
- SSL certificates if configuring HTTPS termination in the Envoy configuration

## docker-compose.yml

```yaml
services:
  envoy:
    image: envoyproxy/envoy:v1.28-latest
    container_name: envoy
    restart: unless-stopped
    volumes:
      - ./envoy/envoy.yaml:/etc/envoy/envoy.yaml:ro
    ports:
      - "80:80"
      - "443:443"
      - "9901:9901"
    networks:
      - envoy-network

networks:
  envoy-network:
    driver: bridge
```

## .env

```bash
# Envoy admin interface
ENVOY_ADMIN_PORT=9901
```

## Usage notes

- Docs: https://www.envoyproxy.io/docs/envoy/latest/
- Admin interface at http://localhost:9901 - stats, config dump, health
- Create envoy/envoy.yaml with listeners, clusters, and routes
- Hot reload config: kill -SIGHUP $(pidof envoy)
- Built-in circuit breaking, retries, and outlier detection
- Use xDS for dynamic configuration in service mesh setups

## Troubleshooting

- Config validation failed: Check envoy.yaml syntax using 'envoy --mode validate --config-path envoy.yaml'
- Admin interface returns 404: Verify admin listener is configured in envoy.yaml with correct address binding
- Upstream cluster connection failures: Ensure cluster endpoints are reachable and health checks are properly configured
- High memory usage during traffic spikes: Adjust connection buffer limits and enable HTTP/2 connection reuse
- SSL handshake failures: Verify certificate chain completeness and TLS version compatibility in listener configuration
- Hot reload not working: Ensure Envoy process has proper signal handling enabled and configuration file permissions are correct

