README
¶
Envoyinit
The running instance of Envoy. In Gloo Edge, this is commonly referred to as the gateway-proxy component.
Background
The Envoy Proxy is a cloud-native, high-performance, service proxy.
Source Code
The Gloo Edge service proxies provide all the functionality of the open source Envoy Proxy, in addition to some custom extensions. The source code for these proxies is maintained at envoy-gloo
Versioning
In the Makefile, the ENVOY_GLOO_IMAGE value defines the version of envoy-gloo that Gloo Edge depends on.
Envoy publishes new minor releases each quarter. Gloo attempts to follow this cadence, and increment our minor version of envoy-gloo as well.
Build
All make targets are currently defined in the Makefile at the root of the repository.
The VERSION env variable determines the name of the tag for the image.
You may either inject the version yourself:
VERSION=<version name> make gloo-envoy-wrapper-docker -B
Or rely on the auto-generated version:
make gloo-envoy-wrapper-docker -B
Release
During a Gloo Edge release, the gloo-envoy-wrapper image is published to the Google Cloud Registry and the Quay repository.
Configuration
Envoy configuration can be provided either statically or dynamically. In Gloo Edge, we leverage both of these patterns: at initialization time, the proxy is provided with basic boostrap configuration, and then all future updates are provided dynamically by the control-plane.
Static
Envoy is configured with Bootstrap configuration. This provides static server configuration and configures Envoy to access dynamic configuration from the Gloo control plane.
In Gloo Edge, Envoy configuration is processed in the following order:
- The bootstrap configuration is defined in a ConfigMap
- The ConfigMap is mounted as a volume on the Pod
- At initialization, the container reads the configuration, and transforms it using the Kubernetes Downward API
- The transformed configuration is provided to the Envoy executable
Dynamic
Envoy receives dynamic configuration via the xDS protocol. The Gloo xDS package contains relevant code for serving dynamic configuration.
Debug
It can be useful to run the Envoy proxy, without the control-plane, as a way of validating proxy behavior. hack/envoy.yaml provides example bootstrap that can be used.
These commands should be run from this directory. If you built an image you want to use, be sure to update container parameter in the command with the new image address output in the build step.
docker run --rm -ti -p 8000:8000 -p 19000:19000 -v $(pwd)/hack/envoy.yaml:/etc/envoy/envoy.yaml:ro -l trace gcr.io/gloo-edge/gloo-envoy-wrapper:1.12.34
Envoy supports a series of command line options, which may be helpful as well. component-log-level is an especially useful option, below is how it would be used:
docker run --rm -ti -p 8000:8000 -p 19000:19000 -v $(pwd)/hack/envoy.yaml:/etc/envoy/envoy.yaml:ro -l trace gcr.io/gloo-edge/gloo-envoy-wrapper:1.12.34 --component-log-level upstream:debug,connection:trace
After running this, you should see a lot of Envoy logs:
[2022-05-19 23:21:59.465][8][info][main] [external/envoy/source/server/server.cc:381] initializing epoch 0 (base id=0, hot restart version=11.104)
[2022-05-19 23:21:59.465][8][info][main] [external/envoy/source/server/server.cc:383] statically linked extensions:
Envoy exposes an administration interface which can be used to query and modify different aspects of the server. The address of this interface is defined in the bootstrap API, though it is commonly found at port 19000.
If the above command succeeded, you should be able to visit port 19000 in your browser to explore the admin interface.
Testing
Tests are run using Ginkgo.
make test is the entrypoint for running the unit tests in the TEST_PKG
To run all tests in this project:
TEST_PKG=projects/envoyinit make test
To run a specific subset of tests, read the Ginkgo docs around focusing tests
TEST_PKG=projects/envoyinit/pkg make test
Useful Information
Other resources
To discover further information about Envoy, there are a number of great sources:
- Hoot YouTube series
- Hoot Repository
- Envoy docs
- Envoy slack
- Envoy getting started
- Envoy best practices
- Envoy Life of a Request
Determine the underlying version of Envoy
docker run --entrypoint=envoy gcr.io/gloo-edge/gloo-envoy-wrapper:1.11.11 --version
envoy version: 1f606cca72a8cd5f712803a732d0dd97828bd860/1.21.1/Distribution/RELEASE/BoringSSL
Directories