Envoy

Last reviewed Aug 26, 2026 · 814 words

Envoy is the proxy inside Istio, Envoy Gateway, Contour and most of the service meshes you have heard of, and almost nobody should run it by hand at home. For "put TLS in front of 12 containers" it is the wrong tool: no automatic certificates, no Docker-label discovery, and around 60 lines of YAML for what Caddy does in 3. It earns its place when the proxy itself is the product: routing decisions per request, retries and outlier detection between services, or a control plane pushing configuration to a fleet of proxies. The catalogue rates it Hard, and that is the honest rating.

The minimal static config, so you know what you are signing up for

A single listener forwarding to a single upstream, which is the entire job for most home proxies, looks like this:

static_resources:
  listeners:
    - name: web
      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
                route_config:
                  virtual_hosts:
                    - name: app
                      domains: ["*"]
                      routes:
                        - match: { prefix: "/" }
                          route: { cluster: app }
                http_filters:
                  - name: envoy.filters.http.router
                    typed_config:
                      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
  clusters:
    - name: app
      connect_timeout: 2s
      load_assignment:
        cluster_name: app
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    socket_address: { address: app, port_value: 3000 }
admin:
  address:
    socket_address: { address: 127.0.0.1, port_value: 9901 }

Run it with envoy -c envoy.yaml from the envoyproxy/envoy image. Every noun in that file, listener, filter chain, HTTP connection manager, route, cluster, endpoint, is a concept you will need to hold in your head, and the typed @type URLs are why the "verbose YAML" complaint exists. The verbosity is not carelessness; it is the cost of a configuration model designed to be generated by software rather than typed by people.

Three things it does that Caddy and Traefik do not

First, xDS: every part of that file can instead be fetched from a control plane over gRPC and updated live without a restart, which is what a service mesh is. Second, resilience per route: retries with budgets, circuit breakers per cluster, outlier detection that ejects a backend after 5 consecutive 5xx responses, and traffic splitting by weight for canaries. Third, observability that no other proxy matches out of the box: thousands of counters and histograms per cluster, served in Prometheus format at /stats/prometheus on the admin port, structured access logs, and native OpenTelemetry tracing. If you already run Prometheus and Grafana, Envoy is the proxy that gives you a per-upstream latency histogram for free. Whether you need one is a separate question.

TLS is your problem to solve

Envoy will terminate TLS and will hot-reload certificates through its secret discovery service, but it will not obtain them. There is no ACME client. In Kubernetes that is fine because cert-manager exists; on a single Docker host it means running certbot or acme.sh on a timer and pointing the listener at the files, which is exactly the chore Caddy and Traefik were built to remove. This alone decides the question for most homelabs.

Where it sits in a homelab, if anywhere

The realistic entry point is not raw Envoy but Envoy Gateway, the implementation of the Kubernetes Gateway API, on a k3s cluster where you want mesh-adjacent features without adopting Istio. That gets you weighted routing, retries and the metrics without hand-writing the YAML above. Outside Kubernetes, Caddy or Traefik is the right default and the Caddy versus Traefik comparison settles which; HAProxy remains the choice for raw TCP load balancing at high connection counts. The other legitimate reason to run Envoy at home is that you operate it at work and want a lab: in that case, run it behind Caddy, not instead of it.

The admin port is a foot-gun

Port 9901 serves a config dump including any inline secrets, lets a caller change log levels, drain listeners and reset counters, and has no authentication. The example above binds it to 127.0.0.1 on purpose. Do not publish it in compose, do not put it on a Tailscale interface without an ACL, and treat any tutorial that maps 9901:9901 as a tutorial for a laptop.

What I'd do

For a homelab reverse proxy, do not run Envoy; run Caddy and spend the evening on something that will matter. If you are on k3s and want Gateway API features, install Envoy Gateway and let it generate the configuration. If you want to learn Envoy because your job uses it, run it on a single internal service behind your existing proxy, wire its stats into Prometheus, and study the config dump on 9901 from localhost. That is the one setup where its 512 MB and its learning curve buy something you can use.