From daf57a8c58074c78699b26e47f0c9e899217b3f4 Mon Sep 17 00:00:00 2001
From: Matt Klein <mattklein123@users.noreply.github.com>
Date: Tue, 16 Aug 2016 15:21:34 -0700
Subject: [PATCH] docs: route matching details (#17)

---
 .../http_conn_man/route_config/route_config.rst      |  1 +
 .../http_conn_man/route_config/route_matching.rst    | 12 ++++++++++++
 2 files changed, 13 insertions(+)
 create mode 100644 docs/configuration/http_conn_man/route_config/route_matching.rst

diff --git a/docs/configuration/http_conn_man/route_config/route_config.rst b/docs/configuration/http_conn_man/route_config/route_config.rst
index 628844f26557..928eb2990284 100644
--- a/docs/configuration/http_conn_man/route_config/route_config.rst
+++ b/docs/configuration/http_conn_man/route_config/route_config.rst
@@ -53,3 +53,4 @@ response_headers_to_remove
   vhost
   route
   vcluster
+  route_matching
diff --git a/docs/configuration/http_conn_man/route_config/route_matching.rst b/docs/configuration/http_conn_man/route_config/route_matching.rst
new file mode 100644
index 000000000000..2cda7e1c5e5e
--- /dev/null
+++ b/docs/configuration/http_conn_man/route_config/route_matching.rst
@@ -0,0 +1,12 @@
+Route matching
+==============
+
+When Envoy matches a route, it uses the following procedure:
+
+#. The HTTP request's *host* or *:authority* header is matched to a :ref:`virtual host
+   <config_http_conn_man_route_table_vhost>`.
+#. Each :ref:`route entry <config_http_conn_man_route_table_route>` in the virtual host is checked,
+   *in order*. If there is a match, the route is used and no further route checks are made.
+#. Independently, each :ref:`virtual cluster <config_http_conn_man_route_table_vcluster>` in the
+   virtual host is checked, *in order*. If there is a match, the virtual cluster is used and no 
+   further virtual cluster checks are made.