Switchboard: Simple Powerful Ingress in an Envoy Proxy Docker Container

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.


  • http://www:mydomain.com@my-cluster
    Simply route traffic directed at http://www.mydomain.com to my-cluster (egress)
  • https://www?:mydomain.com/search@google.com
    Redirect both of the following to google.com:
    • https://www.mydomain.com/search
    • https://mydomain.com/search 
  • https!://:mydomain.com/api!@api-cluster
    • https! forces https
    • /api! strips the /api prefix from the path before routing to the egress cluster
  • wss?://api:mydomain.com@my-cluster
    • 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 dev-www.technicallywizadry.com, 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.

Read the Diff

The Diff is a weekly email with step-by-step instructions, project ideas, and links. Drop your email in the form below, and I'll send you some of my favorite resources. The links cover everything from off-grid/vanlife construction to home automation and Raspberry Pis.

... but this site has no paywalls. If you do choose to sign up for this mailing list I promise I'll keep the content worth your time.

Written by
(zane) / Technically Wizardry
Join the discussion


Around the Web