Merge remote-tracking branch 'upstream/master' into validate

bazel/README.md

@@ -214,8 +214,10 @@ https://github.com/bazelbuild/bazel/issues/2805.
 
 # Coverage builds
 
-To generate coverage results, make sure you have `gcov` 3.3 in your `PATH` (or
-set `GCOVR` to point at it). Then run:
+To generate coverage results, make sure you have
+[`gcovr`](https://github.com/gcovr/gcovr) 3.3 in your `PATH` (or set `GCOVR` to
+point at it) and are using a GCC toolchain (clang does not work currently, see
+https://github.com/lyft/envoy/issues/1000). Then run:
 
 ```
 test/run_envoy_bazel_coverage.sh

docs/build.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 SCRIPT_DIR=$(dirname "$0")
-BUILD_DIR=build/docs
+BUILD_DIR=build_docs
 [[ -z "${DOCS_OUTPUT_DIR}" ]] && DOCS_OUTPUT_DIR=generated/docs
 
 rm -rf "${DOCS_OUTPUT_DIR}"

docs/configuration/cluster_manager/cluster.rst

@@ -20,7 +20,7 @@ Cluster
     "features": "...",
     "http_codec_options": "...",
     "dns_refresh_rate_ms": "...",
-    "outlier_detection": "..."
+    "outlier_detection": "{...}"
   }
 
 .. _config_cluster_manager_cluster_name:

docs/configuration/http_conn_man/route_config/route.rst

@@ -79,14 +79,14 @@ cluster_header
 
 host_redirect
   *(sometimes required, string)* Indicates that the route is a redirect rule. If there is a match,
-  a 302 redirect response will be sent which swaps the host portion of the URL with this value.
+  a 301 redirect response will be sent which swaps the host portion of the URL with this value.
   *path_redirect* can also be specified along with this option.
 
 .. _config_http_conn_man_route_table_route_path_redirect:
 
 path_redirect
   *(sometimes required, string)* Indicates that the route is a redirect rule. If there is a match,
-  a 302 redirect response will be sent which swaps the path portion of the URL with this value.
+  a 301 redirect response will be sent which swaps the path portion of the URL with this value.
   *host_redirect*  can also be specified along with this option.
 
 .. _config_http_conn_man_route_table_route_prefix_rewrite:
@@ -225,13 +225,13 @@ num_retries
 
 per_try_timeout_ms
   *(optional, integer)* specifies a non-zero timeout per retry attempt. This parameter is optional.
-  The same conditions documented for 
+  The same conditions documented for
   :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms` apply.
 
   **Note:** If left unspecified, Envoy will use the global
-  :ref:`route timeout <config_http_conn_man_route_table_route_timeout>` for the request. 
-  Consequently, when using a :ref:`5xx <config_http_filters_router_x-envoy-retry-on>` based 
-  retry policy, a request that times out will not be retried as the total timeout budget 
+  :ref:`route timeout <config_http_conn_man_route_table_route_timeout>` for the request.
+  Consequently, when using a :ref:`5xx <config_http_filters_router_x-envoy-retry-on>` based
+  retry policy, a request that times out will not be retried as the total timeout budget
   would have been exhausted.
 
 .. _config_http_conn_man_route_table_route_shadow:

docs/install/install.rst

@@ -10,5 +10,5 @@ Building and installation
   building
   installation
   ref_configs
-  sandboxes
+  sandboxes/sandboxes.rst
   tools

docs/install/sandboxes.rst → docs/install/sandboxes/front_proxy.rst

@@ -1,14 +1,7 @@
-.. _install_sandboxes:
-
-Sandboxes
-=========
-
-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.
+.. _install_sandboxes_front_proxy:
 
 Front Proxy
------------
+===========
 
 To get a flavor of what Envoy has to offer as a front proxy, we are releasing a
 `docker compose <https://docs.docker.com/compose/>`_ sandbox that deploys a front
@@ -233,88 +226,3 @@ 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 <config_http_filters_grpc_bridge>`.
-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::
-
-  $ pwd
-  ~/src/envoy/examples/grpc-bridge
-  $ script/bootstrap
-  $ script/build
-
-Docker compose
-~~~~~~~~~~~~~~
-
-To run the docker compose file, and set up both the Python and the gRPC containers
-run::
-
-  $ pwd
-  ~/src/envoy/examples/grpc-bridge
-  $ docker-compose up --build
-
-Sending requests to the Key/Value store
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To use the python service and sent gRPC requests::
-
-  $ pwd
-  ~/src/envoy/examples/grpc-bridge
-  # 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
-
-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
-  $ ./ci/run_envoy_docker.sh './ci/do_ci.sh bazel.dev'
-
-That command will take some time to run because it is compiling an envoy binary and running tests.
-
-For more information on building and different build targets, please refer to :repo:`ci/README.md`.
-
-**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 ci/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.

docs/install/sandboxes/grpc_bridge.rst

@@ -0,0 +1,52 @@
+.. _install_sandboxes_grpc_bridge:
+
+gRPC Bridge
+===========
+
+Envoy gRPC
+~~~~~~~~~~
+
+The gRPC bridge sandbox is an example usage of Envoy's
+:ref:`gRPC bridge filter <config_http_filters_grpc_bridge>`.
+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::
+
+  $ pwd
+  ~/src/envoy/examples/grpc-bridge
+  $ script/bootstrap
+  $ script/build
+
+Docker compose
+~~~~~~~~~~~~~~
+
+To run the docker compose file, and set up both the Python and the gRPC containers
+run::
+
+  $ pwd
+  ~/src/envoy/examples/grpc-bridge
+  $ docker-compose up --build
+
+Sending requests to the Key/Value store
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use the Python service and send gRPC requests::
+
+  $ pwd
+  ~/src/envoy/examples/grpc-bridge
+  # 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

docs/install/sandboxes/local_docker_build.rst

@@ -0,0 +1,35 @@
+.. _install_sandboxes_local_docker_build:
+
+Building an Envoy Docker image
+==============================
+
+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
+  $ ./ci/run_envoy_docker.sh './ci/do_ci.sh bazel.release'
+
+That command will take some time to run because it is compiling an Envoy binary and running tests.
+
+For more information on building and different build targets, please refer to :repo:`ci/README.md`.
+
+**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 ci/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.

docs/install/sandboxes/sandboxes.rst

@@ -0,0 +1,16 @@
+.. _install_sandboxes:
+
+Sandboxes
+=========
+
+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. The following sandboxes are available:
+
+.. toctree::
+  :maxdepth: 1
+
+  front_proxy
+  zipkin_tracing
+  grpc_bridge
+  local_docker_build

docs/install/sandboxes/zipkin_tracing.rst

@@ -0,0 +1,82 @@
+.. _install_sandboxes_zipkin_tracing:
+
+Zipkin Tracing
+==============
+
+The Zipkin tracing sandbox demonstrates Envoy's :ref:`request tracing <arch_overview_tracing>`
+capabilities using `Zipkin <http://zipkin.io/>`_ as the tracing provider. This sandbox
+is very similar to the front proxy architecture described above, with one difference:
+service1 makes an API call to service2 before returning a response. 
+The three containers will be deployed inside a virtual network called ``envoymesh``.
+
+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:`/examples/zipkin-tracing/docker-compose.yml`). Notice that
+all envoys are configured to collect request traces (e.g., http_connection_manager/config/tracing setup in
+:repo:`/examples/zipkin-tracing/front-envoy-zipkin.json`) and setup to propagate the spans generated
+by the Zipkin tracer to a Zipkin cluster (trace driver setup
+in :repo:`/examples/zipkin-tracing/front-envoy-zipkin.json`).
+
+Before routing a request to the appropriate service envoy or the application, Envoy will take
+care of generating the appropriate spans for tracing (parent/child/shared context spans).
+At a high-level, each span records the latency of upstream API calls as well as information
+needed to correlate the span with other related spans (e.g., the trace ID).
+
+One of the most important benefits of tracing from Envoy is that it will take care of
+propagating the traces to the Zipkin service cluster. However, in order to fully take advantage
+of tracing, the application has to propagate trace headers that Envoy generates, while making
+calls to other services. In the sandbox we have provided, the simple flask app
+(see trace function in :repo:`/examples/front-proxy/service.py`) acting as service1 propagates
+the trace headers while making an outbound call to service2.
+
+
+Running the Sandbox
+~~~~~~~~~~~~~~~~~~~
+
+The following documentation runs through the setup of an envoy cluster organized
+as is described in the image above.
+
+**Step 1: Build the sandbox**
+
+To build this sandbox example, and start the example apps run the following commands::
+
+    $ pwd
+    envoy/examples/zipkin-tracing
+    $ docker-compose up --build -d
+    $ docker-compose ps
+            Name                       Command               State      Ports
+    -------------------------------------------------------------------------------------------------------------
+    zipkintracing_service1_1      /bin/sh -c /usr/local/bin/ ...    Up       80/tcp
+    zipkintracing_service2_1      /bin/sh -c /usr/local/bin/ ...    Up       80/tcp
+    zipkintracing_front-envoy_1   /bin/sh -c /usr/local/bin/ ...    Up       0.0.0.0:8000->80/tcp, 0.0.0.0:8001->8001/tcp
+
+**Step 2: Generate some load**
+
+You can now send a request to service1 via the front-envoy as follows::
+
+    $ curl -v $(docker-machine ip default):8000/trace/1
+    *   Trying 192.168.99.100...
+    * Connected to 192.168.99.100 (192.168.99.100) port 8000 (#0)
+    > GET /trace/1 HTTP/1.1
+    > Host: 192.168.99.100:8000
+    > User-Agent: curl/7.43.0
+    > Accept: */*
+    >
+    < HTTP/1.1 200 OK
+    < content-type: text/html; charset=utf-8
+    < content-length: 89
+    < x-envoy-upstream-service-time: 1
+    < server: envoy
+    < date: Fri, 26 Aug 2016 19:39:19 GMT
+    < x-envoy-protocol-version: HTTP/1.1
+    <
+    Hello from behind Envoy (service 1)! hostname: f26027f1ce28 resolvedhostname: 172.19.0.6
+    * Connection #0 to host 192.168.99.100 left intact
+
+**Step 3: View the traces in Zipkin UI**
+
+Point your browser to http://localhost:9411 . You should see the Zipkin dashboard.
+Set the service to "front-proxy" and set the start time to a few minutes before
+the start of the test (step 2) and hit enter. You should see traces from the front-proxy.
+Click on a trace to explore the path taken by the request from front-proxy to service1
+to service2, as well as the latency incurred at each hop.

docs/intro/arch_overview/hot_restart.rst

@@ -6,7 +6,7 @@ Hot restart
 Ease of operation is one of the primary goals of Envoy. In addition to robust statistics and a local
 administration interface, Envoy has the ability to “hot” or “live” restart itself. This means that
 Envoy can fully reload itself (both code and configuration) without dropping any connections. The
-hot restart functionality has has the following general architecture:
+hot restart functionality has the following general architecture:
 
 * Statistics and some locks are kept in a shared memory region. This means that gauges will be
   consistent across both processes as restart is taking place.

docs/operations/faq/overview.rst

@@ -9,3 +9,4 @@ The purpose of this document is to link examples of commonly used deployment sce
   :maxdepth: 1
 
   zone_aware_routing
+  zipkin_tracing

docs/operations/faq/zipkin_tracing.rst

@@ -0,0 +1,7 @@
+.. _common_configuration_zipkin_tracing:
+
+Request tracing with Zipkin
+===========================
+
+Refer to the :ref:`zipkin sandbox setup <install_sandboxes_zipkin_tracing>`
+for an example of zipkin tracing configuration.

examples/BUILD

@@ -14,5 +14,8 @@ filegroup(
         "front-proxy/service-envoy.json",
         "grpc-bridge/config/s2s-grpc-envoy.json",
         "grpc-bridge/config/s2s-python-envoy.json",
+        "zipkin-tracing/front-envoy-zipkin.json",
+        "zipkin-tracing/service1-envoy-zipkin.json",
+        "zipkin-tracing/service2-envoy-zipkin.json",
     ],
 )