Any sufficiently advanced technology is indistinguishable from magic.

Switchboard: Simple Powerful Ingress in an Envoy Proxy Docker Container

As websites grow, routing traffic becomes increasingly complicated. Different subdomains, domains, and paths might need to be routed to different backend servers. TLS (https) certificates need to be managed, monitoring/observability becomes important, and things like WebSockets, GRPC, statelessness, and Kubernetes might play a role. Unfortunately, setting up something like an envoy proxy is generally not simple.

Check out the open-source Switchboard project on Github. You can pull it from inzania/switchboard:latest on Docker.

Simple to Configure Envoy Proxy

Switchboard resembles a Kubernetes ingress controller, but is more powerful and more portable. For example, it manages SSL certificate generation and renewal while still achieving statelessness. The docker container may be configured with any combination of mounted config directories and environment variables. This makes it easy to set up via docker-compose, Kubernetes, or any system which can deploy containers.


  • TLS termination (https)
  • GRPC
  • Web Sockets
  • HTTP->HTTPS redirection
  • Domain name redirection
  • Sharding (different subdomains for different environments)
  • Automatic certificate generation via CertBot/LetsEncrypt
  • Stateless (certificate backup via S3)

Sample Kubernetes Deployment

See switchboard-deployment yml.

This example assumes kube2iam for AWS authentication in order to achieve the S3 backup-and-restore of certbot-generated certifiactes. It also tweaks the default logging formats to structured JSON, making it well suited for a variety of ingestion pipelines. Finally, it provides samples of readiness and liveness checks.

Configuration Examples

Switchboard aims to provide a simple DSL for defining ingress (what traffic is accepted?) and egress (where does that traffic go?). See the Github project for complete usage documentation.


    Simply route traffic directed at to my-cluster (egress)
  • https://www?
    Redirect both of the following to
  • https!://!@api-cluster
    • https! forces https
    • /api! strips the /api prefix from the path before routing to the egress cluster
  • wss?://
    • wss and ws work identically to https and http, except support web socket upgrading
    • wss? and https? listen on both secure and insecure schemas.


  • my-cluster:http@localhost:5200: Route regular HTTP traffic for my-cluster to localhost:5200
  • my-cluster:grpc@localhost:5201: Route GRPC traffic for my-cluster to localhost:5201

Enabling Environments

I use Switchboard for this blog. The same Kubernetes production AWS cluster is running several different Docker containers, each hosting different projects of mine.

At home, I have a Linux computer running an almost identical deployment as my staging environment. I use the kustomize tool to change the ingress so that it listens on different domains.

Finally, development takes place on my laptop. Kustomize is used again, this time to enable Switchboard’s shard feature. The result is to enable URLs like, where I can access the development version of this blog thanks to an edit to /etc/hosts.

Technical Design

The docker image is based upon envoyproxy/envoy:latest. The Dockerfile layers in certbot, aws, and a few others. The Python start script generates the necessary configuration files. It’s the simple work of a Python-newb, but the resulting configuration files are fairly well-tuned.

About the author

(zane) / Technically Wizardry

I've been a game designer, startup founder, and @Airbnb for 6+ years. This blog documents my hobbies of building a vanlife van, "magic" home automation, and interesting software to control it all.

Add comment

Any sufficiently advanced technology is indistinguishable from magic.

Around the Web