Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: example configurations #38

Merged
merged 3 commits into from
Aug 25, 2016
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions configs/configgen.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions configs/envoy_double_proxy.template.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
50 changes: 49 additions & 1 deletion configs/envoy_router.template.json
Original file line number Diff line number Diff line change
@@ -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') }}
}
]
}
]
}
51 changes: 47 additions & 4 deletions docs/install/ref_configs.rst
Original file line number Diff line number Diff line change
@@ -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 manage. The
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what is '_' here for?
to 'create and manage' ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's sphinx syntax for external links. See docs.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's a typo, will fix.

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>`.
6 changes: 5 additions & 1 deletion docs/intro/deployment_types/double_proxy.rst
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _deployment_type_double_proxy:

Service to service, front proxy, and double proxy
-------------------------------------------------

Expand All @@ -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.
4 changes: 3 additions & 1 deletion docs/intro/deployment_types/front_proxy.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 3 additions & 1 deletion docs/intro/deployment_types/service_to_service.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.