From 2e60a86ed1f4cbfc3eecda7b2350324a994a0c98 Mon Sep 17 00:00:00 2001 From: Matt Klein Date: Thu, 25 Aug 2016 08:04:33 -0700 Subject: [PATCH] docs: example configurations (#38) --- configs/configgen.py | 1 + configs/envoy_double_proxy.template.json | 4 +- configs/envoy_router.template.json | 50 +++++++++++++++++- docs/install/ref_configs.rst | 51 +++++++++++++++++-- docs/intro/deployment_types/double_proxy.rst | 6 ++- docs/intro/deployment_types/front_proxy.rst | 4 +- .../deployment_types/service_to_service.rst | 4 +- 7 files changed, 110 insertions(+), 10 deletions(-) diff --git a/configs/configgen.py b/configs/configgen.py index 5689dedef970..faccbeaab626 100755 --- a/configs/configgen.py +++ b/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 diff --git a/configs/envoy_double_proxy.template.json b/configs/envoy_double_proxy.template.json index 5f51eeacaed6..c7e3e3d6184f 100644 --- a/configs/envoy_double_proxy.template.json +++ b/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", diff --git a/configs/envoy_router.template.json b/configs/envoy_router.template.json index 4400f0ac360a..115d8a621d87 100644 --- a/configs/envoy_router.template.json +++ b/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') }} + } + ] + } + ] } diff --git a/docs/install/ref_configs.rst b/docs/install/ref_configs.rst index 9f56be3caaea..4a8dbe2f0e3a 100644 --- a/docs/install/ref_configs.rst +++ b/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 ` +* :ref:`Front proxy ` +* :ref:`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 `. + +Configuration generator +----------------------- + +Envoy configurations can become relatively complicated. At Lyft we use `jinja +`_ 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 ` 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 `_. To disable this delete the + :ref:`tracing configuration `. +* The configuration demonstrates the use of a :ref:`global rate limiting service + `. To disable this delete the :ref:`rate limit configuration + `. diff --git a/docs/intro/deployment_types/double_proxy.rst b/docs/intro/deployment_types/double_proxy.rst index 329c3f2a2dc2..55a67cdf6cd0 100644 --- a/docs/intro/deployment_types/double_proxy.rst +++ b/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 ` for more +information. diff --git a/docs/intro/deployment_types/front_proxy.rst b/docs/intro/deployment_types/front_proxy.rst index c4da63f5bcf2..f89e8cb17da5 100644 --- a/docs/intro/deployment_types/front_proxy.rst +++ b/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 ` for more +information. diff --git a/docs/intro/deployment_types/service_to_service.rst b/docs/intro/deployment_types/service_to_service.rst index eae43bb50a85..1eafdae72997 100644 --- a/docs/intro/deployment_types/service_to_service.rst +++ b/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 ` for more +information.