Envoy Proxy Primer

Why Envoy

Envoy is a purpose-built L4/L7 proxy with first-class HTTP/2, gRPC, and dynamic configuration via xDS. It runs as a sidecar or edge gateway, giving Meridian services uniform observability, retry budgets, and circuit breaking without application changes.

Core Concepts

• Listener — a named network location (IP:port) that accepts downstream connections. Each listener owns a filter chain.
• Cluster — a logical upstream group with load-balancing policy, health checks, and outlier detection.
• Route — maps incoming requests (host, path, headers) to a cluster. Defined inside an HTTP connection manager filter.
• Filter — pluggable processing stage. HTTP filters handle auth, rate limiting, WAF, and transformation.

Minimal Static Config

A single YAML file bootstraps Envoy without xDS. Below, one listener on port 10000 terminates TLS and proxies to a local Meridian API cluster.

static_resources:
  listeners:
  - name: ingress
    address:
      socket_address: { address: 0.0.0.0, port_value: 10000 }
    filter_chains:
    - 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/certs/fullchain.pem" }
              private_key: { filename: "/etc/certs/privkey.pem" }
      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: api
              domains: ["*"]
              routes:
              - match: { prefix: "/" }
                route: { cluster: meridian_api }
          http_filters:
          - name: envoy.filters.http.router
  clusters:
  - name: meridian_api
    connect_timeout: 5s
    type: STRICT_DNS
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: meridian_api
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address: { address: 127.0.0.1, port_value: 8080 }

Rate Limiting

Attach the HTTP rate-limit filter to enforce per-route quotas. Envoy calls an external RL service over gRPC; descriptors define the key (e.g., header, remote address).

- name: envoy.filters.http.ratelimit
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.ratelimit.v3.RateLimit
    domain: meridian
    rate_limit_service:
      grpc_service:
        envoy_grpc:
          cluster_name: rate_limit_cluster

Next Steps

Move from static config to xDS for zero-downtime reloads. Combine with the Meridian auth filter recipe to validate JWTs at the edge before requests reach your API.