diff --git a/docs/install/sandboxes.rst b/docs/install/sandboxes.rst index cf4ae0930be3..ffef480c1a4a 100644 --- a/docs/install/sandboxes.rst +++ b/docs/install/sandboxes.rst @@ -3,7 +3,14 @@ Sandboxes ========= -To get a flavor of what Envoy has to offer, we are releasing a +The docker-compose sandboxes give you different environments to test out Envoy's +features. As we gauge people's interests we will add more sandboxes demonstrating +different features. + +Front Proxy +----------- + +To get a flavor of what Envoy has to offer as a front proxy, we are releasing a `docker compose `_ sandbox that deploys a front envoy and a couple of services (simple flask apps) colocated with a running service envoy. The three containers will be deployed inside a virtual network @@ -16,16 +23,16 @@ Below you can see a graphic showing the docker compose deployment: All incoming requests are routed via the front envoy, which is acting as a reverse proxy sitting on the edge of the ``envoymesh`` network. Port ``80`` is mapped to port ``8000`` by docker compose -(see :repo:`/example/docker-compose.yml>`). Moreover, notice +(see :repo:`/examples/front-proxy/docker-compose.yml`). Moreover, notice that all traffic routed by the front envoy to the service containers is actually routed to the -service envoys (routes setup in :repo:`/example/front-envoy.json>`). In turn the service +service envoys (routes setup in :repo:`/examples/front-proxy/front-envoy.json`). In turn the service envoys route the request to the flask app via the loopback address (routes setup in -:repo:`/example/service-envoy.json>`). This setup +:repo:`/examples/front-proxy/service-envoy.json`). This setup illustrates the advantage of running service envoys collocated with your services: all requests are handled by the service envoy, and efficiently routed to your services. Running the Sandbox -------------------- +~~~~~~~~~~~~~~~~~~~ The following documentation runs through the setup of an envoy cluster organized as is described in the image above. @@ -226,3 +233,80 @@ statistics. For example inside ``frontenvoy`` we can get:: Notice that we can get the number of members of upstream clusters, number of requests fulfilled by them, information about http ingress, and a plethora of other useful stats. + +gRPC bridge +----------- + +Envoy gRPC +~~~~~~~~~~ + +The gRPC bridge sandbox is an example usage of Envoy's +:ref:`gRPC bridge filter `. +Included in the sandbox is a gRPC in memory Key/Value store with a Python HTTP +client. The Python client makes HTTP/1 requests through the Envoy sidecar +process which are upgraded into HTTP/2 gRPC requests. Response trailers are then +buffered and sent back to the client as a HTTP/1 header payload. + +Another Envoy feature demonstrated in this example is Envoy's ability to do authority +base routing via its route configuration. + +Docker compose +~~~~~~~~~~~~~~ + +To run the docker compose file, and set up both the Python and the gRPC containers +run:: + + docker-compose up --build + +Sending requests to the Key/Value store +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To use the python service and sent gRPC requests:: + + # set a key + docker-compose exec python /client/client.py set foo bar + => setf foo to bar + + # get a key + docker-compose exec python /client/client.py get foo + => bar + +Building the Go service +~~~~~~~~~~~~~~~~~~~~~~~ + +To build the Go gRPC service run:: + + script/bootstrap + script/build + +Locally building a docker image with an envoy binary +---------------------------------------------------- + +The following steps guide you through building your own envoy binary, and +putting that in a clean ubuntu container. + +**Step 1: Build Envoy** + +Using ``lyft/envoy-build`` you will compile envoy. +This image has all software needed to build envoy. From your envoy directory:: + + $ pwd + src/envoy + $ docker run -t -i -v :/source lyft/envoy-build:latest /bin/bash -c "cd /source && ci/do_ci.sh normal" + +That command will take some time to run because it is compiling an envoy binary. + +**Step 2: Build image with only envoy binary** + +In this step we'll build an image that only has the envoy binary, and none +of the software used to build it.:: + + $ pwd + src/envoy/ + $ docker build -f example/Dockerfile-envoy-image -t envoy . + +Now you can use this ``envoy`` image to build the any of the sandboxes if you change +the ``FROM`` line in any dockerfile. + +This will be particularly useful if you are interested in modifying envoy, and testing +your changes. diff --git a/examples/front-proxy/README.md b/examples/front-proxy/README.md index 29a18ceba7c3..9d05c7755a35 100644 --- a/examples/front-proxy/README.md +++ b/examples/front-proxy/README.md @@ -1,38 +1,2 @@ To learn about this sandbox and for instructions on how to run it please head over -to the envoy docs - -### Building the Docker image - -The `lyft/envoy` image is a docker image made using `build-envoy/Dockerfile-envoy` -it copies a precompiled envoy binary into a docker image, and installs `curl` -and `pip`. - -The following steps guide you through building your own envoy binary, and -putting that in a clean ubuntu container. - -#### Step 1: Build Envoy - -Using `lyft/envoy-buld` you will compile envoy. -This image has all software needed to build envoy. From your envoy directory: - -```shell -$ pwd -src/envoy -$ docker run -t -i -v :/source lyft/envoy-build:latest /bin/bash -c "cd /source && ci/do_ci.sh normal" -``` - -That command will take some time to run because it is compiling an envoy binary. - -#### Step 2: Build image with only envoy binary - -In this step we'll build an image that only has the envoy binary, and none -of the software used to build it. - -```shell -$ pwd -src/envoy/ -$ docker build -f example/Dockerfile-envoy-image -t envoy . -``` - -Now you can use this `envoy` image to build the demo if you change the `FROM` -line in `Dockerfile-frontenvoy` and `Dockerfile-service` +to the [envoy docs](https://lyft.github.io/envoy/docs/install/sandboxes.html#front-proxy) diff --git a/examples/grpc-bridge/README.md b/examples/grpc-bridge/README.md index 680328f2edd2..f43907810140 100644 --- a/examples/grpc-bridge/README.md +++ b/examples/grpc-bridge/README.md @@ -1,31 +1,2 @@ -# envoy-grpc - -This is an example usage of the Envoy [gRPC bridge filter](https://lyft.github.io/envoy/docs/configuration/http_filters/grpc_http1_bridge_filter.html#config-http-filters-grpc-bridge). Included is a gRPC in memory Key/Value store with a Python HTTP client. The Python client makes HTTP/1 requests through the Envoy sidecar process which are upgraded into HTTP/2 gRPC requests. Response trailers are then buffered and sent back to the client as a HTTP/1 header payload. - -## Building the Go service - -```bash -script/bootstrap -script/build -``` - -## Docker compose - -To run the docker compose file, and set up both the Python and the gRPC containers -run: - -```bash -docker-compose up --build -``` - -## Sending requests to the Key/Value store - -```bash -# set a key -docker-compose exec python /client/client.py set foo bar -=> setf foo to bar - -# get a key -docker-compose exec python /client/client.py get foo -=> bar -``` +To learn about this sandbox and for instructions on how to run it please head over +to the [envoy docs](https://lyft.github.io/envoy/docs/install/sandboxes.html#grpc-bridge)