docs: example configurations (#38)

configs/configgen.py

@@ -20,6 +20,7 @@
 front_envoy_clusters = {
     'service1': {},
     'service2': {},
+    'service3': {},
 }
 
 # This is the set of internal services that local Envoys will route to. All services that will be

configs/envoy_double_proxy.template.json

@@ -131,9 +131,9 @@
       "ssl_context": {
         "cert_chain_file": "/etc/envoy/envoy-double-proxy.pem",
         "private_key_file": "/etc/envoy/envoy-double-proxy.key",
-        "verify_subject_alt_name": "front-proxy.yourcompany.com"
+        "verify_subject_alt_name": "front-proxy.yourcompany.net"
       },
-      "hosts": [{"url": "tcp://front-proxy.yourcompany.com:9400"}]
+      "hosts": [{"url": "tcp://front-proxy.yourcompany.net:9400"}]
     },
     {
       "name": "lightstep_saas",

configs/envoy_router.template.json

@@ -1,3 +1,51 @@
+{% import 'routing_helper.template.json' as helper with context -%}
+
 {
-  "virtual_hosts": []
+  "virtual_hosts": [
+    {
+      "name": "www",
+      "require_ssl": "all",
+      "domains": ["www.yourcompany.net"],
+      "routes": [
+        {
+          "prefix": "/foo/bar",
+          "runtime": {
+            "key": "routing.www.use_service_2",
+            "default": 0
+          },
+          {{ helper.make_route('service2') }}
+        },
+        {
+          "prefix": "/",
+          {{ helper.make_route('service1') }}
+        }
+      ]
+    },
+    {
+      "name": "www_redirect",
+      "require_ssl": "all",
+      "domains": ["wwww.yourcompany.net"],
+      "routes": [
+        {
+          "prefix": "/",
+          "host_redirect": "www.yourcompany.net"
+        }
+      ]
+    },
+    {
+      "name": "api",
+      "require_ssl": "external_only",
+      "domains": ["api.yourcompany.net"],
+      "routes": [
+        {
+          "path": "/foo/bar",
+          {{ helper.make_route('service3') }}
+        },
+        {
+          "prefix": "/",
+          {{ helper.make_route('service1') }}
+        }
+      ]
+    }
+  ]
 }

docs/install/ref_configs.rst

@@ -1,9 +1,52 @@
+.. _install_ref_configs:
+
 Reference configurations
 ========================
 
-FIXFIX
+The source distribution includes a set of example configuration templates for each of the three
+major Envoy deployment types:
+
+* :ref:`Service to service <deployment_type_service_to_service>`
+* :ref:`Front proxy <deployment_type_front_proxy>`
+* :ref:`Double proxy <deployment_type_double_proxy>`
+
+The goal of this set of example configurations is to demonstrate the full capabilities of Envoy in
+a complex deployment. All features will not be applicable to all use cases. For full documentation
+see the :ref:`configuration reference <config>`.
+
+Configuration generator
+-----------------------
+
+Envoy configurations can become relatively complicated. At Lyft we use `jinja
+<http://jinja.pocoo.org/>`_ templating to make the configurations easier to create and manage. The
+source distribution includes a version of the configuration generator that loosely approximates what
+we use at Lyft. We have also included three example configuration templates for each of the above
+three scenarios.
+
+* Generator script: :repo:`configs/configgen.py`
+* Service to service template: :repo:`configs/envoy_service_to_service.template.json`
+* Front proxy template: :repo:`configs/envoy_front_proxy.template.json`
+* Double proxy template: :repo:`configs/envoy_double_proxy.template.json`
+
+To generate the example configurations run the following from the root of the repo:
+
+.. code-block:: console
+
+  mkdir -p generated/configs
+  configs/configgen.sh generated/configs
+
+The previous command will produce three fully expanded configurations using some variables
+defined inside of `configgen.py`. See the comments inside of `configgen.py` for detailed
+information on how the different expansions work.
 
-configgen
----------
+A few notes about the example configurations:
 
-FIXFIX
+* An instance of :ref:`service discovery service <arch_overview_service_discovery_sds>` is assumed
+  to be running at `discovery.yourcompany.net`.
+* DNS for `yourcompany.net` is assumed to be setup for various things. Search the configuration
+  templates for different instances of this.
+* Tracing is configured for `LightStep <http://lightstep.com/>`_. To disable this delete the
+  :ref:`tracing configuration <config_tracing>`.
+* The configuration demonstrates the use of a :ref:`global rate limiting service
+  <arch_overview_rate_limit>`. To disable this delete the :ref:`rate limit configuration
+  <config_rate_limit_service>`.

docs/intro/deployment_types/double_proxy.rst

@@ -1,3 +1,5 @@
+.. _deployment_type_double_proxy:
+
 Service to service, front proxy, and double proxy
 -------------------------------------------------
 
@@ -19,4 +21,6 @@ ordinarily would not be trustable (such as the x-forwaded-for HTTP header).
 Configuration template
 ^^^^^^^^^^^^^^^^^^^^^^
 
-FIXFIX
+The source distribution includes an example double proxy configuration that is very similar to
+the version that Lyft runs in production. See :ref:`here <install_ref_configs>` for more
+information.

docs/intro/deployment_types/front_proxy.rst

@@ -21,4 +21,6 @@ reverse proxy provides the following features:
 Configuration template
 ^^^^^^^^^^^^^^^^^^^^^^
 
-FIXFIX
+The source distribution includes an example front proxy configuration that is very similar to
+the version that Lyft runs in production. See :ref:`here <install_ref_configs>` for more
+information.

docs/intro/deployment_types/service_to_service.rst

@@ -57,4 +57,6 @@ load balancing, statistics gathering, etc.
 Configuration template
 ^^^^^^^^^^^^^^^^^^^^^^
 
-FIXFIX
+The source distribution includes an example service to service configuration that is very similar to
+the version that Lyft runs in production. See :ref:`here <install_ref_configs>` for more
+information.