From e9b45a25234c8b5db75e3d03e73adb8a8f025d7f Mon Sep 17 00:00:00 2001 From: Jose Nino Date: Mon, 19 Sep 2016 14:07:52 -0700 Subject: [PATCH 1/5] Fix documentation on docker sandboxes --- docs/install/sandboxes.rst | 94 ++++++++++++++++++++++++++++++++-- examples/front-proxy/README.md | 38 +------------- examples/grpc-bridge/README.md | 33 +----------- 3 files changed, 92 insertions(+), 73 deletions(-) diff --git a/docs/install/sandboxes.rst b/docs/install/sandboxes.rst index cf4ae0930be3..87af80503233 100644 --- a/docs/install/sandboxes.rst +++ b/docs/install/sandboxes.rst @@ -3,7 +3,47 @@ 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. + +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-buld`` 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. + + +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 +56,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 +266,47 @@ 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. + +Building the Go service +~~~~~~~~~~~~~~~~~~~~~~~ + +To build the Go gRPC service run:: + + script/bootstrap + script/build + +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 diff --git a/examples/front-proxy/README.md b/examples/front-proxy/README.md index 29a18ceba7c3..07403466bf89 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://envoydocs-staging.lyft.net/docs/install/sandboxes.html#front-proxy) diff --git a/examples/grpc-bridge/README.md b/examples/grpc-bridge/README.md index 680328f2edd2..f5a701ff5447 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://envoydocs-staging.lyft.net/docs/install/sandboxes.html#grpc-bridge) From 90118e660fe8bad7455c29d9a7ddb84b8fdb4fb4 Mon Sep 17 00:00:00 2001 From: Jose Ulises Nino Rivera Date: Mon, 19 Sep 2016 16:42:04 -0700 Subject: [PATCH 2/5] Move section --- docs/install/sandboxes.rst | 65 +++++++++++++++++++------------------- 1 file changed, 32 insertions(+), 33 deletions(-) diff --git a/docs/install/sandboxes.rst b/docs/install/sandboxes.rst index 87af80503233..70534304574b 100644 --- a/docs/install/sandboxes.rst +++ b/docs/install/sandboxes.rst @@ -7,39 +7,6 @@ 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. -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-buld`` 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. - - Front Proxy ----------- @@ -310,3 +277,35 @@ To use the python service and sent gRPC requests:: # get a key docker-compose exec python /client/client.py get foo => bar + +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. From a9b4843ff7c71a235c8b10ae127a19609a8fcb26 Mon Sep 17 00:00:00 2001 From: Jose Ulises Nino Rivera Date: Mon, 19 Sep 2016 16:44:03 -0700 Subject: [PATCH 3/5] Change gRPC order --- docs/install/sandboxes.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/install/sandboxes.rst b/docs/install/sandboxes.rst index 70534304574b..ffef480c1a4a 100644 --- a/docs/install/sandboxes.rst +++ b/docs/install/sandboxes.rst @@ -240,7 +240,8 @@ gRPC bridge Envoy gRPC ~~~~~~~~~~ -The gRPC bridge sandbox is an example usage of Envoy's :ref:`gRPC bridge filter `. +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 @@ -249,14 +250,6 @@ 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. -Building the Go service -~~~~~~~~~~~~~~~~~~~~~~~ - -To build the Go gRPC service run:: - - script/bootstrap - script/build - Docker compose ~~~~~~~~~~~~~~ @@ -277,6 +270,14 @@ To use the python service and sent gRPC requests:: # 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 ---------------------------------------------------- From e5155ce1e834e56f1c4840be3746f9482b7261e2 Mon Sep 17 00:00:00 2001 From: Jose Ulises Nino Rivera Date: Mon, 19 Sep 2016 16:45:10 -0700 Subject: [PATCH 4/5] Public link --- examples/front-proxy/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/front-proxy/README.md b/examples/front-proxy/README.md index 07403466bf89..9d05c7755a35 100644 --- a/examples/front-proxy/README.md +++ b/examples/front-proxy/README.md @@ -1,2 +1,2 @@ To learn about this sandbox and for instructions on how to run it please head over -to the [envoy docs](https://envoydocs-staging.lyft.net/docs/install/sandboxes.html#front-proxy) +to the [envoy docs](https://lyft.github.io/envoy/docs/install/sandboxes.html#front-proxy) From 94a35335ef684ccd9c2b6799db40668834865665 Mon Sep 17 00:00:00 2001 From: Jose Ulises Nino Rivera Date: Mon, 19 Sep 2016 16:45:32 -0700 Subject: [PATCH 5/5] Public link --- examples/grpc-bridge/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/grpc-bridge/README.md b/examples/grpc-bridge/README.md index f5a701ff5447..f43907810140 100644 --- a/examples/grpc-bridge/README.md +++ b/examples/grpc-bridge/README.md @@ -1,2 +1,2 @@ To learn about this sandbox and for instructions on how to run it please head over -to the [envoy docs](https://envoydocs-staging.lyft.net/docs/install/sandboxes.html#grpc-bridge) +to the [envoy docs](https://lyft.github.io/envoy/docs/install/sandboxes.html#grpc-bridge)