This project is no longer maintained by Turbine Labs, which has shut down.
Envoy-simple is a Docker image of Envoy proxy that makes it easy to configure Envoy from a dynamic control plane. Instead of an Envoy configuration file, envoy-simple pulls all its configuration over Envoy's xDS APIs. Configuring the container is as easy as setting a few environment variables:
$ docker run -d \ -e 'ENVOY_XDS_HOST=127.0.0.1' \ -e 'ENVOY_XDS_PORT=50000' \ -p 9999:9999 \ -p 80:80 \ turbinelabs/envoy-simple:0.19.0
By default, envoy-simple opens up an admin port on
0.0.0.0:9999, and looks for an xDS
It supports the following environment variables:
- ENVOY_BASE_ID (default: 0): sets the base ID so that multiple envoys can run on the same host
- ENVOY_NODE_ID (default:
default-node): sets the node ID
- ENVOY_NODE_CLUSTER (default:
default-cluster): sets the node cluster
- ENVOY_NODE_ZONE (default:
default-zone): sets the zone in the node locality
- ENVOY_ADMIN_IP (default:
0.0.0.0): sets the admin server listener ip
- ENVOY_ADMIN_PORT (default:
9999): sets the admin server listener port
- ENVOY_ADMIN_LOG (default:
/dev/stdout): sets the path to the admin server logfile
- ENVOY_XDS_HOST (default:
127.0.0.1): sets the xDS server hostname or IP address
- ENVOY_XDS_PORT (default:
50000): sets the xDS server port
- ENVOY_XDS_CONNECT_TIMEOUT_SECS (default:
30): sets the timeout to connect to xDS services, in seconds
- ENVOY_XDS_REFRESH_DELAY_SECS (default:
10): sets the delay between calls refresh calls to xDS
- ENVOY_XDS_KEEPALIVE_PROBES: number of consecutive TCP keep-alive failures encountered before the xDS connection is closed and re-opened
- ENVOY_XDS_KEEPALIVE_TIME_SECS: how long, in seconds, after the TCP connection goes idle before TCP keep-alive checks begin
- ENVOY_XDS_KEEPALIVE_INTERVAL_SECS: the interval, in seconds, between TCP keep-alive checks
- ENVOY_LOG_LEVEL (default:
info): sets the log level to one of:
- ENVOY_ARGS (default: none): additional args for the envoy binary
Envoy logs are emitted on STDERR, and by default admin server request logging is sent to STDOUT.
You can configure one or more tracers in Envoy by setting appropriate environment variables. Tracers need a destination to send spans, which requires a static cluster. Envoy-simple will create both the static cluster and tracing configuration elements for you.
To generate spans you'll need to add tracing information to your HTTP connection manager
For Zipkin, all you need to specify is the collector host if you're running a default zipkin build, although you can override the cluster name, port, and endpoint if you like.
$ docker run -d \ -e 'ENVOY_XDS_HOST=127.0.0.1' \ -e 'ENVOY_XDS_PORT=50000' \ -e 'ENVOY_ZIPKIN_COLLECTOR_HOST=zipkin.example.com' -p 9999:9999 \ -p 80:80 \ turbinelabs/envoy-simple:0.19.0
- ENVOY_ZIPKIN_COLLECTOR_HOST set the zipkin server hostname
- ENVOY_ZIPKIN_COLLECTOR_PORT (defaults to 9411) set the zipkin server port
- ENVOY_ZIPKIN_COLLECTOR_CLUSTER (defaults to zipkin) set the name static cluster in the Envoy config
- ENVOY_ZIPKIN_COLLECTOR_ENDPOINT (defaults to /api/vi/spans) set the endpoint Envoy will send spans to
- ENVOY_ZIPKIN_CONNECT_TIMEOUT_SECS (defaults to 30) set the connect timeout for the zipkin cluster
For LightStep, all you need to specify is the location of the access token file. Note that you will also need to make this file available in the docker container, using
$ docker run -d \ -e 'ENVOY_XDS_HOST=127.0.0.1' \ -e 'ENVOY_XDS_PORT=50000' \ -e 'ENVOY_LIGHTSTEP_ACCESS_TOKEN=<your lightstep access token> -p 9999:9999 \ -p 80:80 \ turbinelabs/envoy-simple:0.19.0
- ENVOY_LIGHTSTEP_ACCESS_TOKEN set the LightStep access token
- ENVOY_LIGHTSTEP_COLLECTOR_HOST (defaults to collector-grpc.lightstep.com) set the hostname for the LightStep collector. Note that this collector must support gRPC for sending traces
- ENVOY_LIGHTSTEP_COLLECTOR_PORT (defaults to 443) set the port number of the LightStep collector
- ENVOY_LIGHTSTEP_COLLECTOR_CLUSTER (defaults to lightstep) set the name of the static LightStep collector clutser in the Envoy config
- ENVOY_LIGHTSTEP_CONNECT_TIMEOUT_SECS (defaults to 30) set the connect timeout for the LightStep cluster
Please see Versioning of Turbine Labs Open Source Projects.
Patches accepted! Please see Contributing to Turbine Labs Open Source Projects.
Code of Conduct
All Turbine Labs open-sourced projects are released with a Contributor Code of Conduct. By participating in our projects you agree to abide by its terms, which will be carefully enforced.