Envoy

---
name: envoy
description: "Expert coverage of Envoy Proxy and Envoy Gateway: xDS APIs, L7 filter chains, WASM extensions, HTTP Connection Manager, Envoy Gateway Kubernetes Gateway API implementation, service mesh data plane (Istio, Consul), circuit breaking, and cloud-native load balancing patterns. Use for \"Envoy\", \"Envoy Proxy\", \"xDS\", \"Envoy Gateway\", \"Envoy filter\", \"WASM Envoy\", \"Istio data plane\", \"service mesh proxy\", \"Envoy configuration\". Do NOT use for cross-vendor comparison, platform selection, or category-wide architecture -- use the `load-balancing` skill. Do NOT use for Kubernetes-native service mesh sidecar/mTLS questions -- that's the `istio` skill (in the `containers` plugin)."
license: MIT
---

# Envoy Proxy

This skill covers Envoy Proxy and Envoy Gateway across all current versions. Areas of expertise include:

- xDS APIs: LDS, RDS, CDS, EDS, SDS, ADS -- dynamic configuration from control planes
- Filter chains: HTTP Connection Manager, L7 HTTP filters, L4 network filters
- WASM extensions: WebAssembly custom filters (Rust, C++, TinyGo, AssemblyScript)
- Envoy Gateway: Kubernetes Gateway API implementation (GatewayClass, HTTPRoute, BackendTrafficPolicy)
- Service mesh data plane: Istio sidecar, Consul Connect, AWS App Mesh, ambient mesh
- Load balancing: Round robin, least request, ring hash, Maglev, random
- Resilience: Circuit breaking, outlier detection, retry, timeout, fault injection
- Observability: Access logging, distributed tracing (Zipkin, Jaeger, OpenTelemetry), metrics (Prometheus)
- TLS: SDS-based certificate rotation, mTLS, SPIFFE identity
- Protocol support: HTTP/1.1, HTTP/2, HTTP/3 (QUIC), gRPC, TCP, UDP, MongoDB, Redis

## How to Approach Tasks

1. **Classify** the request:
   - **Architecture** -- Load `references/architecture.md` for xDS, filter chain, and cluster internals
   - **Configuration** -- Static config (envoy.yaml) or dynamic config (xDS from control plane)
   - **Envoy Gateway** -- Kubernetes Gateway API resources, CRDs, extension policies
   - **Service mesh** -- Istio/Consul sidecar configuration, mTLS, traffic shifting
   - **Extensions** -- WASM filter development, ext_authz, rate limiting
   - **Troubleshooting** -- Access logs, admin interface, config dump, cluster health

2. **Identify deployment context** -- Standalone Envoy, Envoy Gateway (K8s), Istio sidecar, or Consul Connect. Configuration and management differ significantly.

3. **Load context** -- Read `references/architecture.md` for deep xDS and filter chain knowledge.

4. **Analyze** -- Apply Envoy-specific reasoning. Consider filter chain ordering (filters execute in order), xDS version consistency, and control plane interaction.

5. **Recommend** -- Provide actionable guidance with Envoy YAML, Envoy Gateway CRDs, or xDS configuration.

6. **Verify** -- Suggest validation (admin interface /clusters, /config_dump, /stats, access logs).

## xDS APIs

The xDS (x Discovery Service) APIs enable dynamic Envoy configuration from a control plane:

| xDS | Manages | Key Fields |
|---|---|---|
| **LDS** (Listener) | Listeners: IP:port, filter chains, TLS | `address`, `filter_chains`, `listener_filters` |
| **RDS** (Route) | HTTP route tables: virtual hosts, route matches | `virtual_hosts`, `route`, `match`, `cluster` |
| **CDS** (Cluster) | Upstream clusters: endpoints, health checks, circuit breaking | `name`, `type`, `lb_policy`, `health_checks` |
| **EDS** (Endpoint) | Individual endpoints within clusters | `cluster_name`, `endpoints`, `health_status` |
| **SDS** (Secret) | TLS certificates and keys | `tls_certificate`, `validation_context` |
| **ADS** (Aggregated) | Single stream for all xDS; ensures ordering | All of the above over one gRPC stream |

### xDS Protocol

- Transport: **gRPC** (preferred) or REST (HTTP/2 + protobuf)
- Version: **xDS v3** (current); v2 deprecated
- Control planes implementing xDS: Istio (istiod), Consul, go-control-plane, custom
- **Incremental xDS (Delta)** -- Send only changed resources, not full state

### Static vs Dynamic Configuration

```yaml
# Static configuration (envoy.yaml) - no control plane needed
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
                route_config:
                  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
      type: STRICT_DNS
      load_assignment:
        cluster_name: backend_cluster
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    socket_address: { address: backend, port_value: 8080 }
```

## Filter Chain Architecture

### HTTP Connection Manager (HCM)

The primary L7 filter; handles HTTP/1.1, HTTP/2, HTTP/3 (QUIC):

- Configures: access logging, header manipulation, timeouts, idle timeouts
- Hosts the HTTP filter chain (ordered list of filters applied per request)
- Route configuration: static (inline) or dynamic (RDS)

### HTTP Filters

| Filter | Purpose | Configuration |
|---|---|---|
| **router** | Route to upstream cluster | Required; always last in chain |
| **rate_limit** | External Rate Limit Service (RLS) | gRPC call to RLS for rate decisions |
| **ext_authz** | External authorization | gRPC or HTTP call to auth service |
| **jwt_authn** | JWT token validation | JWKS endpoint, issuer, audience validation |
| **cors** | CORS header management | Allow origins, methods, headers |
| **fault** | Chaos testing | Inject delay (ms) or abort (HTTP status) |
| **grpc_web** | gRPC-Web translation | Browser gRPC-Web to backend gRPC |
| **lua** | Inline Lua scripts | Custom request/response logic |
| **wasm** | WebAssembly filters | Custom compiled modules |
| **compressor** | Response compression | gzip, brotli, zstd |
| **health_check** | Health check endpoint | Respond to /healthz without upstream |
| **tap** | Traffic tapping | Capture request/response for debugging |

### Network Filters (L4)

| Filter | Purpose |
|---|---|
| **tcp_proxy** | L4 TCP proxying; TLS passthrough |
| **http_connection_manager** | L7 HTTP processing (most common) |
| **mongo_proxy** | MongoDB protocol inspection and stats |
| **redis_proxy** | Redis protocol proxying with cluster sharding |
| **thrift_proxy** | Apache Thrift protocol handling |

### Filter Ordering

Filters execute in the order listed in the configuration. The `router` filter must always be last:

```yaml
http_filters:
  - name: envoy.filters.http.jwt_authn      # 1st: Validate JWT
  - name: envoy.filters.http.ext_authz      # 2nd: External authorization
  - name: envoy.filters.http.rate_limit     # 3rd: Rate limiting
  - name: envoy.filters.http.fault          # 4th: Fault injection (testing)
  - name: envoy.filters.http.router         # LAST: Route to upstream
```

## WASM Extensions

Envoy supports WebAssembly modules as pluggable filters:

- **Languages**: Rust, C++, AssemblyScript, TinyGo
- **Code sources**: HTTP URL, OCI image, local file
- **TLS for code source**: TLS-authenticated fetch of WASM binaries (added March 2026)
- **Capabilities**: Custom auth, telemetry, transformation, protocol handling

### EnvoyExtensionPolicy (Envoy Gateway)

```yaml
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyExtensionPolicy
metadata:
  name: custom-auth
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: my-route
  wasm:
    - name: custom-auth-filter
      code:
        type: OCI
        oci:
          image: registry.example.com/envoy-filters/auth:v1
      config:
        type: String
        string: '{"auth_endpoint":"https://auth.example.com"}'
```

## Envoy Gateway

Envoy Gateway implements the Kubernetes **Gateway API** using Envoy as the data plane:

### Key Resources

| Resource | Purpose |
|---|---|
| **GatewayClass** | Defines controller (Envoy Gateway) |
| **Gateway** | Instantiates listeners (L7 or L4) |
| **HTTPRoute** | HTTP routing rules (virtual hosts, path matching) |
| **TLSRoute** | TLS passthrough routing |
| **TCPRoute** | L4 TCP routing |
| **BackendTrafficPolicy** | Circuit breaking, retry, timeout, health checks |
| **SecurityPolicy** | JWT auth, ext_authz, CORS per route |
| **EnvoyExtensionPolicy** | WASM filters, extension servers |

### Example Gateway + HTTPRoute

```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  gatewayClassName: eg
  listeners:
    - name: http
      protocol: HTTP
      port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      backendRefs:
        - name: api-v1-svc
          port: 8080
    - matches:
        - path:
            type: PathPrefix
            value: /v2
      backendRefs:
        - name: api-v2-svc
          port: 8080
```

### Extension Server

- gRPC hook that receives xDS config before it's sent to Envoy
- Allows external modification of generated xDS resources
- Enables custom logic not possible with standard Gateway API resources

Current version: **Envoy Gateway v1.5.3** (March 2026).

## Service Mesh Data Plane

Envoy is the universal data plane for major service meshes:

### Istio

- Envoy sidecar injected into each pod
- Istiod (control plane) programs sidecars via xDS
- Features: mTLS (automatic), traffic shifting (canary), circuit breaking, distributed tracing
- **Ambient mesh mode**: ztunnel (node-level proxy) replaces per-pod sidecar for simpler deployment

### Consul Connect

- Consul programs Envoy sidecars
- Service intentions map to Envoy filter policies
- mTLS with Consul-issued certificates (SPIFFE)

### AWS App Mesh

- AWS-managed control plane programs Envoy sidecars in ECS/EKS
- Virtual nodes, virtual services, virtual routers map to Envoy config

## Load Balancing Policies

| Policy | Description | Use Case |
|---|---|---|
| **ROUND_ROBIN** | Sequential distribution | General purpose |
| **LEAST_REQUEST** | Fewest active requests (power of 2 choices) | Variable request duration |
| **RING_HASH** | Consistent hashing by key | Session affinity without cookies |
| **MAGLEV** | Google Maglev consistent hashing | Stable hashing with minimal disruption |
| **RANDOM** | Random selection | Simple, low overhead |

## Resilience Patterns

### Circuit Breaking

```yaml
circuit_breakers:
  thresholds:
    - max_connections: 1000
      max_pending_requests: 100
      max_requests: 1000
      max_retries: 3
```

### Outlier Detection

```yaml
outlier_detection:
  consecutive_5xx: 5
  interval: 10s
  base_ejection_time: 30s
  max_ejection_percent: 50
```

### Retry Policy

```yaml
retry_policy:
  retry_on: "5xx,connect-failure,retriable-4xx"
  num_retries: 3
  per_try_timeout: 2s
```

## Common Pitfalls

1. **Router filter not last** -- The `router` filter must be the last HTTP filter in the chain. Filters after `router` are never executed.

2. **xDS version mismatch** -- Mixing v2 and v3 xDS resources causes configuration rejection. Use v3 exclusively.

3. **Missing ADS for ordering** -- Without ADS, CDS and EDS can arrive out of order, causing temporary routing errors. Use ADS for consistent configuration delivery.

4. **Circuit breaker defaults too low** -- Default `max_connections` is 1024. High-traffic services easily exceed this, causing HTTP 503 responses with `upstream_cx_overflow`.

5. **Ignoring outlier detection** -- Without outlier detection, Envoy continues sending traffic to failing endpoints. Enable outlier detection for all production clusters.

6. **WASM filter performance** -- WASM filters add latency per request. Profile filter performance before production deployment; avoid complex computation in hot paths.

7. **Static config in dynamic environments** -- Using static configuration when endpoints change frequently causes stale routing. Use EDS for dynamic endpoint discovery.

8. **Filter chain mismatch** -- Listener filter chain matching is exact. A TLS listener will not match non-TLS traffic. Ensure filter chain match criteria align with expected traffic.

## Reference Files

Load these when you need deep knowledge:

- `references/architecture.md` -- xDS protocol internals, filter chain processing, WASM runtime, Envoy Gateway architecture, service mesh integration. Read for "how does X work" questions.