Envoy Proxy Cheatsheet¶
Installation¶
| Platform | Command |
|---|---|
| Ubuntu/Debian | curl -sL 'https://deb.dl.getenvoy.io/public/gpg.8115BA8E629CC074.key' \| gpg --dearmor -o /usr/share/keyrings/getenvoy-keyring.gpg && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/getenvoy-keyring.gpg] https://deb.dl.getenvoy.io/public/deb/ubuntu $(lsb_release -cs) main" \| sudo tee /etc/apt/sources.list.d/getenvoy.list && sudo apt update && sudo apt install -y getenvoy-envoy |
| macOS | brew install envoy |
| Docker | docker pull envoyproxy/envoy:v1.28-latest |
| Binary (Linux) | curl -L https://github.com/envoyproxy/envoy/releases/download/v1.28.0/envoy-1.28.0-linux-x86_64 -o envoy && chmod +x envoy && sudo mv envoy /usr/local/bin/ |
| RHEL/CentOS | curl -sL 'https://rpm.dl.getenvoy.io/public/gpg.CF716AF503183491.key' \| sudo rpm --import - && sudo yum-config-manager --add-repo https://rpm.dl.getenvoy.io/public/rpm/el/8/x86_64 && sudo yum install -y getenvoy-envoy |
| Kubernetes (Helm) | helm repo add bitnami https://charts.bitnami.com/bitnami && helm install my-envoy bitnami/envoy |
| Verify Installation | envoy --version |
Basic Commands¶
| Command | Description |
|---|---|
envoy -c envoy.yaml |
Start Envoy with specified configuration file |
envoy --version |
Display Envoy version information |
envoy --help |
Show all available command-line options |
envoy --mode validate -c envoy.yaml |
Validate configuration file without starting |
envoy -c envoy.yaml --log-level info |
Start with specific log level (trace, debug, info, warn, error, critical) |
envoy -c envoy.yaml --component-log-level upstream:debug |
Set log level for specific component |
envoy -c envoy.yaml --service-cluster my-cluster |
Start with service cluster identifier |
envoy -c envoy.yaml --service-node node-1 |
Start with service node identifier |
envoy -c envoy.yaml --base-id 0 |
Set base ID for hot restart functionality |
envoy -c envoy.yaml --restart-epoch 1 |
Perform hot restart with epoch number |
envoy -c envoy.yaml --drain-time-s 60 |
Set drain time for graceful shutdown (seconds) |
envoy -c envoy.yaml --parent-shutdown-time-s 90 |
Set parent shutdown time during hot restart |
envoy -c envoy.yaml --concurrency 4 |
Set number of worker threads |
envoy -c envoy.yaml --disable-hot-restart |
Disable hot restart functionality |
envoy --help-hidden |
Display hidden/advanced command-line options |
Admin Interface Commands¶
| Command | Description |
|---|---|
curl http://localhost:9901/server_info |
Get server information and current state |
curl http://localhost:9901/stats |
Retrieve all statistics in plain text format |
curl http://localhost:9901/stats/prometheus |
Export statistics in Prometheus format |
curl http://localhost:9901/stats?format=json |
Get statistics in JSON format |
curl http://localhost:9901/stats?filter=cluster.outbound |
Filter statistics by prefix |
curl http://localhost:9901/stats?usedonly |
Show only statistics with non-zero values |
curl http://localhost:9901/config_dump |
Dump complete current configuration |
curl http://localhost:9901/config_dump?resource=bootstrap |
Dump only bootstrap configuration |
curl http://localhost:9901/config_dump?resource=dynamic_listeners |
Dump dynamic listener configuration |
curl http://localhost:9901/config_dump?resource=dynamic_clusters |
Dump dynamic cluster configuration |
curl http://localhost:9901/clusters |
Get detailed cluster information and health status |
curl http://localhost:9901/listeners |
Get detailed listener information |
curl http://localhost:9901/ready |
Check if Envoy is ready to serve traffic |
curl -X POST http://localhost:9901/healthcheck/fail |
Mark server as failed for health checks |
curl -X POST http://localhost:9901/healthcheck/ok |
Mark server as healthy for health checks |
curl -X POST http://localhost:9901/reset_counters |
Reset all statistics counters to zero |
curl -X POST http://localhost:9901/drain_listeners |
Drain listeners for graceful shutdown |
curl -X POST http://localhost:9901/logging?level=debug |
Change global log level at runtime |
curl -X POST http://localhost:9901/logging?upstream=debug |
Change component-specific log level |
curl -X POST http://localhost:9901/runtime_modify?key=value |
Modify runtime configuration values |
Advanced Usage¶
| Command | Description |
|---|---|
curl http://localhost:9901/stats \| grep circuit_breakers |
Monitor circuit breaker statistics |
curl http://localhost:9901/stats \| grep outlier_detection |
Check outlier detection events |
curl http://localhost:9901/stats \| grep ratelimit |
View rate limiting statistics |
curl http://localhost:9901/stats \| grep upstream_rq_retry |
Monitor retry statistics |
curl http://localhost:9901/stats \| grep ssl |
Check TLS/SSL connection statistics |
curl http://localhost:9901/stats \| grep http.ingress.downstream_rq |
Monitor incoming HTTP requests |
curl http://localhost:9901/clusters \| grep health_flags |
Check cluster health status flags |
curl http://localhost:9901/config_dump \| jq '.configs[].bootstrap.tracing' |
Extract tracing configuration |
curl http://localhost:9901/config_dump \| jq '.configs[].dynamic_active_clusters' |
View active dynamic clusters |
curl http://localhost:9901/stats?format=json \| jq '.stats[] \| select(.name \| contains("upstream_cx_"))' |
Filter connection statistics with jq |
curl http://localhost:9901/listeners \| grep -A 5 "address" |
View listener addresses and ports |
curl http://localhost:9901/stats/prometheus \| grep envoy_cluster_upstream_rq_total |
Export specific metric to Prometheus |
docker run -d -v $(pwd)/envoy.yaml:/etc/envoy/envoy.yaml -p 9901:9901 -p 10000:10000 envoyproxy/envoy:v1.28-latest |
Run Envoy in Docker with mounted config |
kubectl create configmap envoy-config --from-file=envoy.yaml |
Create Kubernetes ConfigMap for Envoy config |
kubectl logs -f deployment/envoy |
Follow Envoy logs in Kubernetes |
envoy -c envoy.yaml --log-format '[%Y-%m-%d %T.%e][%t][%l] %v' |
Start with custom log format |
curl http://localhost:9901/certs |
Display loaded TLS certificates information |
curl http://localhost:9901/memory |
Show memory allocation statistics |
curl http://localhost:9901/contention |
Display mutex contention statistics (if enabled) |
curl -X POST http://localhost:9901/cpuprofiler?enable=y |
Enable CPU profiling (if compiled with profiling) |
Configuration¶
Basic Configuration Structure¶
# envoy.yaml - Minimal configuration
static_resources:
listeners:
- name: listener_0
address:
socket_address:
address: 0.0.0.0
port_value: 10000
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: ingress_http
route_config:
name: local_route
virtual_hosts:
- name: backend
domains: ["*"]
routes:
- match:
prefix: "/"
route:
cluster: service_backend
http_filters:
- name: envoy.filters.http.router
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
clusters:
- name: service_backend
connect_timeout: 0.25s
type: STRICT_DNS
lb_policy: ROUND_ROBIN
load_assignment:
cluster_name: service_backend
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: backend-service
port_value: 8080
admin:
address:
socket_address:
address: 0.0.0.0
port_value: 9901
Dynamic Configuration (xDS)¶
# envoy-dynamic.yaml - Control plane configuration
node:
cluster: my-cluster
id: node-1
dynamic_resources:
lds_config:
resource_api_version: V3
api_config_source:
api_type: GRPC
transport_api_version: V3
grpc_services:
- envoy_grpc:
cluster_name: xds_cluster
cds_config:
resource_api_version: V3
api_config_source:
api_type: GRPC
transport_api_version: V3
grpc_services:
- envoy_grpc:
cluster_name: xds_cluster
static_resources:
clusters:
- name: xds_cluster
connect_timeout: 1s
type: STRICT_DNS
lb_policy: ROUND_ROBIN
http2_protocol_options: {}
load_assignment:
cluster_name: xds_cluster
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: control-plane
port_value: 18000
admin:
address:
socket_address:
address: 0.0.0.0
port_value: 9901
Advanced Features Configuration¶
# Circuit breaker and outlier detection
clusters:
- name: backend_service
connect_timeout: 0.25s
type: STRICT_DNS
lb_policy: ROUND_ROBIN
circuit_breakers:
thresholds:
- priority: DEFAULT
max_connections: 1024
max_pending_requests: 1024
max_requests: 1024
max_retries: 3
outlier_detection:
consecutive_5xx: 5
interval: 30s
base_ejection_time: 30s
max_ejection_percent: 50
enforcing_consecutive_5xx: 100
load_assignment:
cluster_name: backend_service
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: backend
port_value: 8080
health_check_config:
port_value: 8081
TLS Configuration¶
# TLS termination
listeners:
- name: https_listener
address:
socket_address:
address: 0.0.0.0
port_value: 443
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: ingress_https
route_config:
name: local_route
virtual_hosts:
- name: backend
domains: ["*"]
routes:
- match:
prefix: "/"
route:
cluster: backend_service
http_filters:
- name: envoy.filters.http.router
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
transport_socket:
name: envoy.transport_sockets.tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
common_tls_context:
tls_certificates:
- certificate_chain:
filename: /etc/ssl/certs/server.crt
private_key:
filename: /etc/ssl/private/server.key
Common Use Cases¶
Use Case: Basic HTTP Proxy¶
Set up Envoy as a simple HTTP proxy forwarding traffic to backend services.
# Create configuration file
cat > envoy.yaml << EOF
static_resources:
listeners:
- name: listener_0
address:
socket_address:
address: 0.0.0.0
port_value: 8080
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: ingress_http
route_config:
name: local_route
virtual_hosts:
- name: backend
domains: ["*"]
routes:
- match:
prefix: "/"
route:
cluster: backend_cluster
http_filters:
- name: envoy.filters.http.router
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
clusters:
- name: backend_cluster
connect_timeout: 0.25s
type: STRICT_DNS
lb_policy: ROUND_ROBIN
load_assignment:
cluster_name: backend_cluster
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: localhost
port_value: 3000
admin:
address:
socket_address:
address: 0.0.0.0
port_value: 9901
EOF
# Start Envoy
envoy -c envoy.yaml
# Test the proxy
curl http://localhost:8080
# Monitor statistics
curl http://localhost:9901/stats | grep http
Use Case: Load Balancing Multiple Backends¶
Configure Envoy to load balance across multiple backend instances with health checking.
# Create load balancing configuration
cat > envoy-lb.yaml << EOF
static_resources:
listeners:
- name: listener_0
address:
socket_address:
address: 0.0.0.0
port_value: 8080
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: ingress_http
route_config:
name: local_route
virtual_hosts:
- name: backend
domains: ["*"]
routes:
- match:
prefix: "/"
route:
cluster: backend_cluster
http_filters:
- name: envoy.filters.http.router
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
clusters:
- name: backend_cluster
connect_timeout: 0.25s
type: STRICT_DNS
lb_policy: ROUND_ROBIN
health_checks:
- timeout: 1s
interval: 10s
unhealthy_threshold: 2
healthy_threshold: 2
http_health_check:
path: /health
load_assignment:
cluster_name: backend_cluster
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: backend1.example.com
port_value: 8080
- endpoint:
address:
socket_address:
address: backend2.example.com
port_value: 8080
- endpoint:
address:
socket_address:
address: backend3.example.com
port_value: 8080
admin:
address:
socket_address:
address: 0.0.0.0
port_value: 9901
EOF
# Start Envoy with load balancing
envoy -c envoy-lb.yaml
# Check cluster health status
curl http://localhost:9901/clusters
# Monitor load distribution
watch -n 1 'curl -s http://localhost:9901/stats | grep backend_cluster.upstream_rq_total'
Use Case: TLS Termination and Re-encryption¶
Configure Envoy to terminate TLS from clients and re-encrypt to backends.
# Generate self-signed certificates for testing
openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt -days 365 -nodes -subj "/CN=localhost"
# Create TLS configuration
cat > envoy-tls.yaml << EOF
static_resources:
listeners:
- name: https_listener
address:
socket_address:
address: 0.0.0.0
port_value: 443
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: ingress_https
route_config:
name: local_route
virtual_hosts:
- name: backend
domains: ["*"]
routes:
- match:
prefix: "/"
route:
cluster: secure_backend
http_filters:
- name: envoy.filters.http.router
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
transport_socket:
name: envoy.transport_sockets.tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
common_tls_context:
tls_certificates:
- certificate_chain:
filename: server.crt
private_key:
filename: server.key
clusters:
- name: secure_backend
connect_timeout: 0.25s
type: STRICT_DNS
lb_policy: ROUND_ROBIN
transport_socket:
name: envoy.transport_sockets.tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
load_assignment:
cluster_name: secure_backend
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: backend.example.com
port_value: 443
admin:
address:
socket_address:
address: 0.0.0.0
port_value: 9901
EOF
# Start Envoy with TLS
envoy -c envoy-tls.yaml
# Test TLS connection
curl -k https://localhost
# Check TLS statistics
curl http://localhost:9901/stats | grep ssl
Use Case: Rate Limiting and Circuit Breaking¶
Implement rate limiting and circuit breaking for resilient service communication.
# Create resilience configuration
cat > envoy-resilience.yaml << EOF
static_resources:
listeners:
- name: listener_0
address:
socket_address:
address: 0.0.0.0
port_value: 8080
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: ingress_http
route_config:
name: local_route
virtual_hosts:
- name: backend
domains: ["*"]
routes:
- match:
prefix: "/"
route:
cluster: protected_backend
retry_policy:
retry_on: "5xx"
num_retries: 3
per_try_timeout: 1s
http_filters:
- name: envoy.filters.http.router
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
clusters:
- name: protected_backend
connect_timeout: 0.25s
type: STRICT_DNS
lb_policy: ROUND_ROBIN
circuit_breakers:
thresholds:
- priority: DEFAULT
max_connections: 100
max_pending_requests: 100
max_requests: 100
max_retries: 3
outlier_detection:
consecutive_5xx: 5
interval: 10s
base_ejection_time: 30s
max_ejection_percent: 50
load_assignment:
cluster_name: protected_backend
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: backend.example.com
port_value: 8080
admin:
address:
socket_address:
address: 0.0.0.0
port_value: 9901
EOF
# Start Envoy with resilience features
envoy -c envoy-resilience.yaml
# Monitor circuit breaker status
curl http://localhost:9901/stats | grep circuit_breakers
# Check outlier detection events
curl http://localhost:9901/stats | grep outlier_detection
# View retry statistics
curl http://localhost:9901/stats | grep retry
Use Case: Observability with Distributed Tracing¶
Configure Envoy with distributed tracing for microservices observability.
```bash
Create tracing configuration¶
cat > envoy-tracing.yaml << EOF static_resources: listeners: - name: listener_0 address: socket_address: address: 0.0.0.0 port_value: 8080 filter_chains: - filters: - name: envoy.filters.network.http_connection_manager typed_config: "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager stat_prefix