Chiebot-Mirror
/
data-plane-api
mirror of https://github.com/envoyproxy/data-plane-api.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

Reconcile envoyproxy/data-plane-api and envoyproxy/envoy (#3036)

Browse Source 
This PR implements the planned merge of envoyproxy/data-plane-api into envoyproxy/envoy as described in #2934 and https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!topic/envoy-dev/KcVHFH-zQwQ.

Risk Level: Medium (there might be unintentional breakage of dependent builds).
Testing: CI passes. There is now an additional bazel.api do_ci.sh target to build and run API tests.

Fixes #2934.

Signed-off-by: Harvey Tuch <htuch@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ 1fdb6386c4bb42748530d7a9bf58ded644d77749
pull/619/head
data-plane-api(CircleCI) 7 years ago
parent 73cfd4a76d
commit 34f3b9da45
202 changed files with 27 additions and 14281 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 5
      API_OVERVIEW.md
  2. 3
      BUILD
  3. 69
      CONTRIBUTING.md
  4. 1
      VERSION
  5. 2
      bazel/api_build_system.bzl
  6. 24
      docs/README.md
  7. 94
      docs/build.sh
  8. 221
      docs/conf.py
  9. 32
      docs/publish.sh
  10. 19
      docs/requirements.txt
  11. 4
      docs/root/_static/docker_compose_v0.1.svg
  12. 4
      docs/root/_static/double_proxy.svg
  13. 4
      docs/root/_static/front_proxy.svg
  14. 0
      docs/root/_static/placeholder
  15. 4
      docs/root/_static/service_to_service.svg
  16. 20
      docs/root/about_docs.rst
  17. 181
      docs/root/api-v1/access_log.rst
  18. 27
      docs/root/api-v1/admin.rst
  19. 19
      docs/root/api-v1/api.rst
  20. 45
      docs/root/api-v1/cluster_manager/cds.rst
  21. 205
      docs/root/api-v1/cluster_manager/cluster.rst
  22. 64
      docs/root/api-v1/cluster_manager/cluster_circuit_breakers.rst
  23. 91
      docs/root/api-v1/cluster_manager/cluster_hc.rst
  24. 51
      docs/root/api-v1/cluster_manager/cluster_manager.rst
  25. 101
      docs/root/api-v1/cluster_manager/cluster_outlier_detection.rst
  26. 26
      docs/root/api-v1/cluster_manager/cluster_ring_hash_lb_config.rst
  27. 82
      docs/root/api-v1/cluster_manager/cluster_ssl.rst
  28. 15
      docs/root/api-v1/cluster_manager/outlier.rst
  29. 85
      docs/root/api-v1/cluster_manager/sds.rst
  30. 24
      docs/root/api-v1/http_filters/buffer_filter.rst
  31. 13
      docs/root/api-v1/http_filters/cors_filter.rst
  32. 19
      docs/root/api-v1/http_filters/dynamodb_filter.rst
  33. 94
      docs/root/api-v1/http_filters/fault_filter.rst
  34. 13
      docs/root/api-v1/http_filters/grpc_http1_bridge_filter.rst
  35. 64
      docs/root/api-v1/http_filters/grpc_json_transcoder_filter.rst
  36. 13
      docs/root/api-v1/http_filters/grpc_web_filter.rst
  37. 28
      docs/root/api-v1/http_filters/health_check_filter.rst
  38. 8
      docs/root/api-v1/http_filters/http_filters.rst
  39. 21
      docs/root/api-v1/http_filters/lua_filter.rst
  40. 39
      docs/root/api-v1/http_filters/rate_limit_filter.rst
  41. 28
      docs/root/api-v1/http_filters/router_filter.rst
  42. 56
      docs/root/api-v1/http_filters/squash_filter.rst
  43. 49
      docs/root/api-v1/listeners/lds.rst
  44. 238
      docs/root/api-v1/listeners/listeners.rst
  45. 47
      docs/root/api-v1/network_filters/client_ssl_auth_filter.rst
  46. 13
      docs/root/api-v1/network_filters/echo_filter.rst
  47. 260
      docs/root/api-v1/network_filters/http_conn_man.rst
  48. 53
      docs/root/api-v1/network_filters/mongo_proxy_filter.rst
  49. 8
      docs/root/api-v1/network_filters/network_filters.rst
  50. 40
      docs/root/api-v1/network_filters/rate_limit_filter.rst
  51. 46
      docs/root/api-v1/network_filters/redis_proxy_filter.rst
  52. 126
      docs/root/api-v1/network_filters/tcp_proxy_filter.rst
  53. 28
      docs/root/api-v1/rate_limit.rst
  54. 183
      docs/root/api-v1/route_config/rate_limits.rst
  55. 63
      docs/root/api-v1/route_config/rds.rst
  56. 553
      docs/root/api-v1/route_config/route.rst
  57. 92
      docs/root/api-v1/route_config/route_config.rst
  58. 47
      docs/root/api-v1/route_config/vcluster.rst
  59. 84
      docs/root/api-v1/route_config/vhost.rst
  60. 34
      docs/root/api-v1/runtime.rst
  61. 69
      docs/root/api-v1/tracing.rst
  62. 16
      docs/root/api-v2/api.rst
  63. 12
      docs/root/api-v2/bootstrap/bootstrap.rst
  64. 13
      docs/root/api-v2/clusters/clusters.rst
  65. 15
      docs/root/api-v2/common_messages/common_messages.rst
  66. 11
      docs/root/api-v2/config/filter/filter.rst
  67. 8
      docs/root/api-v2/config/filter/http/http.rst
  68. 8
      docs/root/api-v2/config/filter/network/network.rst
  69. 9
      docs/root/api-v2/http_routes/http_routes.rst
  70. 9
      docs/root/api-v2/listeners/listeners.rst
  71. 9
      docs/root/api-v2/types/types.rst
  72. 208
      docs/root/configuration/access_log.rst
  73. 31
      docs/root/configuration/cluster_manager/cds.rst
  74. 17
      docs/root/configuration/cluster_manager/cluster_circuit_breakers.rst
  75. 73
      docs/root/configuration/cluster_manager/cluster_hc.rst
  76. 17
      docs/root/configuration/cluster_manager/cluster_manager.rst
  77. 131
      docs/root/configuration/cluster_manager/cluster_runtime.rst
  78. 218
      docs/root/configuration/cluster_manager/cluster_stats.rst
  79. 22
      docs/root/configuration/configuration.rst
  80. 35
      docs/root/configuration/http_conn_man/header_sanitizing.rst
  81. 482
      docs/root/configuration/http_conn_man/headers.rst
  82. 20
      docs/root/configuration/http_conn_man/http_conn_man.rst
  83. 30
      docs/root/configuration/http_conn_man/rds.rst
  84. 19
      docs/root/configuration/http_conn_man/route_matching.rst
  85. 36
      docs/root/configuration/http_conn_man/runtime.rst
  86. 126
      docs/root/configuration/http_conn_man/stats.rst
  87. 145
      docs/root/configuration/http_conn_man/traffic_splitting.rst
  88. 23
      docs/root/configuration/http_filters/buffer_filter.rst
  89. 12
      docs/root/configuration/http_filters/cors_filter.rst
  90. 71
      docs/root/configuration/http_filters/dynamodb_filter.rst
  91. 92
      docs/root/configuration/http_filters/fault_filter.rst
  92. 50
      docs/root/configuration/http_filters/grpc_http1_bridge_filter.rst
  93. 37
      docs/root/configuration/http_filters/grpc_json_transcoder_filter.rst
  94. 11
      docs/root/configuration/http_filters/grpc_web_filter.rst
  95. 51
      docs/root/configuration/http_filters/gzip_filter.rst
  96. 17
      docs/root/configuration/http_filters/health_check_filter.rst
  97. 22
      docs/root/configuration/http_filters/http_filters.rst
  98. 41
      docs/root/configuration/http_filters/ip_tagging_filter.rst
  99. 417
      docs/root/configuration/http_filters/lua_filter.rst
  100. 126
      docs/root/configuration/http_filters/rate_limit_filter.rst
  101. Some files were not shown because too many files have changed in this diff Show More

5
API_OVERVIEW.md
Unescape View File

@ -1,4 +1,3 @@
# Envoy v2 APIs for developers
## Goals
@ -27,9 +26,7 @@ See
[here](https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/v2_overview.html#status)
for the current status of the v2 APIs.
See
[here](https://github.com/envoyproxy/data-plane-api/blob/master/CONTRIBUTING.md#api-changes)
for the v2 API change process.
See [here](CONTRIBUTING.md#api-changes) for the v2 API change process.
## Principles

3
BUILD
Unescape View File

@ -1,3 +0,0 @@
licenses(["notice"]) # Apache 2
exports_files(["VERSION"])

69
CONTRIBUTING.md
Unescape View File

@ -4,65 +4,12 @@
All API changes should follow the [style guide](STYLE.md).
The following high level procedure is used to make Envoy changes that require API changes.
1. Create a PR in this repo for the API/configuration changes. (If it helps to discuss the
configuration changes in the context of a code change, it is acceptable to point a code
change at a temporary fork of this repo so it passes tests).
Run the automated formatting checks on your change before submitting the PR:
```
./ci/run_envoy_docker.sh './ci/do_ci.sh check_format'
```
If the `check_format` script reports any problems, you can fix them manually or run
the companion `fix_format` script:
```
./ci/run_envoy_docker.sh './ci/do_ci.sh fix_format'
```
Before building the docs
2. Bazel can be used to build/test locally.
1. Directly on Linux:
```
bazel build //envoy/...
bazel test //test/... //tools/...
```
2. Using docker:
```
./ci/run_envoy_docker.sh './ci/do_ci.sh bazel.test'
./ci/run_envoy_docker.sh './ci/do_ci.sh bazel.docs'
```
*Note: New .proto files should be also included to [build.sh](https://github.com/envoyproxy/data-plane-api/blob/4e533f22baced334c4aba68fb60c5fc439f0fe9c/docs/build.sh#L28) and
[BUILD](https://github.com/envoyproxy/data-plane-api/blob/master/docs/BUILD) in order to get the RSTs generated.*
3. All configuration changes should have temporary associated documentation. Fields should be
hidden from the documentation via the `[#not-implemented-hide:]` comment tag. E.g.,
```
// [#not-implemented-hide:] Some new cool field that I'm going to implement and then
// come back and doc for real!
string foo_field = 3;
```
Additionally, [constraints](https://github.com/lyft/protoc-gen-validate/blob/master/README.md)
should be specified for new fields if applicable. E.g.,
```
string endpoint = 2 [(validate.rules).message.required = true];
```
4. Next, the feature should be implemented in Envoy. New versions of data-plane-api are brought
in via editing [this](https://github.com/envoyproxy/envoy/blob/master/bazel/repository_locations.bzl)
file.
5. Once (4) is completed, come back here and unhide the field from documentation and complete all
documentation around the new feature. This may include architecture docs, etc. Optimally, the
PR for documentation should be reviewed at the same time that the feature PR is reviewed in
the Envoy repository. See the following section for tips on writing documentation.
API changes are regular PRs in https://github.com/envoyproxy/envoy for the API/configuration
changes. They may be as part of a larger implementation PR. Please follow the standard Bazel and CI
process for validating build/test sanity of `api/` before submitting a PR.
*Note: New .proto files should be also included to [build.sh](https://github.com/envoyproxy/envoy/blob/master/docs/build.sh) and
[BUILD](https://github.com/envoyproxy/envoy/blob/master/api/docs/BUILD) in order to get the RSTs generated.*
## Documentation changes
@ -73,7 +20,7 @@ documentation.
### Building documentation locally
The documentation can be built locally in the root of this repo via:
The documentation can be built locally in the root of https://github.com/envoyproxy/envoy via:
```
docs/build.sh
@ -82,7 +29,7 @@ docs/build.sh
Or to use a hermetic docker container:
```
./ci/run_envoy_docker.sh './ci/do_ci.sh bazel.docs'
./ci/run_envoy_docker.sh './ci/do_ci.sh docs'
```
This process builds RST documentation directly from the proto files, merges it with the static RST

1
VERSION
Unescape View File

@ -1 +0,0 @@
1.7.0-dev

2
bazel/api_build_system.bzl
Unescape View File

@ -80,7 +80,7 @@ def api_go_grpc_library(name, proto, deps = []):
# from api_proto_library.
def api_proto_library(name, visibility = ["//visibility:private"], srcs = [], deps = [], has_services = 0, require_py = 1):
# This is now vestigial, since there are no direct consumers in
# data-plane-api. However, we want to maintain native proto_library support
# the data plane API. However, we want to maintain native proto_library support
# in the proto graph to (1) support future C++ use of native rules with
# cc_proto_library (or some Bazel aspect that works on proto_library) when
# it can play well with the PGV plugin and (2) other language support that

24
docs/README.md
Unescape View File

@ -1,24 +0,0 @@
# Developer-local docs build
```bash
./docs/build.sh
```
The output can be found in `generated/docs`.
# How the Envoy website and docs are updated
The Envoy website, and docs are automatically built, and pushed on every commit
to master. This process is handled by Travis CI with the
[`publish.sh`](https://github.com/envoyproxy/envoy/blob/master/docs/publish.sh) script.
In order to have this automatic process there is an encrypted ssh key at the root
of the envoy repo (`.publishdocskey.enc`). This key was encrypted with Travis CLI
and can only be decrypted by commits initiated in the Envoy repo, not PRs that are
submitted from forks. This is the case because only PRs initiated in the Envoy
repo have access to the secure environment variables (`encrypted_b1a4cc52fa4a_iv`,
`encrypted_b1a4cc52fa4a_key`) [used to decrypt the key.](https://docs.travis-ci.com/user/pull-requests#Pull-Requests-and-Security-Restrictions)
The key only has write access to the Envoy repo. If the key, or the variables
used to decrypt it are ever compromised, delete the key immediately from the
Envoy repo in `Settings > Deploy keys`.

94
docs/build.sh
Unescape View File

@ -1,94 +0,0 @@
#!/bin/bash
set -e
SCRIPT_DIR=$(dirname "$0")
BUILD_DIR=build_docs
[[ -z "${DOCS_OUTPUT_DIR}" ]] && DOCS_OUTPUT_DIR=generated/docs
[[ -z "${GENERATED_RST_DIR}" ]] && GENERATED_RST_DIR=generated/rst
rm -rf "${DOCS_OUTPUT_DIR}"
mkdir -p "${DOCS_OUTPUT_DIR}"
rm -rf "${GENERATED_RST_DIR}"
mkdir -p "${GENERATED_RST_DIR}"
if [ ! -d "${BUILD_DIR}"/venv ]; then
virtualenv "${BUILD_DIR}"/venv --no-site-packages --python=python2.7
"${BUILD_DIR}"/venv/bin/pip install -r "${SCRIPT_DIR}"/requirements.txt
fi
source "${BUILD_DIR}"/venv/bin/activate
bazel --batch build ${BAZEL_BUILD_OPTIONS} //docs:protos --aspects \
tools/protodoc/protodoc.bzl%proto_doc_aspect --output_groups=rst --action_env=CPROFILE_ENABLED
# These are the protos we want to put in docs, this list will grow.
# TODO(htuch): Factor this out of this script.
PROTO_RST="
/envoy/api/v2/core/address/envoy/api/v2/core/address.proto.rst
/envoy/api/v2/core/base/envoy/api/v2/core/base.proto.rst
/envoy/api/v2/core/config_source/envoy/api/v2/core/config_source.proto.rst
/envoy/api/v2/core/grpc_service/envoy/api/v2/core/grpc_service.proto.rst
/envoy/api/v2/core/health_check/envoy/api/v2/core/health_check.proto.rst
/envoy/api/v2/core/protocol/envoy/api/v2/core/protocol.proto.rst
/envoy/api/v2/auth/cert/envoy/api/v2/auth/cert.proto.rst
/envoy/api/v2/eds/envoy/api/v2/eds.proto.rst
/envoy/api/v2/endpoint/endpoint/envoy/api/v2/endpoint/endpoint.proto.rst
/envoy/api/v2/cds/envoy/api/v2/cds.proto.rst
/envoy/api/v2/cluster/outlier_detection/envoy/api/v2/cluster/outlier_detection.proto.rst
/envoy/api/v2/cluster/circuit_breaker/envoy/api/v2/cluster/circuit_breaker.proto.rst
/envoy/api/v2/rds/envoy/api/v2/rds.proto.rst
/envoy/api/v2/route/route/envoy/api/v2/route/route.proto.rst
/envoy/api/v2/lds/envoy/api/v2/lds.proto.rst
/envoy/api/v2/listener/listener/envoy/api/v2/listener/listener.proto.rst
/envoy/api/v2/ratelimit/ratelimit/envoy/api/v2/ratelimit/ratelimit.proto.rst
/envoy/config/bootstrap/v2/bootstrap/envoy/config/bootstrap/v2/bootstrap.proto.rst
/envoy/api/v2/discovery/envoy/api/v2/discovery.proto.rst
/envoy/config/ratelimit/v2/rls/envoy/config/ratelimit/v2/rls.proto.rst
/envoy/config/metrics/v2/metrics_service/envoy/config/metrics/v2/metrics_service.proto.rst
/envoy/config/metrics/v2/stats/envoy/config/metrics/v2/stats.proto.rst
/envoy/config/trace/v2/trace/envoy/config/trace/v2/trace.proto.rst
/envoy/config/filter/accesslog/v2/accesslog/envoy/config/filter/accesslog/v2/accesslog.proto.rst
/envoy/config/filter/fault/v2/fault/envoy/config/filter/fault/v2/fault.proto.rst
/envoy/config/filter/http/buffer/v2/buffer/envoy/config/filter/http/buffer/v2/buffer.proto.rst
/envoy/config/filter/http/fault/v2/fault/envoy/config/filter/http/fault/v2/fault.proto.rst
/envoy/config/filter/http/gzip/v2/gzip/envoy/config/filter/http/gzip/v2/gzip.proto.rst
/envoy/config/filter/http/health_check/v2/health_check/envoy/config/filter/http/health_check/v2/health_check.proto.rst
/envoy/config/filter/http/ip_tagging/v2/ip_tagging/envoy/config/filter/http/ip_tagging/v2/ip_tagging.proto.rst
/envoy/config/filter/http/lua/v2/lua/envoy/config/filter/http/lua/v2/lua.proto.rst
/envoy/config/filter/http/rate_limit/v2/rate_limit/envoy/config/filter/http/rate_limit/v2/rate_limit.proto.rst
/envoy/config/filter/http/router/v2/router/envoy/config/filter/http/router/v2/router.proto.rst
/envoy/config/filter/http/squash/v2/squash/envoy/config/filter/http/squash/v2/squash.proto.rst
/envoy/config/filter/http/transcoder/v2/transcoder/envoy/config/filter/http/transcoder/v2/transcoder.proto.rst
/envoy/config/filter/network/client_ssl_auth/v2/client_ssl_auth/envoy/config/filter/network/client_ssl_auth/v2/client_ssl_auth.proto.rst
/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto.rst
/envoy/config/filter/network/mongo_proxy/v2/mongo_proxy/envoy/config/filter/network/mongo_proxy/v2/mongo_proxy.proto.rst
/envoy/config/filter/network/rate_limit/v2/rate_limit/envoy/config/filter/network/rate_limit/v2/rate_limit.proto.rst
/envoy/config/filter/network/redis_proxy/v2/redis_proxy/envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto.rst
/envoy/config/filter/network/tcp_proxy/v2/tcp_proxy/envoy/config/filter/network/tcp_proxy/v2/tcp_proxy.proto.rst
/envoy/type/percent/envoy/type/percent.proto.rst
/envoy/type/range/envoy/type/range.proto.rst
"
# Dump all the generated RST so they can be added to PROTO_RST easily.
find -L bazel-bin -name "*.proto.rst"
# Only copy in the protos we care about and know how to deal with in protodoc.
for p in $PROTO_RST
do
DEST="${GENERATED_RST_DIR}/api-v2/$(sed -e 's#/envoy\/.*/envoy/##' <<< "$p")"
mkdir -p "$(dirname "${DEST}")"
cp -f bazel-bin/"${p}" "$(dirname "${DEST}")"
[ -n "${CPROFILE_ENABLED}" ] && cp -f bazel-bin/"${p}".profile "$(dirname "${DEST}")"
done
rsync -av "${SCRIPT_DIR}"/root/ "${SCRIPT_DIR}"/conf.py "${GENERATED_RST_DIR}"
BUILD_SHA=$(git rev-parse HEAD)
VERSION_NUM=$(cat VERSION)
[[ -z "${ENVOY_DOCS_VERSION_STRING}" ]] && ENVOY_DOCS_VERSION_STRING="${VERSION_NUM}"-data-plane-api-"${BUILD_SHA:0:6}"
[[ -z "${ENVOY_DOCS_RELEASE_LEVEL}" ]] && ENVOY_DOCS_RELEASE_LEVEL=pre-release
export ENVOY_DOCS_VERSION_STRING ENVOY_DOCS_RELEASE_LEVEL
sphinx-build -W -b html "${GENERATED_RST_DIR}" "${DOCS_OUTPUT_DIR}"

221
docs/conf.py
Unescape View File

@ -1,221 +0,0 @@
# -*- coding: utf-8 -*-
#
# envoy documentation build configuration file, created by
# sphinx-quickstart on Sat May 28 10:51:27 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sphinx_rtd_theme
import sys
import os
def setup(app):
app.add_config_value('release_level', '', 'env')
if not os.environ.get('ENVOY_DOCS_RELEASE_LEVEL'):
raise Exception("ENVOY_DOCS_RELEASE_LEVEL env var must be defined")
release_level = os.environ['ENVOY_DOCS_RELEASE_LEVEL']
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinxcontrib.httpdomain', 'sphinx.ext.extlinks', 'sphinx.ext.ifconfig']
extlinks = {
'repo': ('https://github.com/envoyproxy/envoy/blob/master/%s', ''),
'api': ('https://github.com/envoyproxy/data-plane-api/blob/master/%s', ''),
}
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'envoy'
copyright = u'2016-2018, Envoy Project Authors'
author = u'Envoy Project Authors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
if not os.environ.get('ENVOY_DOCS_VERSION_STRING'):
raise Exception("ENVOY_DOCS_VERSION_STRING env var must be defined")
# The short X.Y version.
version = os.environ['ENVOY_DOCS_VERSION_STRING']
# The full version, including alpha/beta/rc tags.
release = os.environ['ENVOY_DOCS_VERSION_STRING']
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', '_venv', 'Thumbs.db', '.DS_Store']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#html_title = u'envoy v1.0.0'
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
html_favicon = 'favicon.ico'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#html_last_updated_fmt = None
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'envoydoc'

32
docs/publish.sh
Unescape View File

@ -1,32 +0,0 @@
#!/bin/bash
set -e
DOCS_DIR=generated/docs
CHECKOUT_DIR=../envoy-docs
PUBLISH_DIR="$CHECKOUT_DIR"/docs/envoy/latest
BUILD_SHA=`git rev-parse HEAD`
if [ -z "$CIRCLE_PULL_REQUEST" ] && [ "$CIRCLE_BRANCH" == "master" ]
then
echo 'cloning'
git clone git@github.com:envoyproxy/envoyproxy.github.io "$CHECKOUT_DIR"
git -C "$CHECKOUT_DIR" fetch
git -C "$CHECKOUT_DIR" checkout -B master origin/master
rm -fr "$PUBLISH_DIR"
mkdir -p "$PUBLISH_DIR"
cp -r "$DOCS_DIR"/* "$PUBLISH_DIR"
cd "$CHECKOUT_DIR"
git config user.name "envoy-docs(travis)"
git config user.email envoy-docs@users.noreply.github.com
echo 'add'
git add .
echo 'commit'
git commit -m "docs data-plane-api@$BUILD_SHA"
echo 'push'
git push origin master
else
echo "Ignoring PR branch for docs push"
fi

19
docs/requirements.txt
Unescape View File

@ -1,19 +0,0 @@
GitPython==2.0.8
Jinja2==2.9.6
MarkupSafe==1.0
Pygments==2.2.0
alabaster==0.7.10
babel==2.4.0
docutils==0.12
gitdb==0.6.4
imagesize==0.7.1
pytz==2017.2
requests==2.13.0
six==1.10.0
smmap==0.9.0
snowballstemmer==1.2.1
sphinx==1.6.5
sphinxcontrib-httpdomain==1.5.0
# Fix for https://github.com/rtfd/sphinx_rtd_theme/issues/397
git+https://github.com/rtfd/sphinx_rtd_theme@9d704f287ac197dfb1c9b27f0acfb91267dce4f1

4
docs/root/_static/docker_compose_v0.1.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 295 KiB

4
docs/root/_static/double_proxy.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 67 KiB

4
docs/root/_static/front_proxy.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 54 KiB

0
docs/root/_static/placeholder
Unescape View File

4
docs/root/_static/service_to_service.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 52 KiB

20
docs/root/about_docs.rst
Unescape View File

@ -1,20 +0,0 @@
About the documentation
=======================
The Envoy documentation is composed of a few major sections:
* :ref:`Introduction <intro>`: This section covers a general overview of what Envoy is, an
architecture overview, how it is typically deployed, etc.
* :ref:`Getting Started <start>`: Quickly get started with Envoy using Docker.
* :ref:`Installation <install>`: How to build/install Envoy using Docker.
* :ref:`Configuration <config>`: Detailed configuration instructions common to both the legacy v1
API and the new v2 API. Where relevant, the configuration guide also contains information on
statistics, runtime configuration, and APIs.
* :ref:`Operations <operations>`: General information on how to operate Envoy including the command
line interface, hot restart wrapper, administration interface, a general statistics overview,
etc.
* :ref:`Extending Envoy <extending>`: Information on how to write custom filters for Envoy.
* :ref:`v1 API reference <envoy_v1_api_reference>`: Configuration details specific to the legacy
v1 API.
* :ref:`v2 API reference <envoy_api_reference>`: Configuration details specific to the new v2 API.
* :ref:`Envoy FAQ <faq_overview>`: Have questions? We have answers. Hopefully.

181
docs/root/api-v1/access_log.rst
Unescape View File

@ -1,181 +0,0 @@
.. _config_access_log_v1:
Access logging
==============
Configuration
-------------
.. code-block:: json
{
"access_log": [
{
"path": "...",
"format": "...",
"filter": "{...}",
},
]
}
.. _config_access_log_path_param:
path
*(required, string)* Path the access log is written to.
.. _config_access_log_format_param:
format
*(optional, string)* Access log format. Envoy supports :ref:`custom access log formats
<config_access_log_format>` as well as a :ref:`default format
<config_access_log_default_format>`.
.. _config_access_log_filter_param:
filter
*(optional, object)* :ref:`Filter <config_http_con_manager_access_log_filters_v1>` which is used
to determine if the access log needs to be written.
.. _config_http_con_manager_access_log_filters_v1:
Filters
-------
Envoy supports the following access log filters:
.. contents::
:local:
Status code
^^^^^^^^^^^
.. code-block:: json
{
"filter": {
"type": "status_code",
"op": "...",
"value": "...",
"runtime_key": "..."
}
}
Filters on HTTP response/status code.
op
*(required, string)* Comparison operator. Currently *>=* and *=* are the only supported operators.
value
*(required, integer)* Default value to compare against if runtime value is not available.
runtime_key
*(optional, string)* Runtime key to get value for comparison. This value is used if defined.
Duration
^^^^^^^^
.. code-block:: json
{
"filter": {
"type": "duration",
"op": "..",
"value": "...",
"runtime_key": "..."
}
}
Filters on total request duration in milliseconds.
op
*(required, string)* Comparison operator. Currently *>=* and *=* are the only supported operators.
value
*(required, integer)* Default value to compare against if runtime values is not available.
runtime_key
*(optional, string)* Runtime key to get value for comparison. This value is used if defined.
Not health check
^^^^^^^^^^^^^^^^
.. code-block:: json
{
"filter": {
"type": "not_healthcheck"
}
}
Filters for requests that are not health check requests. A health check request is marked by
the :ref:`health check filter <config_http_filters_health_check>`.
Traceable
^^^^^^^^^
.. code-block:: json
{
"filter": {
"type": "traceable_request"
}
}
Filters for requests that are traceable. See the :ref:`tracing overview <arch_overview_tracing>` for
more information on how a request becomes traceable.
.. _config_http_con_manager_access_log_filters_runtime_v1:
Runtime
^^^^^^^^^
.. code-block:: json
{
"filter": {
"type": "runtime",
"key" : "..."
}
}
Filters for random sampling of requests. Sampling pivots on the header
:ref:`x-request-id<config_http_conn_man_headers_x-request-id>` being present. If
:ref:`x-request-id<config_http_conn_man_headers_x-request-id>` is present, the filter will
consistently sample across multiple hosts based on the runtime key value and the value extracted
from :ref:`x-request-id<config_http_conn_man_headers_x-request-id>`. If it is missing, the
filter will randomly sample based on the runtime key value.
key
*(required, string)* Runtime key to get the percentage of requests to be sampled.
This runtime control is specified in the range 0-100 and defaults to 0.
And
^^^
.. code-block:: json
{
"filter": {
"type": "logical_and",
"filters": []
}
}
Performs a logical "and" operation on the result of each filter in *filters*. Filters are evaluated
sequentially and if one of them returns false, the filter returns false immediately.
Or
^^
.. code-block:: json
{
"filter": {
"type": "logical_or",
"filters": []
}
}
Performs a logical "or" operation on the result of each individual filter. Filters are evaluated
sequentially and if one of them returns true, the filter returns true immediately.

27
docs/root/api-v1/admin.rst
Unescape View File

@ -1,27 +0,0 @@
.. _config_admin_v1:
Administration interface
========================
Administration interface :ref:`operations documentation <operations_admin_interface>`.
.. code-block:: json
{
"access_log_path": "...",
"profile_path": "...",
"address": "..."
}
access_log_path
*(required, string)* The path to write the access log for the administration server. If no
access log is desired specify '/dev/null'.
profile_path
*(optional, string)* The cpu profiler output path for the administration server. If no profile
path is specified, the default is '/var/log/envoy/envoy.prof'.
address
*(required, string)* The TCP address that the administration server will listen on, e.g.,
"tcp://127.0.0.1:1234". Note, "tcp://0.0.0.0:1234" is the wild card match for any IPv4 address
with port 1234.

19
docs/root/api-v1/api.rst
Unescape View File

@ -1,19 +0,0 @@
.. _envoy_v1_api_reference:
v1 API reference
================
.. toctree::
:glob:
:maxdepth: 2
listeners/listeners
network_filters/network_filters
route_config/route_config
http_filters/http_filters
cluster_manager/cluster_manager
access_log
admin
rate_limit
runtime
tracing

45
docs/root/api-v1/cluster_manager/cds.rst
Unescape View File

@ -1,45 +0,0 @@
.. _config_cluster_manager_cds_v1:
Cluster discovery service
=========================
.. code-block:: json
{
"cluster": "{...}",
"refresh_delay_ms": "..."
}
:ref:`cluster <config_cluster_manager_cluster>`
*(required, object)* A standard definition of an upstream cluster that hosts the cluster
discovery service. The cluster must run a REST service that implements the :ref:`CDS HTTP API
<config_cluster_manager_cds_api>`.
refresh_delay_ms
*(optional, integer)* The delay, in milliseconds, between fetches to the CDS API. Envoy will add
an additional random jitter to the delay that is between zero and *refresh_delay_ms*
milliseconds. Thus the longest possible refresh delay is 2 \* *refresh_delay_ms*. Default value
is 30000ms (30 seconds).
.. _config_cluster_manager_cds_api:
REST API
--------
.. http:get:: /v1/clusters/(string: service_cluster)/(string: service_node)
Asks the discovery service to return all clusters for a particular `service_cluster` and
`service_node`. `service_cluster` corresponds to the :option:`--service-cluster` CLI option.
`service_node` corresponds to the :option:`--service-node` CLI option. Responses use the following
JSON schema:
.. code-block:: json
{
"clusters": []
}
clusters
*(Required, array)* A list of :ref:`clusters <config_cluster_manager_cluster>` that will be
dynamically added/modified within the cluster manager. Envoy will reconcile this list with the
clusters that are currently loaded and either add/modify/remove clusters as necessary.

205
docs/root/api-v1/cluster_manager/cluster.rst
Unescape View File

@ -1,205 +0,0 @@
.. _config_cluster_manager_cluster:
Cluster
=======
.. code-block:: json
{
"name": "...",
"type": "...",
"connect_timeout_ms": "...",
"per_connection_buffer_limit_bytes": "...",
"lb_type": "...",
"ring_hash_lb_config": "{...}",
"hosts": [],
"service_name": "...",
"health_check": "{...}",
"max_requests_per_connection": "...",
"circuit_breakers": "{...}",
"ssl_context": "{...}",
"features": "...",
"http2_settings": "{...}",
"cleanup_interval_ms": "...",
"dns_refresh_rate_ms": "...",
"dns_lookup_family": "...",
"dns_resolvers": [],
"outlier_detection": "{...}"
}
.. _config_cluster_manager_cluster_name:
name
*(required, string)* Supplies the name of the cluster which must be unique across all clusters.
The cluster name is used when emitting :ref:`statistics <config_cluster_manager_cluster_stats>`.
By default, the maximum length of a cluster name is limited to 60 characters. This limit can be
increased by setting the :option:`--max-obj-name-len` command line argument to the desired value.
.. _config_cluster_manager_type:
type
*(required, string)* The :ref:`service discovery type <arch_overview_service_discovery_types>` to
use for resolving the cluster. Possible options are *static*, *strict_dns*, *logical_dns*,
:ref:`*original_dst* <arch_overview_service_discovery_types_original_destination>`, and *sds*.
connect_timeout_ms
*(required, integer)* The timeout for new network connections to hosts in the cluster specified
in milliseconds.
.. _config_cluster_manager_cluster_per_connection_buffer_limit_bytes:
per_connection_buffer_limit_bytes
*(optional, integer)* Soft limit on size of the cluster's connections read and write buffers.
If unspecified, an implementation defined default is applied (1MiB).
.. _config_cluster_manager_cluster_lb_type:
lb_type
*(required, string)* The :ref:`load balancer type <arch_overview_load_balancing_types>` to use
when picking a host in the cluster. Possible options are *round_robin*, *least_request*,
*ring_hash*, *random*, and *original_dst_lb*. Note that :ref:`*original_dst_lb*
<arch_overview_load_balancing_types_original_destination>` must be used with clusters of type
:ref:`*original_dst* <arch_overview_service_discovery_types_original_destination>`, and may not be
used with any other cluster type.
:ref:`ring_hash_lb_config <config_cluster_manager_cluster_ring_hash_lb_config>`
*(optional, object)* Optional configuration for the ring hash load balancer, used when *lb_type*
is set to *ring_hash*.
hosts
*(sometimes required, array)* If the service discovery type is *static*, *strict_dns*, or
*logical_dns* the hosts array is required. Hosts array is not allowed with cluster type
*original_dst*. How it is specified depends on the type of service discovery:
static
Static clusters must use fully resolved hosts that require no DNS lookups. Both TCP and unix
domain sockets (UDS) addresses are supported. A TCP address looks like:
``tcp://<ip>:<port>``
A UDS address looks like:
``unix://<file name>``
A list of addresses can be specified as in the following example:
.. code-block:: json
[{"url": "tcp://10.0.0.2:1234"}, {"url": "tcp://10.0.0.3:5678"}]
strict_dns
Strict DNS clusters can specify any number of hostname:port combinations. All names will be
resolved using DNS and grouped together to form the final cluster. If multiple records are
returned for a single name, all will be used. For example:
.. code-block:: json
[{"url": "tcp://foo1.bar.com:1234"}, {"url": "tcp://foo2.bar.com:5678"}]
logical_dns
Logical DNS clusters specify hostnames much like strict DNS, however only the first host will be
used. For example:
.. code-block:: json
[{"url": "tcp://foo1.bar.com:1234"}]
.. _config_cluster_manager_cluster_service_name:
service_name
*(sometimes required, string)* This parameter is required if the service discovery type is *sds*.
It will be passed to the :ref:`SDS API <config_cluster_manager_sds_api>` when fetching cluster
members.
:ref:`health_check <config_cluster_manager_cluster_hc>`
*(optional, object)* Optional :ref:`active health checking <arch_overview_health_checking>`
configuration for the cluster. If no configuration is specified no health checking will be done
and all cluster members will be considered healthy at all times.
max_requests_per_connection
*(optional, integer)* Optional maximum requests for a single upstream connection. This
parameter is respected by both the HTTP/1.1 and HTTP/2 connection pool implementations. If not
specified, there is no limit. Setting this parameter to 1 will effectively disable keep alive.
:ref:`circuit_breakers <config_cluster_manager_cluster_circuit_breakers_v1>`
*(optional, object)* Optional :ref:`circuit breaking <arch_overview_circuit_break>` settings
for the cluster.
:ref:`ssl_context <config_cluster_manager_cluster_ssl>`
*(optional, object)* The TLS configuration for connections to the upstream cluster. If no TLS
configuration is specified, TLS will not be used for new connections.
.. _config_cluster_manager_cluster_features:
features
*(optional, string)* A comma delimited list of features that the upstream cluster supports.
The currently supported features are:
http2
If *http2* is specified, Envoy will assume that the upstream supports HTTP/2 when making new
HTTP connection pool connections. Currently, Envoy only supports prior knowledge for upstream
connections. Even if TLS is used with ALPN, *http2* must be specified. As an aside this allows
HTTP/2 connections to happen over plain text.
.. _config_cluster_manager_cluster_http2_settings:
http2_settings
*(optional, object)* Additional HTTP/2 settings that are passed directly to the HTTP/2 codec when
initiating HTTP connection pool connections. These are the same options supported in the HTTP connection
manager :ref:`http2_settings <config_http_conn_man_http2_settings>` option.
.. _config_cluster_manager_cluster_cleanup_interval_ms:
cleanup_interval_ms
*(optional, integer)* The interval for removing stale hosts from an *original_dst* cluster. Hosts
are considered stale if they have not been used as upstream destinations during this interval.
New hosts are added to original destination clusters on demand as new connections are redirected
to Envoy, causing the number of hosts in the cluster to grow over time. Hosts that are not stale
(they are actively used as destinations) are kept in the cluster, which allows connections to
them remain open, saving the latency that would otherwise be spent on opening new connections.
If this setting is not specified, the value defaults to 5000. For cluster types other than
*original_dst* this setting is ignored.
.. _config_cluster_manager_cluster_dns_refresh_rate_ms:
dns_refresh_rate_ms
*(optional, integer)* If the dns refresh rate is specified and the cluster type is either *strict_dns*,
or *logical_dns*, this value is used as the cluster's dns refresh rate. If this setting is not specified,
the value defaults to 5000. For cluster types other than *strict_dns* and *logical_dns* this setting is
ignored.
.. _config_cluster_manager_cluster_dns_lookup_family:
dns_lookup_family
*(optional, string)* The DNS IP address resolution policy. The options are *v4_only*, *v6_only*,
and *auto*. If this setting is not specified, the value defaults to *v4_only*. When *v4_only* is selected,
the DNS resolver will only perform a lookup for addresses in the IPv4 family. If *v6_only* is selected,
the DNS resolver will only perform a lookup for addresses in the IPv6 family. If *auto* is specified,
the DNS resolver will first perform a lookup for addresses in the IPv6 family and fallback to a lookup for
addresses in the IPv4 family. For cluster types other than *strict_dns* and *logical_dns*, this setting
is ignored.
.. _config_cluster_manager_cluster_dns_resolvers:
dns_resolvers
*(optional, array)* If DNS resolvers are specified and the cluster type is either *strict_dns*, or
*logical_dns*, this value is used to specify the cluster's dns resolvers. If this setting is not
specified, the value defaults to the default resolver, which uses /etc/resolv.conf for
configuration. For cluster types other than *strict_dns* and *logical_dns* this setting is
ignored.
.. _config_cluster_manager_cluster_outlier_detection_summary:
:ref:`outlier_detection <config_cluster_manager_cluster_outlier_detection>`
*(optional, object)* If specified, outlier detection will be enabled for this upstream cluster.
See the :ref:`architecture overview <arch_overview_outlier_detection>` for more information on outlier
detection.
.. toctree::
:hidden:
cluster_hc
cluster_circuit_breakers
cluster_ssl
cluster_outlier_detection
cluster_ring_hash_lb_config

64
docs/root/api-v1/cluster_manager/cluster_circuit_breakers.rst
Unescape View File

@ -1,64 +0,0 @@
.. _config_cluster_manager_cluster_circuit_breakers_v1:
Circuit breakers
================
* Circuit breaking :ref:`architecture overview <arch_overview_circuit_break>`.
* Priority routing :ref:`architecture overview <arch_overview_http_routing_priority>`.
Circuit breaking settings can be specified individually for each defined priority. How the
different priorities are used are documented in the sections of the configuration guide that use
them.
.. code-block:: json
{
"default": "{...}",
"high": "{...}"
}
default
*(optional, object)* Settings object for default priority.
high
*(optional, object)* Settings object for high priority.
Per priority settings
---------------------
.. code-block:: json
{
"max_connections": "...",
"max_pending_requests": "...",
"max_requests": "...",
"max_retries": "...",
}
.. _config_cluster_manager_cluster_circuit_breakers_max_connections:
max_connections
*(optional, integer)* The maximum number of connections that Envoy will make to the upstream
cluster. If not specified, the default is 1024. See the :ref:`circuit breaking overview
<arch_overview_circuit_break>` for more information.
.. _config_cluster_manager_cluster_circuit_breakers_max_pending_requests:
max_pending_requests
*(optional, integer)* The maximum number of pending requests that Envoy will allow to the upstream
cluster. If not specified, the default is 1024. See the :ref:`circuit breaking overview
<arch_overview_circuit_break>` for more information.
.. _config_cluster_manager_cluster_circuit_breakers_max_requests:
max_requests
*(optional, integer)* The maximum number of parallel requests that Envoy will make to the upstream
cluster. If not specified, the default is 1024. See the :ref:`circuit breaking overview
<arch_overview_circuit_break>` for more information.
.. _config_cluster_manager_cluster_circuit_breakers_max_retries:
max_retries
*(optional, integer)* The maximum number of parallel retries that Envoy will allow to the upstream
cluster. If not specified, the default is 3. See the :ref:`circuit breaking overview
<arch_overview_circuit_break>` for more information.

91
docs/root/api-v1/cluster_manager/cluster_hc.rst
Unescape View File

@ -1,91 +0,0 @@
.. _config_cluster_manager_cluster_hc_v1:
Health checking
===============
* Health checking :ref:`architecture overview <arch_overview_health_checking>`.
* If health checking is configured for a cluster, additional statistics are emitted. They are
documented :ref:`here <config_cluster_manager_cluster_stats>`.
.. code-block:: json
{
"type": "...",
"timeout_ms": "...",
"interval_ms": "...",
"unhealthy_threshold": "...",
"healthy_threshold": "...",
"path": "...",
"send": [],
"receive": [],
"interval_jitter_ms": "...",
"service_name": "...",
"redis_key": "..."
}
type
*(required, string)* The type of health checking to perform. Currently supported types are
*http*, *redis*, and *tcp*. See the :ref:`architecture overview <arch_overview_health_checking>`
for more information.
timeout_ms
*(required, integer)* The time in milliseconds to wait for a health check response. If the
timeout is reached the health check attempt will be considered a failure.
.. _config_cluster_manager_cluster_hc_interval:
interval_ms
*(required, integer)* The interval between health checks in milliseconds.
unhealthy_threshold
*(required, integer)* The number of unhealthy health checks required before a host is marked
unhealthy. Note that for *http* health checking if a host responds with 503 this threshold is
ignored and the host is considered unhealthy immediately.
healthy_threshold
*(required, integer)* The number of healthy health checks required before a host is marked
healthy. Note that during startup, only a single successful health check is required to mark
a host healthy.
path
*(sometimes required, string)* This parameter is required if the type is *http*. It specifies the
HTTP path that will be requested during health checking. For example */healthcheck*.
send
*(sometimes required, array)* This parameter is required if the type is *tcp*. It specifies
the bytes to send for a health check request. It is an array of hex byte strings specified
as in the following example:
.. code-block:: json
[
{"binary": "01"},
{"binary": "000000FF"}
]
The array is allowed to be empty in the case of "connect only" health checking.
receive
*(sometimes required, array)* This parameter is required if the type is *tcp*. It specified the
bytes that are expected in a successful health check response. It is an array of hex byte strings
specified similarly to the *send* parameter. The array is allowed to be empty in the case of
"connect only" health checking.
interval_jitter_ms
*(optional, integer)* An optional jitter amount in millseconds. If specified, during every
internal Envoy will add 0 to *interval_jitter_ms* milliseconds to the wait time.
.. _config_cluster_manager_cluster_hc_service_name:
service_name
*(optional, string)* An optional service name parameter which is used to validate the identity of
the health checked cluster. See the :ref:`architecture overview
<arch_overview_health_checking_identity>` for more information.
.. _config_cluster_manager_cluster_hc_redis_key:
redis_key
*(optional, string)* If the type is *redis*, perform ``EXISTS <redis_key>`` instead of
``PING``. A return value from Redis of 0 (does not exist) is considered a passing healthcheck. A
return value other than 0 is considered a failure. This allows the user to mark a Redis instance
for maintenance by setting the specified key to any value and waiting for traffic to drain.

51
docs/root/api-v1/cluster_manager/cluster_manager.rst
Unescape View File

@ -1,51 +0,0 @@
.. _config_cluster_manager_v1:
Cluster manager
===============
.. toctree::
:hidden:
cluster
outlier
cds
sds
Cluster manager :ref:`architecture overview <arch_overview_cluster_manager>`.
.. code-block:: json
{
"clusters": [],
"sds": "{...}",
"local_cluster_name": "...",
"outlier_detection": "{...}",
"cds": "{...}"
}
.. _config_cluster_manager_clusters:
:ref:`clusters <config_cluster_manager_cluster>`
*(required, array)* A list of upstream clusters that the cluster manager performs
:ref:`service discovery <arch_overview_service_discovery>`,
:ref:`health checking <arch_overview_health_checking>`, and
:ref:`load balancing <arch_overview_load_balancing>` on.
:ref:`sds <config_cluster_manager_sds>`
*(sometimes required, object)* If any defined clusters use the :ref:`sds
<arch_overview_service_discovery_types_sds>` cluster type, a global SDS configuration must be specified.
.. _config_cluster_manager_local_cluster_name:
local_cluster_name
*(optional, string)* Name of the local cluster (i.e., the cluster that owns the Envoy running this
configuration). In order to enable
:ref:`zone aware routing <arch_overview_load_balancing_zone_aware_routing>` this option must be
set. If *local_cluster_name* is defined then :ref:`clusters <config_cluster_manager_clusters>`
must contain a definition of a cluster with the same name.
:ref:`outlier_detection <config_cluster_manager_outlier_detection>`
*(optional, object)* Optional global configuration for outlier detection.
:ref:`cds <config_cluster_manager_cds_v1>`
*(optional, object)* Optional configuration for the cluster discovery service (CDS) API.

101
docs/root/api-v1/cluster_manager/cluster_outlier_detection.rst
Unescape View File

@ -1,101 +0,0 @@
.. _config_cluster_manager_cluster_outlier_detection:
Outlier detection
=================
.. code-block:: json
{
"consecutive_5xx": "...",
"consecutive_gateway_failure": "...",
"interval_ms": "...",
"base_ejection_time_ms": "...",
"max_ejection_percent": "...",
"enforcing_consecutive_5xx" : "...",
"enforcing_consecutive_gateway_failure" : "...",
"enforcing_success_rate" : "...",
"success_rate_minimum_hosts" : "...",
"success_rate_request_volume" : "...",
"success_rate_stdev_factor" : "..."
}
.. _config_cluster_manager_cluster_outlier_detection_consecutive_5xx:
consecutive_5xx
*(optional, integer)* The number of consecutive 5xx responses before a consecutive 5xx ejection occurs. Defaults to 5.
.. _config_cluster_manager_cluster_outlier_detection_consecutive_gateway_failure:
consecutive_gateway_failure
*(optional, integer)* The number of consecutive "gateway errors" (502, 503 and 504 responses),
including those raised by Envoy for connection errors, before a consecutive gateway failure
ejection occurs. Defaults to 5.
.. _config_cluster_manager_cluster_outlier_detection_interval_ms:
interval_ms
*(optional, integer)* The time interval between ejection analysis sweeps. This can result in both new ejections as well
as hosts being returned to service. Defaults to 10000ms or 10s.
.. _config_cluster_manager_cluster_outlier_detection_base_ejection_time_ms:
base_ejection_time_ms
*(optional, integer)* The base time that a host is ejected for. The real time is equal to the base time multiplied by
the number of times the host has been ejected. Defaults to 30000ms or 30s.
.. _config_cluster_manager_cluster_outlier_detection_max_ejection_percent:
max_ejection_percent
*(optional, integer)* The maximum % of hosts in an upstream cluster that can be ejected due to outlier detection.
Defaults to 10%.
.. _config_cluster_manager_cluster_outlier_detection_enforcing_consecutive_5xx:
enforcing_consecutive_5xx
*(optional, integer)* The % chance that a host will be actually ejected when an outlier status is detected through
consecutive 5xx. This setting can be used to disable ejection or to ramp it up slowly.
Defaults to 100 with 1% granularity.
.. _config_cluster_manager_cluster_outlier_detection_enforcing_consecutive_gateway_failure:
enforcing_consecutive_gateway_failure
*(optional, integer)* The % chance that a host will be actually ejected when an outlier status is
detected through consecutive gateway failure. This setting can be used to disable ejection or to
ramp it up slowly. Defaults to 0 with 1% granularity.
.. _config_cluster_manager_cluster_outlier_detection_enforcing_success_rate:
enforcing_success_rate
*(optional, integer)* The % chance that a host will be actually ejected when an outlier status is detected through
success rate statistics. This setting can be used to disable ejection or to ramp it up slowly.
Defaults to 100 with 1% granularity.
.. _config_cluster_manager_cluster_outlier_detection_success_rate_minimum_hosts:
success_rate_minimum_hosts
*(optional, integer)* The number of hosts in a cluster that must have enough request volume to detect success rate outliers.
If the number of hosts is less than this setting, outlier detection via success rate statistics is not
performed for any host in the cluster. Defaults to 5.
.. _config_cluster_manager_cluster_outlier_detection_success_rate_request_volume:
success_rate_request_volume
*(optional, integer)* The minimum number of total requests that must be collected in one interval
(as defined by :ref:`interval_ms <config_cluster_manager_cluster_outlier_detection_interval_ms>` above)
to include this host in success rate based outlier detection. If the volume is lower than this setting,
outlier detection via success rate statistics is not performed for that host. Defaults to 100.
.. _config_cluster_manager_cluster_outlier_detection_success_rate_stdev_factor:
success_rate_stdev_factor
*(optional, integer)* This factor is used to determine the ejection threshold for success rate outlier ejection.
The ejection threshold is used as a measure to determine when a particular host has fallen below an acceptable
success rate.
The ejection threshold is the difference between the mean success rate, and the product of
this factor and the standard deviation of the mean success rate:
``mean - (stdev * success_rate_stdev_factor)``. This factor is divided by a thousand to
get a ``double``. That is, if the desired factor is ``1.9``, the runtime value should be ``1900``.
Defaults to 1900.
Each of the above configuration values can be overridden via
:ref:`runtime values <config_cluster_manager_cluster_runtime_outlier_detection>`.

26
docs/root/api-v1/cluster_manager/cluster_ring_hash_lb_config.rst
Unescape View File

@ -1,26 +0,0 @@
.. _config_cluster_manager_cluster_ring_hash_lb_config:
Ring hash load balancer configuration
=====================================
Ring hash load balancing settings are used when the *lb_type* is set to *ring_hash* in the
:ref:`cluster manager <config_cluster_manager_cluster_lb_type>`.
.. code-block:: json
{
"minimum_ring_size": "...",
"use_std_hash": "..."
}
minimum_ring_size
*(optional, integer)* Minimum hash ring size, i.e. total virtual nodes. A larger size will provide
better request distribution since each host in the cluster will have more virtual nodes. Defaults
to 1024. In the case that total number of hosts is greater than the minimum, each host will be
allocated a single virtual node.
use_std_hash
*(optional, boolean)* Defaults to true, meaning that std::hash is used to hash hosts onto the
ketama ring. std::hash can vary by platform. For this reason, Envoy will eventually use
`xxHash <https://github.com/Cyan4973/xxHash>`_ by default. This field exists for migration
purposes and will eventually be deprecated. Set it to false to use xxHash now.

82
docs/root/api-v1/cluster_manager/cluster_ssl.rst
Unescape View File

@ -1,82 +0,0 @@
.. _config_cluster_manager_cluster_ssl:
TLS context
===========
.. code-block:: json
{
"alpn_protocols": "...",
"cert_chain_file": "...",
"private_key_file": "...",
"ca_cert_file": "...",
"verify_certificate_hash": "...",
"verify_subject_alt_name": [],
"cipher_suites": "...",
"ecdh_curves": "...",
"sni": "..."
}
alpn_protocols
*(optional, string)* Supplies the list of ALPN protocols that connections should request. In
practice this is likely to be set to a single value or not set at all:
* "h2" If upstream connections should use HTTP/2. In the current implementation this must be set
alongside the *http2* cluster :ref:`features <config_cluster_manager_cluster_features>` option.
The two options together will use ALPN to tell a server that expects ALPN that Envoy supports
HTTP/2. Then the *http2* feature will cause new connections to use HTTP/2.
cert_chain_file
*(optional, string)* The certificate chain file that should be served by the connection. This is
used to provide a client side TLS certificate to an upstream host.
private_key_file
*(optional, string)* The private key that corresponds to the certificate chain file.
ca_cert_file
*(optional, string)* A file containing certificate authority certificates to use in verifying
a presented server certificate.
verify_certificate_hash
*(optional, string)* If specified, Envoy will verify (pin) the hash of the presented server
certificate.
verify_subject_alt_name
*(optional, array)* An optional list of subject alt names. If specified, Envoy will verify
that the server certificate's subject alt name matches one of the specified values.
cipher_suites
*(optional, string)* If specified, the TLS connection will only support the specified `cipher list
<https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Cipher-suite-configuration>`_.
If not specified, the default list:
.. code-block:: none
[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]
[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]
ECDHE-ECDSA-AES128-SHA256
ECDHE-RSA-AES128-SHA256
ECDHE-ECDSA-AES128-SHA
ECDHE-RSA-AES128-SHA
AES128-GCM-SHA256
AES128-SHA256
AES128-SHA
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-SHA384
ECDHE-RSA-AES256-SHA384
ECDHE-ECDSA-AES256-SHA
ECDHE-RSA-AES256-SHA
AES256-GCM-SHA384
AES256-SHA256
AES256-SHA
will be used.
ecdh_curves
*(optional, string)* If specified, the TLS connection will only support the specified ECDH curves.
If not specified, the default curves (X25519, P-256) will be used.
sni
*(optional, string)* If specified, the string will be presented as the SNI during the TLS
handshake.

15
docs/root/api-v1/cluster_manager/outlier.rst
Unescape View File

@ -1,15 +0,0 @@
.. _config_cluster_manager_outlier_detection:
Outlier detection
=================
Outlier detection :ref:`architecture overview <arch_overview_outlier_detection>`.
.. code-block:: json
{
"event_log_path": "..."
}
event_log_path
*(optional, string)* Specifies the path to the outlier event log.

85
docs/root/api-v1/cluster_manager/sds.rst
Unescape View File

@ -1,85 +0,0 @@
.. _config_cluster_manager_sds:
Service discovery service
=========================
Service discovery service :ref:`architecture overview <arch_overview_service_discovery_types_sds>`.
.. code-block:: json
{
"cluster": "{...}",
"refresh_delay_ms": "{...}"
}
:ref:`cluster <config_cluster_manager_cluster>`
*(required, object)* A standard definition of an upstream cluster that hosts the service
discovery service. The cluster must run a REST service that implements the :ref:`SDS HTTP API
<config_cluster_manager_sds_api>`.
refresh_delay_ms
*(required, integer)* The delay, in milliseconds, between fetches to the SDS API for each
configured SDS cluster. Envoy will add an additional random jitter to the delay that is between
zero and *refresh_delay_ms* milliseconds. Thus the longest possible refresh delay is
2 \* *refresh_delay_ms*.
.. _config_cluster_manager_sds_api:
REST API
--------
Envoy expects the service discovery service to expose the following API (See Lyft's
`reference implementation <https://github.com/lyft/discovery>`_):
.. http:get:: /v1/registration/(string: service_name)
Asks the discovery service to return all hosts for a particular `service_name`. `service_name`
corresponds to the :ref:`service_name <config_cluster_manager_cluster_service_name>` cluster
parameter. Responses use the following JSON schema:
.. code-block:: json
{
"hosts": []
}
hosts
*(Required, array)* A list of :ref:`hosts <config_cluster_manager_sds_api_host>` that make up
the service.
.. _config_cluster_manager_sds_api_host:
Host JSON
---------
.. code-block:: json
{
"ip_address": "...",
"port": "...",
"tags": {
"az": "...",
"canary": "...",
"load_balancing_weight": "..."
}
}
ip_address
*(required, string)* The IP address of the upstream host.
port
*(required, integer)* The port of the upstream host.
.. _config_cluster_manager_sds_api_host_az:
az
*(optional, string)* The optional zone of the upstream host. Envoy uses the zone for various
statistics and load balancing tasks documented elsewhere.
canary
*(optional, boolean)* The optional canary status of the upstream host. Envoy uses the canary
status for various statistics and load balancing tasks documented elsewhere.
load_balancing_weight
*(optional, integer)* The optional load balancing weight of the upstream host, in the range
1 - 100. Envoy uses the load balancing weight in some of the built in load balancers.

24
docs/root/api-v1/http_filters/buffer_filter.rst
Unescape View File

@ -1,24 +0,0 @@
.. _config_http_filters_buffer_v1:
Buffer
======
Buffer :ref:`configuration overview <config_http_filters_buffer>`.
.. code-block:: json
{
"name": "buffer",
"config": {
"max_request_bytes": "...",
"max_request_time_s": "..."
}
}
max_request_bytes
*(required, integer)* The maximum request size that the filter will buffer before the connection
manager will stop buffering and return a 413 response.
max_request_time_s
*(required, integer)* The maximum number of seconds that the filter will wait for a complete
request before returning a 408 response.

13
docs/root/api-v1/http_filters/cors_filter.rst
Unescape View File

@ -1,13 +0,0 @@
.. _config_http_filters_cors_v1:
CORS filter
===========
Cors :ref:`configuration overview <config_http_filters_cors>`.
.. code-block:: json
{
"name": "cors",
"config": {}
}

19
docs/root/api-v1/http_filters/dynamodb_filter.rst
Unescape View File

@ -1,19 +0,0 @@
.. _config_http_filters_dynamo_v1:
DynamoDB
========
DynamoDB :ref:`configuration overview <config_http_filters_dynamo>`.
.. code-block:: json
{
"name": "http_dynamo_filter",
"config": {}
}
name
*(required, string)* Filter name. The only supported value is `http_dynamo_filter`.
config
*(required, object)* The filter does not use any configuration.

94
docs/root/api-v1/http_filters/fault_filter.rst
Unescape View File

@ -1,94 +0,0 @@
.. _config_http_filters_fault_injection_v1:
Fault Injection
===============
Fault Injection :ref:`configuration overview <config_http_filters_fault_injection>`.
Configuration
-------------
.. code-block:: json
{
"name" : "fault",
"config" : {
"abort" : "{...}",
"delay" : "{...}",
"upstream_cluster" : "...",
"headers" : [],
"downstream_nodes": []
}
}
:ref:`abort <config_http_filters_fault_injection_abort>`
*(sometimes required, object)* If specified, the filter will abort requests based on
the values in the object. At least *abort* or *delay* must be specified.
:ref:`delay <config_http_filters_fault_injection_delay>`
*(sometimes required, object)* If specified, the filter will inject delays based on the values
in the object. At least *abort* or *delay* must be specified.
upstream_cluster:
*(optional, string)* Specifies the name of the (destination) upstream
cluster that the filter should match on. Fault injection will be
restricted to requests bound to the specific upstream cluster.
:ref:`headers <config_http_conn_man_route_table_route_headers>`
*(optional, array)* Specifies a set of headers that the filter should match on. The fault
injection filter can be applied selectively to requests that match a set of headers specified in
the fault filter config. The chances of actual fault injection further depend on the values of
*abort_percent* and *fixed_delay_percent* parameters. The filter will check the request's headers
against all the specified headers in the filter config. A match will happen if all the headers in
the config are present in the request with the same values (or based on presence if the *value*
field is not in the config).
downstream_nodes:
*(optional, array)* Faults are injected for the specified list of downstream hosts. If this setting is
not set, faults are injected for all downstream nodes. Downstream node name is taken from
:ref:`the HTTP x-envoy-downstream-service-node <config_http_conn_man_headers_downstream-service-node>`
header and compared against downstream_nodes list.
.. _config_http_filters_fault_injection_abort:
Abort
-----
.. code-block:: json
{
"abort_percent" : "...",
"http_status" : "..."
}
abort_percent
*(required, integer)* The percentage of requests that
should be aborted with the specified *http_status* code. Valid values
range from 0 to 100.
http_status
*(required, integer)* The HTTP status code that will be used as the
response code for the request being aborted.
.. _config_http_filters_fault_injection_delay:
Delay
-----
.. code-block:: json
{
"type" : "...",
"fixed_delay_percent" : "...",
"fixed_duration_ms" : "..."
}
type:
*(required, string)* Specifies the type of delay being
injected. Currently only *fixed* delay type (step function) is supported.
fixed_delay_percent:
*(required, integer)* The percentage of requests that will
be delayed for the duration specified by *fixed_duration_ms*. Valid
values range from 0 to 100.
fixed_duration_ms:
*(required, integer)* The delay duration in milliseconds. Must be greater than 0.

13
docs/root/api-v1/http_filters/grpc_http1_bridge_filter.rst
Unescape View File

@ -1,13 +0,0 @@
.. _config_http_filters_grpc_bridge_v1:
gRPC HTTP/1.1 bridge
====================
gRPC HTTP/1.1 bridge :ref:`configuration overview <config_http_filters_grpc_bridge>`.
.. code-block:: json
{
"name": "grpc_http1_bridge",
"config": {}
}

64
docs/root/api-v1/http_filters/grpc_json_transcoder_filter.rst
Unescape View File

@ -1,64 +0,0 @@
.. _config_http_filters_grpc_json_transcoder_v1:
gRPC-JSON transcoder filter
===========================
gRPC-JSON transcoder :ref:`configuration overview <config_http_filters_grpc_json_transcoder>`.
Configure gRPC-JSON transcoder
------------------------------
The filter config for the filter requires the descriptor file as well as a list of the gRPC
services to be transcoded.
.. code-block:: json
{
"name": "grpc_json_transcoder",
"config": {
"proto_descriptor": "proto.pb",
"services": ["grpc.service.Service"],
"print_options": {
"add_whitespace": false,
"always_print_primitive_fields": false,
"always_print_enums_as_ints": false,
"preserve_proto_field_names": false
}
}
}
proto_descriptor
*(required, string)* Supplies the filename of
:ref:`the proto descriptor set <config_grpc_json_generate_proto_descriptor_set>` for the gRPC
services.
services
*(required, array)* A list of strings that supplies the service names that the
transcoder will translate. If the service name doesn't exist in ``proto_descriptor``, Envoy
will fail at startup. The ``proto_descriptor`` may contain more services than the service names
specified here, but they won't be translated.
print_options
*(optional, object)* Control options for response json. These options are passed directly to
`JsonPrintOptions <https://developers.google.com/protocol-buffers/docs/reference/cpp/
google.protobuf.util.json_util#JsonPrintOptions>`_. Valid options are:
add_whitespace
*(optional, boolean)* Whether to add spaces, line breaks and indentation to make the JSON
output easy to read. Defaults to false.
always_print_primitive_fields
*(optional, boolean)* Whether to always print primitive fields. By default primitive
fields with default values will be omitted in JSON output. For
example, an int32 field set to 0 will be omitted. Setting this flag to
true will override the default behavior and print primitive fields
regardless of their values. Defaults to false.
always_print_enums_as_ints
*(optional, boolean)* Whether to always print enums as ints. By default they are rendered
as strings. Defaults to false.
preserve_proto_field_names
*(optional, boolean)* Whether to preserve proto field names. By default protobuf will
generate JSON field names using the ``json_name`` option, or lower camel case,
in that order. Setting this flag will preserve the original field names. Defaults to false.

13
docs/root/api-v1/http_filters/grpc_web_filter.rst
Unescape View File

@ -1,13 +0,0 @@
.. _config_http_filters_grpc_web_v1:
gRPC-Web filter
===============
gRPC-Web filter :ref:`configuration overview <config_http_filters_grpc_web>`.
.. code-block:: json
{
"name": "grpc_web",
"config": {}
}

28
docs/root/api-v1/http_filters/health_check_filter.rst
Unescape View File

@ -1,28 +0,0 @@
.. _config_http_filters_health_check_v1:
Health check
============
Health check :ref:`configuration overview <config_http_filters_health_check>`.
.. code-block:: json
{
"name": "health_check",
"config": {
"pass_through_mode": "...",
"endpoint": "...",
"cache_time_ms": "..."
}
}
pass_through_mode
*(required, boolean)* Specifies whether the filter operates in pass through mode or not.
endpoint
*(required, string)* Specifies the incoming HTTP endpoint that should be considered the
health check endpoint. For example */healthcheck*.
cache_time_ms
*(optional, integer)* If operating in pass through mode, the amount of time in milliseconds that
the filter should cache the upstream response.

8
docs/root/api-v1/http_filters/http_filters.rst
Unescape View File

@ -1,8 +0,0 @@
HTTP filters
============
.. toctree::
:glob:
:maxdepth: 2
*

21
docs/root/api-v1/http_filters/lua_filter.rst
Unescape View File

@ -1,21 +0,0 @@
.. _config_http_filters_lua_v1:
Lua
===
Lua :ref:`configuration overview <config_http_filters_lua>`.
.. code-block:: json
{
"name": "lua",
"config": {
"inline_code": "..."
}
}
inline_code
*(required, string)* The Lua code that Envoy will execute. This can be a very small script that
further loads code from disk if desired. Note that if JSON configuration is used, the code must
be properly escaped. YAML configuration may be easier to read since YAML supports multi-line
strings so complex scripts can be easily expressed inline in the configuration.

39
docs/root/api-v1/http_filters/rate_limit_filter.rst
Unescape View File

@ -1,39 +0,0 @@
.. _config_http_filters_rate_limit_v1:
Rate limit
==========
Rate limit :ref:`configuration overview <config_http_filters_rate_limit>`.
.. code-block:: json
{
"name": "rate_limit",
"config": {
"domain": "...",
"stage": "...",
"request_type": "...",
"timeout_ms": "..."
}
}
domain
*(required, string)* The rate limit domain to use when calling the rate limit service.
stage
*(optional, integer)* Specifies the rate limit configurations to be applied with the same stage
number. If not set, the default stage number is 0.
**NOTE:** The filter supports a range of 0 - 10 inclusively for stage numbers.
request_type
*(optional, string)* The type of requests the filter should apply to. The supported
types are *internal*, *external* or *both*. A request is considered internal if
:ref:`x-envoy-internal<config_http_conn_man_headers_x-envoy-internal>` is set to true. If
:ref:`x-envoy-internal<config_http_conn_man_headers_x-envoy-internal>` is not set or false, a
request is considered external. The filter defaults to *both*, and it will apply to all request
types.
timeout_ms
*(optional, integer)* The timeout in milliseconds for the rate limit service RPC. If not set,
this defaults to 20ms.

28
docs/root/api-v1/http_filters/router_filter.rst
Unescape View File

@ -1,28 +0,0 @@
.. _config_http_filters_router_v1:
Router
======
Router :ref:`configuration overview <config_http_filters_router>`.
.. code-block:: json
{
"name": "router",
"config": {
"dynamic_stats": "...",
"start_child_span": "..."
}
}
dynamic_stats
*(optional, boolean)* Whether the router generates :ref:`dynamic cluster statistics
<config_cluster_manager_cluster_stats_dynamic_http>`. Defaults to *true*. Can be disabled in high
performance scenarios.
.. _config_http_filters_router_start_child_span:
start_child_span
*(optional, boolean)* Whether to start a child :ref:`tracing <arch_overview_tracing>` span for
egress routed calls. This can be useful in scenarios where other filters (auth, ratelimit, etc.)
make outbound calls and have child spans rooted at the same ingress parent. Defaults to *false*.

56
docs/root/api-v1/http_filters/squash_filter.rst
Unescape View File

@ -1,56 +0,0 @@
.. _config_http_filters_squash_v1:
Squash
======
Squash :ref:`configuration overview <config_http_filters_squash>`.
.. code-block:: json
{
"name": "squash",
"config": {
"cluster": "...",
"attachment_template": "{...}",
"attachment_timeout_ms": "...",
"attachment_poll_period_ms": "...",
"request_timeout_ms": "..."
}
}
cluster
*(required, object)* The name of the cluster that hosts the Squash server.
attachment_template
*(required, object)* When the filter requests the Squash server to create a DebugAttachment, it
will use this structure as template for the body of the request. It can contain reference to
environment variables in the form of '{{ ENV_VAR_NAME }}'. These can be used to provide the Squash
server with more information to find the process to attach the debugger to. For example, in a
Istio/k8s environment, this will contain information on the pod:
.. code-block:: json
{
"spec": {
"attachment": {
"pod": "{{ POD_NAME }}",
"namespace": "{{ POD_NAMESPACE }}"
},
"match_request": true
}
}
(where POD_NAME, POD_NAMESPACE are configured in the pod via the Downward API)
request_timeout_ms
*(required, integer)* The timeout for individual requests sent to the Squash cluster. Defaults to
1 second.
attachment_timeout_ms
*(required, integer)* The total timeout Squash will delay a request and wait for it to be
attached. Defaults to 60 seconds.
attachment_poll_period_ms
*(required, integer)* Amount of time to poll for the status of the attachment object in the Squash
server (to check if has been attached). Defaults to 1 second.

49
docs/root/api-v1/listeners/lds.rst
Unescape View File

@ -1,49 +0,0 @@
.. _config_listeners_lds_v1:
Listener discovery service (LDS)
================================
.. code-block:: json
{
"cluster": "...",
"refresh_delay_ms": "..."
}
cluster
*(required, string)* The name of an upstream :ref:`cluster <config_cluster_manager_cluster>` that
hosts the listener discovery service. The cluster must run a REST service that implements the
:ref:`LDS HTTP API <config_listeners_lds_v1_api>`. NOTE: This is the *name* of a statically defined
cluster in the :ref:`cluster manager <config_cluster_manager>` configuration, not the full definition of
a cluster as in the case of SDS and CDS.
refresh_delay_ms
*(optional, integer)* The delay, in milliseconds, between fetches to the LDS API. Envoy will add
an additional random jitter to the delay that is between zero and *refresh_delay_ms*
milliseconds. Thus the longest possible refresh delay is 2 \* *refresh_delay_ms*. Default value
is 30000ms (30 seconds).
.. _config_listeners_lds_v1_api:
REST API
--------
.. http:get:: /v1/listeners/(string: service_cluster)/(string: service_node)
Asks the discovery service to return all listeners for a particular `service_cluster` and
`service_node`. `service_cluster` corresponds to the :option:`--service-cluster` CLI option.
`service_node` corresponds to the :option:`--service-node` CLI option. Responses use the following
JSON schema:
.. code-block:: json
{
"listeners": []
}
listeners
*(Required, array)* A list of :ref:`listeners <config_listeners>` that will be
dynamically added/modified within the listener manager. The management server is expected to
respond with the complete set of listeners that Envoy should configure during each polling cycle.
Envoy will reconcile this list with the listeners that are currently loaded and either
add/modify/remove listeners as necessary.

238
docs/root/api-v1/listeners/listeners.rst
Unescape View File

@ -1,238 +0,0 @@
.. _config_listeners_v1:
Listeners
=========
.. toctree::
:hidden:
lds
.. code-block:: json
{
"name": "...",
"address": "...",
"filters": [],
"ssl_context": "{...}",
"bind_to_port": "...",
"use_proxy_proto": "...",
"use_original_dst": "...",
"per_connection_buffer_limit_bytes": "...",
"drain_type": "..."
}
.. _config_listeners_name:
name
*(optional, string)* The unique name by which this listener is known. If no name is provided,
Envoy will allocate an internal UUID for the listener. If the listener is to be dynamically
updated or removed via :ref:`LDS <config_listeners_lds>` a unique name must be provided.
By default, the maximum length of a listener's name is limited to 60 characters. This limit can be
increased by setting the :option:`--max-obj-name-len` command line argument to the desired value.
address
*(required, string)* The address that the listener should listen on. Currently only TCP
listeners are supported, e.g., "tcp://127.0.0.1:80". Note, "tcp://0.0.0.0:80" is the wild card
match for any IPv4 address with port 80.
:ref:`filters <config_listener_network_filters>`
*(required, array)* A list of individual :ref:`network filters <arch_overview_network_filters>`
that make up the filter chain for connections established with the listener. Order matters as the
filters are processed sequentially as connection events happen.
**Note:** If the filter list is empty, the connection will close by default.
:ref:`ssl_context <config_listener_ssl_context>`
*(optional, object)* The :ref:`TLS <arch_overview_ssl>` context configuration for a TLS listener.
If no TLS context block is defined, the listener is a plain text listener.
bind_to_port
*(optional, boolean)* Whether the listener should bind to the port. A listener that doesn't bind
can only receive connections redirected from other listeners that set use_original_dst parameter to
true. Default is true.
use_proxy_proto
*(optional, boolean)* Whether the listener should expect a
`PROXY protocol V1 <http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt>`_ header on new
connections. If this option is enabled, the listener will assume that that remote address of the
connection is the one specified in the header. Some load balancers including the AWS ELB support
this option. If the option is absent or set to false, Envoy will use the physical peer address
of the connection as the remote address.
use_original_dst
*(optional, boolean)* If a connection is redirected using *iptables*, the port on which the proxy
receives it might be different from the original destination address. When this flag is set to true,
the listener hands off redirected connections to the listener associated with the original
destination address. If there is no listener associated with the original destination address, the
connection is handled by the listener that receives it. Defaults to false.
.. _config_listeners_per_connection_buffer_limit_bytes:
per_connection_buffer_limit_bytes
*(optional, integer)* Soft limit on size of the listener's new connection read and write buffers.
If unspecified, an implementation defined default is applied (1MiB).
.. _config_listeners_drain_type:
drain_type
*(optional, string)* The type of draining that the listener does. Allowed values include *default*
and *modify_only*. See the :ref:`draining <arch_overview_draining>` architecture overview for
more information.
.. _config_listener_network_filters:
Filters
-------
Network filter :ref:`architecture overview <arch_overview_network_filters>`.
.. code-block:: json
{
"name": "...",
"config": "{...}"
}
name
*(required, string)* The name of the filter to instantiate. The name must match a :ref:`supported
filter <config_network_filters>`.
config
*(required, object)* Filter specific configuration which depends on the filter being instantiated.
See the :ref:`supported filters <config_network_filters>` for further documentation.
.. _config_listener_ssl_context:
TLS context
-----------
TLS :ref:`architecture overview <arch_overview_ssl>`.
.. code-block:: json
{
"cert_chain_file": "...",
"private_key_file": "...",
"alpn_protocols": "...",
"alt_alpn_protocols": "...",
"ca_cert_file": "...",
"verify_certificate_hash": "...",
"verify_subject_alt_name": [],
"crl_file": "...",
"cipher_suites": "...",
"ecdh_curves": "...",
"session_ticket_key_paths": []
}
cert_chain_file
*(required, string)* The certificate chain file that should be served by the listener.
private_key_file
*(required, string)* The private key that corresponds to the certificate chain file.
alpn_protocols
*(optional, string)* Supplies the list of ALPN protocols that the listener should expose. In
practice this is likely to be set to one of two values (see the
:ref:`codec_type <config_http_conn_man_codec_type>` parameter in the HTTP connection
manager for more information):
* "h2,http/1.1" If the listener is going to support both HTTP/2 and HTTP/1.1.
* "http/1.1" If the listener is only going to support HTTP/1.1
.. _config_listener_ssl_context_alt_alpn:
alt_alpn_protocols
*(optional, string)* An alternate ALPN protocol string that can be switched to via runtime. This
is useful for example to disable HTTP/2 without having to deploy a new configuration.
ca_cert_file
*(optional, string)* A file containing certificate authority certificates to use in verifying
a presented client side certificate. If not specified and a client certificate is presented it
will not be verified. By default, a client certificate is optional, unless one of the additional
options (
:ref:`require_client_certificate <config_listener_ssl_context_require_client_certificate>`,
:ref:`verify_certificate_hash <config_listener_ssl_context_verify_certificate_hash>` or
:ref:`verify_subject_alt_name <config_listener_ssl_context_verify_subject_alt_name>`) is also
specified.
.. _config_listener_ssl_context_require_client_certificate:
require_client_certificate
*(optional, boolean)* If specified, Envoy will reject connections without a valid client certificate.
.. _config_listener_ssl_context_verify_certificate_hash:
verify_certificate_hash
*(optional, string)* If specified, Envoy will verify (pin) the hash of the presented client
side certificate.
.. _config_listener_ssl_context_verify_subject_alt_name:
verify_subject_alt_name
*(optional, array)* An optional list of subject alt names. If specified, Envoy will verify
that the client certificate's subject alt name matches one of the specified values.
.. _config_listener_ssl_context_crl_file:
crl_file
*(optional, string)* An optional `certificate revocation list
<http://https://en.wikipedia.org/wiki/Certificate_revocation_list>`_ (in PEM format).
If specified, Envoy will verify that the presented peer certificate has not been revoked by
this CRL. If this file contains multiple CRLs, all of them will be used.
cipher_suites
*(optional, string)* If specified, the TLS listener will only support the specified `cipher list
<https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Cipher-suite-configuration>`_.
If not specified, the default list:
.. code-block:: none
[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]
[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]
ECDHE-ECDSA-AES128-SHA256
ECDHE-RSA-AES128-SHA256
ECDHE-ECDSA-AES128-SHA
ECDHE-RSA-AES128-SHA
AES128-GCM-SHA256
AES128-SHA256
AES128-SHA
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-SHA384
ECDHE-RSA-AES256-SHA384
ECDHE-ECDSA-AES256-SHA
ECDHE-RSA-AES256-SHA
AES256-GCM-SHA384
AES256-SHA256
AES256-SHA
will be used.
ecdh_curves
*(optional, string)* If specified, the TLS connection will only support the specified ECDH curves.
If not specified, the default curves (X25519, P-256) will be used.
session_ticket_key_paths
*(optional, array)* Paths to keyfiles for encrypting and decrypting TLS session tickets. The
first keyfile in the array contains the key to encrypt all new sessions created by this context.
All keys are candidates for decrypting received tickets. This allows for easy rotation of keys
by, for example, putting the new keyfile first, and the previous keyfile second.
If `session_ticket_key_paths` is not specified, the TLS library will still support resuming
sessions via tickets, but it will use an internally-generated and managed key, so sessions cannot
be resumed across hot restarts or on different hosts.
Each keyfile must contain exactly 80 bytes of cryptographically-secure random data. For example,
the output of ``openssl rand 80``.
.. attention::
Using this feature has serious security considerations and risks. Improper handling of keys may
result in loss of secrecy in connections, even if ciphers supporting perfect forward secrecy
are used. See https://www.imperialviolet.org/2013/06/27/botchingpfs.html for some discussion.
To minimize the risk, you must:
* Keep the session ticket keys at least as secure as your TLS certificate private keys
* Rotate session ticket keys at least daily, and preferably hourly
* Always generate keys using a cryptographically-secure random data source

47
docs/root/api-v1/network_filters/client_ssl_auth_filter.rst
Unescape View File

@ -1,47 +0,0 @@
.. _config_network_filters_client_ssl_auth_v1:
Client TLS authentication
=========================
Client TLS authentication :ref:`configuration overview <config_network_filters_client_ssl_auth>`.
.. code-block:: json
{
"name": "client_ssl_auth",
"config": {
"auth_api_cluster": "...",
"stat_prefix": "...",
"refresh_delay_ms": "...",
"ip_white_list": []
}
}
auth_api_cluster
*(required, string)* The :ref:`cluster manager <arch_overview_cluster_manager>` cluster that runs
the authentication service. The filter will connect to the service every 60s to fetch the list
of principals. The service must support the expected :ref:`REST API
<config_network_filters_client_ssl_auth_rest_api>`.
stat_prefix
*(required, string)* The prefix to use when emitting :ref:`statistics
<config_network_filters_client_ssl_auth_stats>`.
refresh_delay_ms
*(optional, integer)* Time in milliseconds between principal refreshes from the authentication
service. Default is 60000 (60s). The actual fetch time will be this value plus a random jittered
value between 0-refresh_delay_ms milliseconds.
ip_white_list
*(optional, array)* An optional list of IP address and subnet masks that should be white listed
for access by the filter. If no list is provided, there is no IP white list. The list is
specified as in the following example:
.. code-block:: json
[
"192.168.3.0/24",
"50.1.2.3/32",
"10.15.0.0/16",
"2001:abcd::/64"
]

13
docs/root/api-v1/network_filters/echo_filter.rst
Unescape View File

@ -1,13 +0,0 @@
.. _config_network_filters_echo_v1:
Echo
====
Echo :ref:`configuration overview <config_network_filters_echo>`.
.. code-block:: json
{
"name": "echo",
"config": {}
}

260
docs/root/api-v1/network_filters/http_conn_man.rst
Unescape View File

@ -1,260 +0,0 @@
.. _config_network_filters_http_conn_man_v1:
HTTP connection manager
=======================
* HTTP connection manager :ref:`architecture overview <arch_overview_http_conn_man>`.
* HTTP protocols :ref:`architecture overview <arch_overview_http_protocols>`.
.. code-block:: json
{
"name": "http_connection_manager",
"config": {
"codec_type": "...",
"stat_prefix": "...",
"rds": "{...}",
"route_config": "{...}",
"filters": [],
"add_user_agent": "...",
"tracing": "{...}",
"http1_settings": "{...}",
"http2_settings": "{...}",
"server_name": "...",
"idle_timeout_s": "...",
"drain_timeout_ms": "...",
"access_log": [],
"use_remote_address": "...",
"forward_client_cert": "...",
"set_current_client_cert": "...",
"generate_request_id": "..."
}
}
.. _config_http_conn_man_codec_type:
codec_type
*(required, string)* Supplies the type of codec that the connection manager should use. Possible
values are:
http1
The connection manager will assume that the client is speaking HTTP/1.1.
http2
The connection manager will assume that the client is speaking HTTP/2 (Envoy does not require
HTTP/2 to take place over TLS or to use ALPN. Prior knowledge is allowed).
auto
For every new connection, the connection manager will determine which codec to use. This mode
supports both ALPN for TLS listeners as well as protocol inference for plaintext listeners.
If ALPN data is available, it is preferred, otherwise protocol inference is used. In almost
all cases, this is the right option to choose for this setting.
.. _config_http_conn_man_stat_prefix:
stat_prefix
*(required, string)* The human readable prefix to use when emitting statistics for the
connection manager. See the :ref:`statistics <config_http_conn_man_stats>` documentation
for more information.
.. _config_http_conn_man_rds_option:
:ref:`rds <config_http_conn_man_rds_v1>`
*(sometimes required, object)* The connection manager configuration must specify one of *rds* or
*route_config*. If *rds* is specified, the connection manager's route table will be dynamically
loaded via the RDS API. See the :ref:`documentation <config_http_conn_man_rds_v1>` for more
information.
.. _config_http_conn_man_route_config:
:ref:`route_config <config_http_conn_man_route_table>`
*(sometimes required, object)* The connection manager configuration must specify one of *rds* or
*route_config*. If *route_config* is specified, the :ref:`route table <arch_overview_http_routing>`
for the connection manager is static and is specified in this property.
:ref:`filters <config_http_conn_man_filters>`
*(required, array)* A list of individual :ref:`HTTP filters <arch_overview_http_filters>` that
make up the filter chain for requests made to the connection manager. Order matters as the filters
are processed sequentially as request events happen.
.. _config_http_conn_man_add_user_agent:
add_user_agent
*(optional, boolean)* Whether the connection manager manipulates the
:ref:`config_http_conn_man_headers_user-agent` and
:ref:`config_http_conn_man_headers_downstream-service-cluster` headers. See the linked
documentation for more information. Defaults to false.
:ref:`tracing <config_http_conn_man_tracing>`
*(optional, object)* Presence of the object defines whether the connection manager
emits :ref:`tracing <arch_overview_tracing>` data to the :ref:`configured tracing provider
<config_tracing_v1>`.
.. _config_http_conn_man_http1_settings:
http1_settings
*(optional, object)* Additional HTTP/1 settings that are passed to the HTTP/1 codec.
allow_absolute_url
*(optional, boolean)* Handle http requests with absolute urls in the requests. These requests
are generally sent by clients to forward/explicit proxies. This allows clients to configure
envoy as their http proxy. In Unix, for example, this is typically done by setting the
http_proxy environment variable.
.. _config_http_conn_man_http2_settings:
http2_settings
*(optional, object)* Additional HTTP/2 settings that are passed directly to the HTTP/2 codec.
Currently supported settings are:
hpack_table_size
*(optional, integer)* `Maximum table size <http://httpwg.org/specs/rfc7541.html#rfc.section.4.2>`_
(in octets) that the encoder is permitted to use for
the dynamic HPACK table. Valid values range from 0 to 4294967295 (2^32 - 1) and defaults to 4096.
0 effectively disables header compression.
max_concurrent_streams
*(optional, integer)* `Maximum concurrent streams
<http://httpwg.org/specs/rfc7540.html#rfc.section.5.1.2>`_
allowed for peer on one HTTP/2 connection.
Valid values range from 1 to 2147483647 (2^31 - 1) and defaults to 2147483647.
.. _config_http_conn_man_http2_settings_initial_stream_window_size:
initial_stream_window_size
*(optional, integer)* `Initial stream-level flow-control window
<http://httpwg.org/specs/rfc7540.html#rfc.section.6.9.2>`_ size. Valid values range from 65535
(2^16 - 1, HTTP/2 default) to 2147483647 (2^31 - 1, HTTP/2 maximum) and defaults to 268435456
(256 * 1024 * 1024).
NOTE: 65535 is the initial window size from HTTP/2 spec. We only support increasing the default window
size now, so it's also the minimum.
This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the
HTTP/2 codec buffers. Once the buffer reaches this pointer, watermark callbacks will fire to
stop the flow of data to the codec buffers.
initial_connection_window_size
*(optional, integer)* Similar to :ref:`initial_stream_window_size
<config_http_conn_man_http2_settings_initial_stream_window_size>`, but for connection-level flow-control
window. Currently , this has the same minimum/maximum/default as :ref:`initial_stream_window_size
<config_http_conn_man_http2_settings_initial_stream_window_size>`.
These are the same options available in the upstream cluster :ref:`http2_settings
<config_cluster_manager_cluster_http2_settings>` option.
.. _config_http_conn_man_server_name:
server_name
*(optional, string)* An optional override that the connection manager will write to the
:ref:`config_http_conn_man_headers_server` header in responses. If not set, the default is
*envoy*.
idle_timeout_s
*(optional, integer)* The idle timeout in seconds for connections managed by the connection
manager. The idle timeout is defined as the period in which there are no active requests. If not
set, there is no idle timeout. When the idle timeout is reached the connection will be closed. If
the connection is an HTTP/2 connection a drain sequence will occur prior to closing the
connection. See :ref:`drain_timeout_ms <config_http_conn_man_drain_timeout_ms>`.
.. _config_http_conn_man_drain_timeout_ms:
drain_timeout_ms
*(optional, integer)* The time in milliseconds that Envoy will wait between sending an HTTP/2
"shutdown notification" (GOAWAY frame with max stream ID) and a final GOAWAY frame. This is used
so that Envoy provides a grace period for new streams that race with the final GOAWAY frame.
During this grace period, Envoy will continue to accept new streams. After the grace period, a
final GOAWAY frame is sent and Envoy will start refusing new streams. Draining occurs both
when a connection hits the idle timeout or during general server draining. The default grace
period is 5000 milliseconds (5 seconds) if this option is not specified.
:ref:`access_log <config_access_log>`
*(optional, array)* Configuration for :ref:`HTTP access logs <arch_overview_access_logs>`
emitted by the connection manager.
.. _config_http_conn_man_use_remote_address:
use_remote_address
*(optional, boolean)* If set to true, the connection manager will use the real remote address
of the client connection when determining internal versus external origin and manipulating
various headers. If set to false or absent, the connection manager will use the
:ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header. See the documentation for
:ref:`config_http_conn_man_headers_x-forwarded-for`,
:ref:`config_http_conn_man_headers_x-envoy-internal`, and
:ref:`config_http_conn_man_headers_x-envoy-external-address` for more information.
.. _config_http_conn_man_forward_client_cert:
forward_client_cert
*(optional, string)* How to handle the
:ref:`config_http_conn_man_headers_x-forwarded-client-cert` (XFCC) HTTP header.
Possible values are:
1. **sanitize**: Do not send the XFCC header to the next hop. This is the default value.
2. **forward_only**: When the client connection is mTLS (Mutual TLS), forward the XFCC header in the request.
3. **always_forward_only**: Always forward the XFCC header in the request, regardless of whether the client connection is mTLS.
4. **append_forward**: When the client connection is mTLS, append the client certificate information to the request's XFCC header and forward it.
5. **sanitize_set**: When the client connection is mTLS, reset the XFCC header with the client certificate information and send it to the next hop.
For the format of the XFCC header, please refer to
:ref:`config_http_conn_man_headers_x-forwarded-client-cert`.
.. _config_http_conn_man_set_current_client_cert_details:
set_current_client_cert_details
*(optional, array)* A list of strings, possible values are *Subject* and *SAN*. This field is
valid only when *forward_client_cert* is *append_forward* or *sanitize_set* and the client
connection is mTLS. It specifies the fields in the client certificate to be forwarded. Note that
in the :ref:`config_http_conn_man_headers_x-forwarded-client-cert` header, `Hash` is always set,
and `By` is always set when the client certificate presents the SAN value.
generate_request_id
*(optional, boolean)* Whether the connection manager will generate the
:ref:`config_http_conn_man_headers_x-request-id` header if it does not exist. This defaults to
*true*. Generating a random UUID4 is expensive so in high throughput scenarios where this
feature is not desired it can be disabled.
.. _config_http_conn_man_tracing:
Tracing
-------
.. code-block:: json
{
"tracing": {
"operation_name": "...",
"request_headers_for_tags": []
}
}
operation_name
*(required, string)* Span name will be derived from operation_name. "ingress" and "egress"
are the only supported values.
request_headers_for_tags
*(optional, array)* A list of header names used to create tags for the active span.
The header name is used to populate the tag name, and the header value is used to populate the
tag value. The tag is created if the specified header name is present in the request's headers.
.. _config_http_conn_man_filters:
Filters
-------
HTTP filter :ref:`architecture overview <arch_overview_http_filters>`.
.. code-block:: json
{
"name": "...",
"config": "{...}"
}
name
*(required, string)* The name of the filter to instantiate. The name must match a :ref:`supported
filter <config_http_filters>`.
config
*(required, object)* Filter specific configuration which depends on the filter being
instantiated. See the :ref:`supported filters <config_http_filters>` for further documentation.

53
docs/root/api-v1/network_filters/mongo_proxy_filter.rst
Unescape View File

@ -1,53 +0,0 @@
.. _config_network_filters_mongo_proxy_v1:
Mongo proxy
===========
MongoDB :ref:`configuration overview <config_network_filters_mongo_proxy>`.
.. code-block:: json
{
"name": "mongo_proxy",
"config": {
"stat_prefix": "...",
"access_log": "...",
"fault": {}
}
}
stat_prefix
*(required, string)* The prefix to use when emitting :ref:`statistics
<config_network_filters_mongo_proxy_stats>`.
access_log
*(optional, string)* The optional path to use for writing Mongo access logs. If not access log
path is specified no access logs will be written. Note that access log is also gated by
:ref:`runtime <config_network_filters_mongo_proxy_runtime>`.
fault
*(optional, object)* If specified, the filter will inject faults based on the values in the object.
Fault configuration
-------------------
Configuration for MongoDB fixed duration delays. Delays are applied to the following MongoDB
operations: Query, Insert, GetMore, and KillCursors. Once an active delay is in progress, all
incoming data up until the timer event fires will be a part of the delay.
.. code-block:: json
{
"fixed_delay": {
"percent": "...",
"duration_ms": "..."
}
}
percent
*(required, integer)* Probability of an eligible MongoDB operation to be affected by the
injected fault when there is no active fault. Valid values are integers in a range of [0, 100].
duration_ms
*(required, integer)* Non-negative delay duration in milliseconds.

8
docs/root/api-v1/network_filters/network_filters.rst
Unescape View File

@ -1,8 +0,0 @@
Network filters
===============
.. toctree::
:glob:
:maxdepth: 2
*

40
docs/root/api-v1/network_filters/rate_limit_filter.rst
Unescape View File

@ -1,40 +0,0 @@
.. _config_network_filters_rate_limit_v1:
Rate limit
==========
Rate limit :ref:`configuration overview <config_network_filters_rate_limit>`.
.. code-block:: json
{
"name": "ratelimit",
"config": {
"stat_prefix": "...",
"domain": "...",
"descriptors": [],
"timeout_ms": "..."
}
}
stat_prefix
*(required, string)* The prefix to use when emitting :ref:`statistics
<config_network_filters_rate_limit_stats>`.
domain
*(required, string)* The rate limit domain to use in the rate limit service request.
descriptors
*(required, array)* The rate limit descriptor list to use in the rate limit service request. The
descriptors are specified as in the following example:
.. code-block:: json
[
[{"key": "hello", "value": "world"}, {"key": "foo", "value": "bar"}],
[{"key": "foo2", "value": "bar2"}]
]
timeout_ms
*(optional, integer)* The timeout in milliseconds for the rate limit service RPC. If not set,
this defaults to 20ms.

46
docs/root/api-v1/network_filters/redis_proxy_filter.rst
Unescape View File

@ -1,46 +0,0 @@
.. _config_network_filters_redis_proxy_v1:
Redis proxy
===========
Redis proxy :ref:`configuration overview <config_network_filters_redis_proxy>`.
.. code-block:: json
{
"name": "redis_proxy",
"config": {
"cluster_name": "...",
"conn_pool": "{...}",
"stat_prefix": "..."
}
}
cluster_name
*(required, string)* Name of cluster from cluster manager.
See the :ref:`configuration section <arch_overview_redis_configuration>` of the architecture
overview for recommendations on configuring the backing cluster.
conn_pool
*(required, object)* Connection pool configuration.
stat_prefix
*(required, string)* The prefix to use when emitting :ref:`statistics
<config_network_filters_redis_proxy_stats>`.
Connection pool configuration
-----------------------------
.. code-block:: json
{
"op_timeout_ms": "...",
}
op_timeout_ms
*(required, integer)* Per-operation timeout in milliseconds. The timer starts when the first
command of a pipeline is written to the backend connection. Each response received from Redis
resets the timer since it signifies that the next command is being processed by the backend.
The only exception to this behavior is when a connection to a backend is not yet established. In
that case, the connect timeout on the cluster will govern the timeout until the connection is
ready.

126
docs/root/api-v1/network_filters/tcp_proxy_filter.rst
Unescape View File

@ -1,126 +0,0 @@
.. _config_network_filters_tcp_proxy_v1:
TCP proxy
=========
TCP proxy :ref:`configuration overview <config_network_filters_tcp_proxy>`.
.. code-block:: json
{
"name": "tcp_proxy",
"config": {
"stat_prefix": "...",
"route_config": "{...}",
"access_log": []
}
}
:ref:`route_config <config_network_filters_tcp_proxy_route_config>`
*(required, object)* The route table for the filter.
All filter instances must have a route table, even if it is empty.
stat_prefix
*(required, string)* The prefix to use when emitting :ref:`statistics
<config_network_filters_tcp_proxy_stats>`.
:ref:`access_log <config_access_log>`
*(optional, array)* Configuration for :ref:`access logs <arch_overview_access_logs>`
emitted by the this tcp_proxy.
.. _config_network_filters_tcp_proxy_route_config:
Route Configuration
-------------------
.. code-block:: json
{
"routes": []
}
:ref:`routes <config_network_filters_tcp_proxy_route>`
*(required, array)* An array of route entries that make up the route table.
.. _config_network_filters_tcp_proxy_route:
Route
-----
A TCP proxy route consists of a set of optional L4 criteria and the name of a
:ref:`cluster <config_cluster_manager_cluster>`. If a downstream connection matches
all the specified criteria, the cluster in the route is used for the corresponding upstream
connection. Routes are tried in the order specified until a match is found. If no match is
found, the connection is closed. A route with no criteria is valid and always produces a match.
.. code-block:: json
{
"cluster": "...",
"destination_ip_list": [],
"destination_ports": "...",
"source_ip_list": [],
"source_ports": "..."
}
cluster
*(required, string)* The :ref:`cluster <config_cluster_manager_cluster>` to connect
to when a the downstream network connection matches the specified criteria.
destination_ip_list
*(optional, array)* An optional list of IP address subnets in the form "ip_address/xx".
The criteria is satisfied if the destination IP address of the downstream connection is
contained in at least one of the specified subnets.
If the parameter is not specified or the list is empty, the destination IP address is ignored.
The destination IP address of the downstream connection might be different from the addresses
on which the proxy is listening if the connection has been redirected. Example:
.. code-block:: json
[
"192.168.3.0/24",
"50.1.2.3/32",
"10.15.0.0/16",
"2001:abcd::/64"
]
destination_ports
*(optional, string)* An optional string containing a comma-separated list of port numbers or
ranges. The criteria is satisfied if the destination port of the downstream connection
is contained in at least one of the specified ranges.
If the parameter is not specified, the destination port is ignored. The destination port address
of the downstream connection might be different from the port on which the proxy is listening if
the connection has been redirected. Example:
.. code-block:: json
{
"destination_ports": "1-1024,2048-4096,12345"
}
source_ip_list
*(optional, array)* An optional list of IP address subnets in the form "ip_address/xx".
The criteria is satisfied if the source IP address of the downstream connection is contained
in at least one of the specified subnets. If the parameter is not specified or the list is empty,
the source IP address is ignored. Example:
.. code-block:: json
[
"192.168.3.0/24",
"50.1.2.3/32",
"10.15.0.0/16",
"2001:abcd::/64"
]
source_ports
*(optional, string)* An optional string containing a comma-separated list of port numbers or
ranges. The criteria is satisfied if the source port of the downstream connection is contained
in at least one of the specified ranges. If the parameter is not specified, the source port is
ignored. Example:
.. code-block:: json
{
"source_ports": "1-1024,2048-4096,12345"
}

28
docs/root/api-v1/rate_limit.rst
Unescape View File

@ -1,28 +0,0 @@
.. _config_rate_limit_service_v1:
Rate limit service
==================
Rate limit :ref:`configuration overview <config_rate_limit_service>`.
.. code-block:: json
{
"type": "grpc_service",
"config": {
"cluster_name": "..."
}
}
type
*(required, string)* Specifies the type of rate limit service to call. Currently the only
supported option is *grpc_service* which specifies Lyft's global rate limit service and
associated IDL.
config
*(required, object)* Specifies type specific configuration for the rate limit service.
cluster_name
*(required, string)* Specifies the cluster manager cluster name that hosts the rate limit
service. The client will connect to this cluster when it needs to make rate limit service
requests.

183
docs/root/api-v1/route_config/rate_limits.rst
Unescape View File

@ -1,183 +0,0 @@
.. _config_http_conn_man_route_table_rate_limit_config:
Rate limit configuration
========================
Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`.
.. code-block:: json
{
"stage": "...",
"disable_key": "...",
"actions": []
}
stage
*(optional, integer)* Refers to the stage set in the filter. The rate limit configuration
only applies to filters with the same stage number. The default stage number is 0.
**NOTE:** The filter supports a range of 0 - 10 inclusively for stage numbers.
disable_key
*(optional, string)* The key to be set in runtime to disable this rate limit configuration.
actions
*(required, array)* A list of actions that are to be applied for this rate limit configuration.
Order matters as the actions are processed sequentially and the descriptor is composed by
appending descriptor entries in that sequence. If an action cannot append a descriptor entry,
no descriptor is generated for the configuration. See :ref:`composing actions
<config_http_filters_rate_limit_composing_actions>` for additional documentation.
.. _config_http_conn_man_route_table_rate_limit_actions:
Actions
-------
.. code-block:: json
{
"type": "..."
}
type
*(required, string)* The type of rate limit action to perform. The currently supported action
types are *source_cluster*, *destination_cluster* , *request_headers*, *remote_address*,
*generic_key* and *header_value_match*.
Source Cluster
^^^^^^^^^^^^^^
.. code-block:: json
{
"type": "source_cluster"
}
The following descriptor entry is appended to the descriptor:
.. code-block:: cpp
("source_cluster", "<local service cluster>")
<local service cluster> is derived from the :option:`--service-cluster` option.
Destination Cluster
^^^^^^^^^^^^^^^^^^^
.. code-block:: json
{
"type": "destination_cluster"
}
The following descriptor entry is appended to the descriptor:
.. code-block:: cpp
("destination_cluster", "<routed target cluster>")
Once a request matches against a route table rule, a routed cluster is determined by one of the
following :ref:`route table configuration <config_http_conn_man_route_table_route_cluster>`
settings:
* :ref:`cluster <config_http_conn_man_route_table_route_cluster>` indicates the upstream cluster
to route to.
* :ref:`weighted_clusters <config_http_conn_man_route_table_route_config_weighted_clusters>`
chooses a cluster randomly from a set of clusters with attributed weight.
* :ref:`cluster_header<config_http_conn_man_route_table_route_cluster_header>` indicates which
header in the request contains the target cluster.
Request Headers
^^^^^^^^^^^^^^^
.. code-block:: json
{
"type": "request_headers",
"header_name": "...",
"descriptor_key" : "..."
}
header_name
*(required, string)* The header name to be queried from the request headers. The header's value is
used to populate the value of the descriptor entry for the descriptor_key.
descriptor_key
*(required, string)* The key to use in the descriptor entry.
The following descriptor entry is appended when a header contains a key that matches the
*header_name*:
.. code-block:: cpp
("<descriptor_key>", "<header_value_queried_from_header>")
Remote Address
^^^^^^^^^^^^^^
.. code-block:: json
{
"type": "remote_address"
}
The following descriptor entry is appended to the descriptor and is populated using the trusted
address from :ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>`:
.. code-block:: cpp
("remote_address", "<trusted address from x-forwarded-for>")
Generic Key
^^^^^^^^^^^
.. code-block:: json
{
"type": "generic_key",
"descriptor_value" : "..."
}
descriptor_value
*(required, string)* The value to use in the descriptor entry.
The following descriptor entry is appended to the descriptor:
.. code-block:: cpp
("generic_key", "<descriptor_value>")
Header Value Match
^^^^^^^^^^^^^^^^^^
.. code-block:: json
{
"type": "header_value_match",
"descriptor_value" : "...",
"expect_match" : "...",
"headers" : []
}
descriptor_value
*(required, string)* The value to use in the descriptor entry.
expect_match
*(optional, boolean)* If set to true, the action will append a descriptor entry when the request
matches the :ref:`headers<config_http_conn_man_route_table_route_headers>`. If set to false,
the action will append a descriptor entry when the request does not match the
:ref:`headers<config_http_conn_man_route_table_route_headers>`. The default value is true.
:ref:`headers<config_http_conn_man_route_table_route_headers>`
*(required, array)* Specifies a set of headers that the rate limit action should match on. The
action will check the request's headers against all the specified headers in the config. A match
will happen if all the headers in the config are present in the request with the same values (or
based on presence if the ``value`` field is not in the config).
The following descriptor entry is appended to the descriptor:
.. code-block:: cpp
("header_match", "<descriptor_value>")

63
docs/root/api-v1/route_config/rds.rst
Unescape View File

@ -1,63 +0,0 @@
.. _config_http_conn_man_rds_v1:
Route discovery service (RDS)
=============================
.. code-block:: json
{
"cluster": "...",
"route_config_name": "...",
"refresh_delay_ms": "..."
}
cluster
*(required, string)* The name of an upstream :ref:`cluster <config_cluster_manager_cluster>` that
hosts the route discovery service. The cluster must run a REST service that implements the
:ref:`RDS HTTP API <config_http_conn_man_rds_v1_api>`. NOTE: This is the *name* of a statically defined
cluster in the :ref:`cluster manager <config_cluster_manager>` configuration, not the full definition of
a cluster as in the case of SDS and CDS.
route_config_name
*(required, string)* The name of the route configuration. This name will be passed to the
:ref:`RDS HTTP API <config_http_conn_man_rds_v1_api>`. This allows an Envoy configuration with
multiple HTTP listeners (and associated HTTP connection manager filters) to use different route
configurations. By default, the maximum length of the name is limited to 60 characters. This
limit can be increased by setting the :option:`--max-obj-name-len` command line argument to the
desired value.
refresh_delay_ms
*(optional, integer)* The delay, in milliseconds, between fetches to the RDS API. Envoy will add
an additional random jitter to the delay that is between zero and *refresh_delay_ms*
milliseconds. Thus the longest possible refresh delay is 2 \* *refresh_delay_ms*. Default
value is 30000ms (30 seconds).
.. _config_http_conn_man_rds_v1_api:
REST API
--------
.. http:get:: /v1/routes/(string: route_config_name)/(string: service_cluster)/(string: service_node)
Asks the route discovery service to return the route configuration for a particular
`route_config_name`, `service_cluster`, and `service_node`. `route_config_name` corresponds to the
RDS configuration parameter above. `service_cluster` corresponds to the :option:`--service-cluster`
CLI option. `service_node` corresponds to the :option:`--service-node` CLI option. Responses are a
single JSON object that contains a route configuration as defined in the :ref:`route configuration
documentation <config_http_conn_man_route_table>`.
A new route configuration will be gracefully swapped in such that existing requests are not
affected. This means that when a request starts, it sees a consistent snapshot of the route
configuration that does not change for the duration of the request. Thus, if an update changes a
timeout for example, only new requests will use the updated timeout value.
As a performance optimization, Envoy hashes the route configuration it receives from the RDS API and
will only perform a full reload if the hash value changes.
.. attention::
Route configurations that are loaded via RDS are *not* checked to see if referenced clusters are
known to the :ref:`cluster manager <config_cluster_manager>`. The RDS API has been designed to
work alongside the :ref:`CDS API <config_cluster_manager_cds>` such that Envoy assumes eventually
consistent updates. If a route references an unknown cluster a 404 response will be returned by
the router filter.

553
docs/root/api-v1/route_config/route.rst
Unescape View File

@ -1,553 +0,0 @@
.. _config_http_conn_man_route_table_route:
Route
=====
A route is both a specification of how to match a request as well as in indication of what to do
next (e.g., redirect, forward, rewrite, etc.).
.. attention::
Envoy supports routing on HTTP method via :ref:`header matching
<config_http_conn_man_route_table_route_headers>`.
.. code-block:: json
{
"prefix": "...",
"path": "...",
"regex": "...",
"cluster": "...",
"cluster_header": "...",
"weighted_clusters" : "{...}",
"host_redirect": "...",
"path_redirect": "...",
"prefix_rewrite": "...",
"host_rewrite": "...",
"auto_host_rewrite": "...",
"case_sensitive": "...",
"use_websocket": "...",
"timeout_ms": "...",
"runtime": "{...}",
"retry_policy": "{...}",
"shadow": "{...}",
"priority": "...",
"headers": [],
"rate_limits": [],
"include_vh_rate_limits" : "...",
"hash_policy": "{...}",
"request_headers_to_add" : [],
"opaque_config": [],
"cors": "{...}",
"decorator" : "{...}"
}
prefix
*(sometimes required, string)* If specified, the route is a prefix rule meaning that the prefix
must match the beginning of the :path header. One of *prefix*, *path*, or *regex* must be specified.
path
*(sometimes required, string)* If specified, the route is an exact path rule meaning that the path
must exactly match the :path header once the query string is removed. One of *prefix*, *path*, or
*regex* must be specified.
regex
*(sometimes required, string)* If specified, the route is a regular expression rule meaning that the
regex must match the :path header once the query string is removed. The entire path (without the
query string) must match the regex. The rule will not match if only a subsequence of the :path header
matches the regex. The regex grammar is defined `here
<http://en.cppreference.com/w/cpp/regex/ecmascript>`_. One of *prefix*, *path*, or
*regex* must be specified.
Examples:
* The regex */b[io]t* matches the path */bit*
* The regex */b[io]t* matches the path */bot*
* The regex */b[io]t* does not match the path */bite*
* The regex */b[io]t* does not match the path */bit/bot*
:ref:`cors <config_http_conn_man_route_table_cors>`
*(optional, object)* Specifies the route's CORS policy.
.. _config_http_conn_man_route_table_route_cluster:
cluster
*(sometimes required, string)* If the route is not a redirect (*host_redirect* and/or
*path_redirect* is not specified), one of *cluster*, *cluster_header*, or *weighted_clusters* must
be specified. When *cluster* is specified, its value indicates the upstream cluster to which the
request should be forwarded to.
.. _config_http_conn_man_route_table_route_cluster_header:
cluster_header
*(sometimes required, string)* If the route is not a redirect (*host_redirect* and/or
*path_redirect* is not specified), one of *cluster*, *cluster_header*, or *weighted_clusters* must
be specified. When *cluster_header* is specified, Envoy will determine the cluster to route to
by reading the value of the HTTP header named by *cluster_header* from the request headers.
If the header is not found or the referenced cluster does not exist, Envoy will return a 404
response.
.. attention::
Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 *Host*
header. Thus, if attempting to match on *Host*, match on *:authority* instead.
.. _config_http_conn_man_route_table_route_config_weighted_clusters:
:ref:`weighted_clusters <config_http_conn_man_route_table_route_weighted_clusters>`
*(sometimes required, object)* If the route is not a redirect (*host_redirect* and/or
*path_redirect* is not specified), one of *cluster*, *cluster_header*, or *weighted_clusters* must
be specified. With the *weighted_clusters* option, multiple upstream clusters can be specified for
a given route. The request is forwarded to one of the upstream clusters based on weights assigned
to each cluster. See :ref:`traffic splitting <config_http_conn_man_route_table_traffic_splitting_split>`
for additional documentation.
.. _config_http_conn_man_route_table_route_host_redirect:
host_redirect
*(sometimes required, string)* Indicates that the route is a redirect rule. If there is a match,
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 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. The router filter will place
the original path before rewrite into the :ref:`x-envoy-original-path
<config_http_filters_router_x-envoy-original-path>` header.
.. _config_http_conn_man_route_table_route_prefix_rewrite:
prefix_rewrite
*(optional, string)* Indicates that during forwarding, the matched prefix (or path) should be
swapped with this value. When using regex path matching, the entire path (not including
the query string) will be swapped with this value. This option allows application URLs to be
rooted at a different path from those exposed at the reverse proxy layer.
.. _config_http_conn_man_route_table_route_host_rewrite:
host_rewrite
*(optional, string)* Indicates that during forwarding, the host header will be swapped with this
value.
.. _config_http_conn_man_route_table_route_auto_host_rewrite:
auto_host_rewrite
*(optional, boolean)* Indicates that during forwarding, the host header will be swapped with the
hostname of the upstream host chosen by the cluster manager. This option is applicable only when
the destination cluster for a route is of type *strict_dns* or *logical_dns*. Setting this to true
with other cluster types has no effect. *auto_host_rewrite* and *host_rewrite* are mutually exclusive
options. Only one can be specified.
.. _config_http_conn_man_route_table_route_case_sensitive:
case_sensitive
*(optional, boolean)* Indicates that prefix/path matching should be case sensitive. The default
is true.
.. _config_http_conn_man_route_table_route_use_websocket:
use_websocket
*(optional, boolean)* Indicates that a HTTP/1.1 client connection to this particular route
should be allowed to upgrade to a WebSocket connection. The default is false.
.. attention::
If set to true, Envoy will expect the first request matching this route to contain WebSocket
upgrade headers. If the headers are not present, the connection will be processed as a normal
HTTP/1.1 connection. If the upgrade headers are present, Envoy will setup plain TCP proxying
between the client and the upstream server. Hence, an upstream server that rejects the WebSocket
upgrade request is also responsible for closing the associated connection. Until then, Envoy will
continue to proxy data from the client to the upstream server.
Redirects, timeouts and retries are not supported on requests with WebSocket upgrade headers.
.. _config_http_conn_man_route_table_route_timeout:
timeout_ms
*(optional, integer)* Specifies the timeout for the route. If not specified, the default is 15s.
Note that this timeout includes all retries. See also
:ref:`config_http_filters_router_x-envoy-upstream-rq-timeout-ms`,
:ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms`, and the
:ref:`retry overview <arch_overview_http_routing_retry>`.
:ref:`runtime <config_http_conn_man_route_table_route_runtime>`
*(optional, object)* Indicates that the route should additionally match on a runtime key.
:ref:`retry_policy <config_http_conn_man_route_table_route_retry>`
*(optional, object)* Indicates that the route has a retry policy.
:ref:`shadow <config_http_conn_man_route_table_route_shadow>`
*(optional, object)* Indicates that the route has a shadow policy.
priority
*(optional, string)* Optionally specifies the :ref:`routing priority
<arch_overview_http_routing_priority>`.
:ref:`headers <config_http_conn_man_route_table_route_headers>`
*(optional, array)* Specifies a set of headers that the route should match on. The router will
check the request's headers against all the specified headers in the route config. A match will
happen if all the headers in the route are present in the request with the same values (or based
on presence if the ``value`` field is not in the config).
request_headers_to_add
*(optional, array)* Specifies a list of HTTP headers that should be added to each
request handled by this virtual host. Headers are specified in the following form:
.. code-block:: json
[
{"key": "header1", "value": "value1"},
{"key": "header2", "value": "value2"}
]
For more information see the documentation on :ref:`custom request headers
<config_http_conn_man_headers_custom_request_headers>`.
:ref:`opaque_config <config_http_conn_man_route_table_opaque_config>`
*(optional, array)* Specifies a set of optional route configuration values that can be accessed by filters.
.. _config_http_conn_man_route_table_route_rate_limits:
:ref:`rate_limits <config_http_conn_man_route_table_rate_limit_config>`
*(optional, array)* Specifies a set of rate limit configurations that could be applied to the
route.
.. _config_http_conn_man_route_table_route_include_vh:
include_vh_rate_limits
*(optional, boolean)* Specifies if the rate limit filter should include the virtual host rate
limits. By default, if the route configured rate limits, the virtual host
:ref:`rate_limits <config_http_conn_man_route_table_rate_limit_config>` are not applied to the
request.
:ref:`hash_policy <config_http_conn_man_route_table_hash_policy>`
*(optional, object)* Specifies the route's hashing policy if the upstream cluster uses a hashing
:ref:`load balancer <arch_overview_load_balancing_types>`.
:ref:`decorator <config_http_conn_man_route_table_decorator>`
*(optional, object)* Specifies the route's decorator used to enhance information reported about
the matched request.
.. _config_http_conn_man_route_table_route_runtime:
Runtime
-------
A :ref:`runtime <arch_overview_runtime>` route configuration can be used to roll out route changes
in a gradual manner without full code/config deploys. Refer to the
:ref:`traffic shifting <config_http_conn_man_route_table_traffic_splitting_shift>` docs
for additional documentation.
.. code-block:: json
{
"key": "...",
"default": "..."
}
key
*(required, string)* Specifies the runtime key name that should be consulted to determine whether
the route matches or not. See the :ref:`runtime documentation <operations_runtime>` for how key
names map to the underlying implementation.
.. _config_http_conn_man_route_table_route_runtime_default:
default
*(required, integer)* An integer between 0-100. Every time the route is considered for a match,
a random number between 0-99 is selected. If the number is <= the value found in the *key*
(checked first) or, if the key is not present, the default value, the route is a match (assuming
everything also about the route matches).
.. _config_http_conn_man_route_table_route_retry:
Retry policy
------------
HTTP retry :ref:`architecture overview <arch_overview_http_routing_retry>`.
.. code-block:: json
{
"retry_on": "...",
"num_retries": "...",
"per_try_timeout_ms" : "..."
}
retry_on
*(required, string)* Specifies the conditions under which retry takes place. These are the same
conditions documented for :ref:`config_http_filters_router_x-envoy-retry-on` and
:ref:`config_http_filters_router_x-envoy-retry-grpc-on`.
num_retries
*(optional, integer)* Specifies the allowed number of retries. This parameter is optional and
defaults to 1. These are the same conditions documented for
:ref:`config_http_filters_router_x-envoy-max-retries`.
per_try_timeout_ms
*(optional, integer)* Specifies a non-zero timeout per retry attempt. This parameter is optional.
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
would have been exhausted.
.. _config_http_conn_man_route_table_route_shadow:
Shadow
------
The router is capable of shadowing traffic from one cluster to another. The current implementation
is "fire and forget," meaning Envoy will not wait for the shadow cluster to respond before returning
the response from the primary cluster. All normal statistics are collected for the shadow
cluster making this feature useful for testing.
During shadowing, the host/authority header is altered such that *-shadow* is appended. This is
useful for logging. For example, *cluster1* becomes *cluster1-shadow*.
.. code-block:: json
{
"cluster": "...",
"runtime_key": "..."
}
cluster
*(required, string)* Specifies the cluster that requests will be shadowed to. The cluster must
exist in the :ref:`cluster manager configuration <config_cluster_manager>`.
runtime_key
*(optional, string)* If not specified, **all** requests to the target cluster will be shadowed.
If specified, Envoy will lookup the runtime key to get the % of requests to shadow. Valid values are
from 0 to 10000, allowing for increments of 0.01% of requests to be shadowed. If the runtime key
is specified in the configuration but not present in runtime, 0 is the default and thus 0% of
requests will be shadowed.
.. _config_http_conn_man_route_table_route_headers:
Headers
-------
.. code-block:: json
{
"name": "...",
"value": "...",
"regex": "...",
"range_match": "..."
}
name
*(required, string)* Specifies the name of the header in the request.
value
*(optional, string)* Specifies the value of the header. If the value is absent a request that has
the *name* header will match, regardless of the header's value.
regex
*(optional, boolean)* Specifies whether the header value is a regular
expression or not. Defaults to false. The entire request header value must match the regex. The
rule will not match if only a subsequence of the request header value matches the regex. The
regex grammar used in the value field is defined
`here <http://en.cppreference.com/w/cpp/regex/ecmascript>`_.
Examples:
* The regex *\d{3}* matches the value *123*
* The regex *\d{3}* does not match the value *1234*
* The regex *\d{3}* does not match the value *123.456*
:ref:`range_match <config_http_conn_man_route_table_range>`
*(optional, object)* Specifies the range that will be used for header matching.
.. attention::
Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 *Host*
header. Thus, if attempting to match on *Host*, match on *:authority* instead.
.. attention::
To route on HTTP method, use the special HTTP/2 *:method* header. This works for both
HTTP/1 and HTTP/2 as Envoy normalizes headers. E.g.,
.. code-block:: json
{
"name": ":method",
"value": "POST"
}
.. _config_http_conn_man_route_table_route_weighted_clusters:
Weighted Clusters
-----------------
Compared to the ``cluster`` field that specifies a single upstream cluster as the target
of a request, the ``weighted_clusters`` option allows for specification of multiple upstream clusters
along with weights that indicate the **percentage** of traffic to be forwarded to each cluster.
The router selects an upstream cluster based on the weights.
.. code-block:: json
{
"clusters": [],
"runtime_key_prefix" : "..."
}
clusters
*(required, array)* Specifies one or more upstream clusters associated with the route.
.. code-block:: json
{
"name" : "...",
"weight": "..."
}
name
*(required, string)* Name of the upstream cluster. The cluster must exist in the
:ref:`cluster manager configuration <config_cluster_manager>`.
weight
*(required, integer)* An integer between 0-100. When a request matches the route,
the choice of an upstream cluster is determined by its weight. The sum of
weights across all entries in the *clusters* array must add up to 100.
runtime_key_prefix
*(optional, string)* Specifies the runtime key prefix that should be used to construct the runtime
keys associated with each cluster. When the ``runtime_key_prefix`` is specified, the router will
look for weights associated with each upstream cluster under the key
``runtime_key_prefix + "." + cluster[i].name`` where ``cluster[i]`` denotes an entry in the
``clusters`` array field. If the runtime key for the cluster does not exist, the value specified
in the configuration file will be used as the default weight.
See the :ref:`runtime documentation <operations_runtime>` for how key names map to the
underlying implementation.
**Note:** If the sum of runtime weights exceed 100, the traffic splitting behavior
is undefined (although the request will be routed to one of the clusters).
.. _config_http_conn_man_route_table_hash_policy:
Hash policy
-----------
Specifies the route's hashing policy if the upstream cluster uses a hashing :ref:`load balancer
<arch_overview_load_balancing_types>`.
.. code-block:: json
{
"header_name": "..."
}
header_name
*(required, string)* The name of the request header that will be used to obtain the hash key. If
the request header is not present, the load balancer will use a random number as the hash,
effectively making the load balancing policy random.
.. _config_http_conn_man_route_table_decorator:
Decorator
---------
Specifies the route's decorator.
.. code-block:: json
{
"operation": "..."
}
operation
*(required, string)* The operation name associated with the request matched to this route. If tracing is
enabled, this information will be used as the span name reported for this request. NOTE: For ingress
(inbound) requests, or egress (outbound) responses, this value may be overridden by the
:ref:`x-envoy-decorator-operation <config_http_filters_router_x-envoy-decorator-operation>` header.
.. _config_http_conn_man_route_table_opaque_config:
Opaque Config
-------------
Additional configuration can be provided to filters through the "Opaque Config" mechanism. A
list of properties are specified in the route config. The configuration is uninterpreted
by envoy and can be accessed within a user-defined filter. The configuration is a generic
string map. Nested objects are not supported.
.. code-block:: json
[
{"...": "..."}
]
.. _config_http_conn_man_route_table_cors:
Cors
--------
Settings on a route take precedence over settings on the virtual host.
.. code-block:: json
{
"enabled": false,
"allow_origin": ["http://foo.example"],
"allow_methods": "POST, GET, OPTIONS",
"allow_headers": "Content-Type",
"allow_credentials": false,
"expose_headers": "X-Custom-Header",
"max_age": "86400"
}
enabled
*(optional, boolean)* Defaults to true. Setting *enabled* to false on a route disables CORS
for this route only. The setting has no effect on a virtual host.
allow_origin
*(optional, array)* The origins that will be allowed to do CORS request.
Wildcard "\*" will allow any origin.
allow_methods
*(optional, string)* The content for the *access-control-allow-methods* header.
Comma separated list of HTTP methods.
allow_headers
*(optional, string)* The content for the *access-control-allow-headers* header.
Comma separated list of HTTP headers.
allow_credentials
*(optional, boolean)* Whether the resource allows credentials.
expose_headers
*(optional, string)* The content for the *access-control-expose-headers* header.
Comma separated list of HTTP headers.
max_age
*(optional, string)* The content for the *access-control-max-age* header.
Value in seconds for how long the response to the preflight request can be cached.
.. _config_http_conn_man_route_table_range:
range_match
--------------
Specifies the int64 start and end of the range using half-open interval semantics [start, end).
Header route matching will be performed if the header's value lies within this range.
.. code-block:: json
{
"start": "...",
"end": "..."
}
start
*(required, integer)* start of the range (inclusive).
end
*(required, integer)* end of the range (exclusive).

92
docs/root/api-v1/route_config/route_config.rst
Unescape View File

@ -1,92 +0,0 @@
.. _config_http_conn_man_route_table:
HTTP Route configuration
========================
* Routing :ref:`architecture overview <arch_overview_http_routing>`
* HTTP :ref:`router filter <config_http_filters_router>`
.. code-block:: json
{
"validate_clusters": "...",
"virtual_hosts": [],
"internal_only_headers": [],
"response_headers_to_add": [],
"response_headers_to_remove": [],
"request_headers_to_add": []
}
.. _config_http_conn_man_route_table_validate_clusters:
validate_clusters
*(optional, boolean)* An optional boolean that specifies whether the clusters that the route
table refers to will be validated by the cluster manager. If set to true and a route refers to
a non-existent cluster, the route table will not load. If set to false and a route refers to a
non-existent cluster, the route table will load and the router filter will return a 404 if the
route is selected at runtime. This setting defaults to true if the route table is statically
defined via the :ref:`route_config <config_http_conn_man_route_config>` option. This setting
default to false if the route table is loaded dynamically via the :ref:`rds
<config_http_conn_man_rds_option>` option. Users may which to override the default behavior in
certain cases (for example when using :ref:`cds <config_cluster_manager_cds_v1>` with a static
route table).
:ref:`virtual_hosts <config_http_conn_man_route_table_vhost>`
*(required, array)* An array of virtual hosts that make up the route table.
internal_only_headers
*(optional, array)* Optionally specifies a list of HTTP headers that the connection manager
will consider to be internal only. If they are found on external requests they will be cleaned
prior to filter invocation. See :ref:`config_http_conn_man_headers_x-envoy-internal` for more
information. Headers are specified in the following form:
.. code-block:: json
["header1", "header2"]
response_headers_to_add
*(optional, array)* Optionally specifies a list of HTTP headers that should be added to each
response that the connection manager encodes. Headers are specified in the following form:
.. code-block:: json
[
{"key": "header1", "value": "value1"},
{"key": "header2", "value": "value2"}
]
For more information, including details on header value syntax, see the documentation on
:ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
response_headers_to_remove
*(optional, array)* Optionally specifies a list of HTTP headers that should be removed from each
response that the connection manager encodes. Headers are specified in the following form:
.. code-block:: json
["header1", "header2"]
.. _config_http_conn_man_route_table_add_req_headers:
request_headers_to_add
*(optional, array)* Specifies a list of HTTP headers that should be added to each
request forwarded by the HTTP connection manager. Headers are specified in the following form:
.. code-block:: json
[
{"key": "header1", "value": "value1"},
{"key": "header2", "value": "value2"}
]
For more information, including details on header value syntax, see the documentation on
:ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
.. toctree::
:hidden:
vhost
route
vcluster
rate_limits
rds

47
docs/root/api-v1/route_config/vcluster.rst
Unescape View File

@ -1,47 +0,0 @@
.. _config_http_conn_man_route_table_vcluster:
Virtual cluster
===============
A virtual cluster is a way of specifying a regex matching rule against certain important endpoints
such that statistics are generated explicitly for the matched requests. The reason this is useful is
that when doing prefix/path matching Envoy does not always know what the application considers to
be an endpoint. Thus, it's impossible for Envoy to generically emit per endpoint statistics.
However, often systems have highly critical endpoints that they wish to get "perfect" statistics on.
Virtual cluster statistics are perfect in the sense that they are emitted on the downstream side
such that they include network level failures.
.. note::
Virtual clusters are a useful tool, but we do not recommend setting up a virtual cluster for
every application endpoint. This is both not easily maintainable as well as the matching and
statistics output are not free.
.. code-block:: json
{
"pattern": "...",
"name": "...",
"method": "..."
}
pattern
*(required, string)* Specifies a regex pattern to use for matching requests. The entire path of the request
must match the regex. The regex grammar used is defined `here <http://en.cppreference.com/w/cpp/regex/ecmascript>`_.
name
*(required, string)* Specifies the name of the virtual cluster. The virtual cluster name as well
as the virtual host name are used when emitting statistics. The statistics are emitted by the
router filter and are documented :ref:`here <config_http_filters_router_stats>`.
method
*(optional, string)* Optionally specifies the HTTP method to match on. For example *GET*, *PUT*,
etc.
Examples:
* The regex */rides/\d+* matches the path */rides/0*
* The regex */rides/\d+* matches the path */rides/123*
* The regex */rides/\d+* does not match the path */rides/123/456*
Documentation for :ref:`virtual cluster statistics <config_http_filters_router_stats>`.

84
docs/root/api-v1/route_config/vhost.rst
Unescape View File

@ -1,84 +0,0 @@
.. _config_http_conn_man_route_table_vhost:
Virtual host
============
The top level element in the routing configuration is a virtual host. Each virtual host has
a logical name as well as a set of domains that get routed to it based on the incoming request's
host header. This allows a single listener to service multiple top level domain path trees. Once a
virtual host is selected based on the domain, the routes are processed in order to see which
upstream cluster to route to or whether to perform a redirect.
.. code-block:: json
{
"name": "...",
"domains": [],
"routes": [],
"require_ssl": "...",
"virtual_clusters": [],
"rate_limits": [],
"request_headers_to_add": []
}
name
*(required, string)* The logical name of the virtual host. This is used when emitting certain
statistics but is not relevant for forwarding. By default, the maximum length of the name is
limited to 60 characters. This limit can be increased by setting the
:option:`--max-obj-name-len` command line argument to the desired value.
domains
*(required, array)* A list of domains (host/authority header) that will be matched to this
virtual host. Wildcard hosts are supported in the form of "\*.foo.com" or "\*-bar.foo.com".
Note that the wildcard will not match the empty string. e.g. "\*-bar.foo.com" will match
"baz-bar.foo.com" but not "-bar.foo.com". Additionally, a special entry "\*" is allowed
which will match any host/authority header. Only a single virtual host in the entire route
configuration can match on "\*". A domain must be unique across all virtual hosts or the config
will fail to load.
:ref:`routes <config_http_conn_man_route_table_route>`
*(required, array)* The list of routes that will be matched, in order, for incoming requests.
The first route that matches will be used.
:ref:`cors <config_http_conn_man_route_table_cors>`
*(optional, object)* Specifies the virtual host's CORS policy.
.. _config_http_conn_man_route_table_vhost_require_ssl:
require_ssl
*(optional, string)* Specifies the type of TLS enforcement the virtual host expects. Possible
values are:
all
All requests must use TLS. If a request is not using TLS, a 302 redirect will be sent telling
the client to use HTTPS.
external_only
External requests must use TLS. If a request is external and it is not using TLS, a 302 redirect
will be sent telling the client to use HTTPS.
If this option is not specified, there is no TLS requirement for the virtual host.
:ref:`virtual_clusters <config_http_conn_man_route_table_vcluster>`
*(optional, array)* A list of virtual clusters defined for this virtual host. Virtual clusters
are used for additional statistics gathering.
:ref:`rate_limits <config_http_conn_man_route_table_rate_limit_config>`
*(optional, array)* Specifies a set of rate limit configurations that will be applied to the
virtual host.
.. _config_http_conn_man_route_table_vhost_add_req_headers:
request_headers_to_add
*(optional, array)* Specifies a list of HTTP headers that should be added to each
request handled by this virtual host. Headers are specified in the following form:
.. code-block:: json
[
{"key": "header1", "value": "value1"},
{"key": "header2", "value": "value2"}
]
For more information see the documentation on :ref:`custom request headers
<config_http_conn_man_headers_custom_request_headers>`.

34
docs/root/api-v1/runtime.rst
Unescape View File

@ -1,34 +0,0 @@
.. _config_runtime_v1:
Runtime
=======
Runtime :ref:`configuration overview <config_runtime>`.
.. code-block:: json
{
"symlink_root": "...",
"subdirectory": "...",
"override_subdirectory": "..."
}
symlink_root
*(required, string)* The implementation assumes that the file system tree is accessed via a
symbolic link. An atomic link swap is used when a new tree should be switched to. This
parameter specifies the path to the symbolic link. Envoy will watch the location for changes
and reload the file system tree when they happen.
subdirectory
*(required, string)* Specifies the subdirectory to load within the root directory. This is useful
if multiple systems share the same delivery mechanism. Envoy configuration elements can be
contained in a dedicated subdirectory.
.. _config_runtime_override_subdirectory:
override_subdirectory
*(optional, string)* Specifies an optional subdirectory to load within the root directory. If
specified and the directory exists, configuration values within this directory will override those
found in the primary subdirectory. This is useful when Envoy is deployed across many different
types of servers. Sometimes it is useful to have a per service cluster directory for runtime
configuration. See below for exactly how the override directory is used.

69
docs/root/api-v1/tracing.rst
Unescape View File

@ -1,69 +0,0 @@
.. _config_tracing_v1:
Tracing
=======
The :ref:`tracing <arch_overview_tracing>` configuration specifies global settings for the HTTP
tracer used by Envoy. The configuration is defined on the :ref:`server's top level configuration
<config_overview_v1>`. Envoy may support other tracers in the future, but right now the HTTP tracer is
the only one supported.
.. code-block:: json
{
"http": {
"driver": "{...}"
}
}
http
*(optional, object)* Provides configuration for the HTTP tracer.
driver
*(optional, object)* Provides the driver that handles trace and span creation.
Currently `LightStep <http://lightstep.com/>`_ and `Zipkin
<http://zipkin.io>`_ drivers are supported.
LightStep driver
----------------
.. code-block:: json
{
"type": "lightstep",
"config": {
"access_token_file": "...",
"collector_cluster": "..."
}
}
access_token_file
*(required, string)* File containing the access token to the `LightStep <http://lightstep.com/>`_
API.
collector_cluster
*(required, string)* The cluster manager cluster that hosts the LightStep collectors.
Zipkin driver
-------------
.. code-block:: json
{
"type": "zipkin",
"config": {
"collector_cluster": "...",
"collector_endpoint": "..."
}
}
collector_cluster
*(required, string)* The cluster manager cluster that hosts the Zipkin collectors. Note that the
Zipkin cluster must be defined under `clusters` in the cluster manager configuration section.
collector_endpoint
*(optional, string)* The API endpoint of the Zipkin service where the
spans will be sent. When using a standard Zipkin installation, the
API endpoint is typically `/api/v1/spans`, which is the default value.

16
docs/root/api-v2/api.rst
Unescape View File

@ -1,16 +0,0 @@
.. _envoy_api_reference:
v2 API reference
================
.. toctree::
:glob:
:maxdepth: 2
bootstrap/bootstrap
listeners/listeners
clusters/clusters
http_routes/http_routes
config/filter/filter
common_messages/common_messages
types/types

12
docs/root/api-v2/bootstrap/bootstrap.rst
Unescape View File

@ -1,12 +0,0 @@
Bootstrap
=========
.. toctree::
:glob:
:maxdepth: 2
../config/bootstrap/v2/bootstrap.proto
../config/metrics/v2/stats.proto
../config/metrics/v2/metrics_service.proto
../config/ratelimit/v2/rls.proto
../config/trace/v2/trace.proto

13
docs/root/api-v2/clusters/clusters.rst
Unescape View File

@ -1,13 +0,0 @@
Clusters
========
.. toctree::
:glob:
:maxdepth: 2
../api/v2/cds.proto
../api/v2/cluster/outlier_detection.proto
../api/v2/cluster/circuit_breaker.proto
../api/v2/endpoint/endpoint.proto
../api/v2/eds.proto
../api/v2/core/health_check.proto

15
docs/root/api-v2/common_messages/common_messages.rst
Unescape View File

@ -1,15 +0,0 @@
Common messages
===============
.. toctree::
:glob:
:maxdepth: 2
../api/v2/core/base.proto
../api/v2/core/address.proto
../api/v2/core/protocol.proto
../api/v2/discovery.proto
../api/v2/core/config_source.proto
../api/v2/core/grpc_service.proto
../api/v2/auth/cert.proto
../api/v2/ratelimit/ratelimit.proto

11
docs/root/api-v2/config/filter/filter.rst
Unescape View File

@ -1,11 +0,0 @@
Filters
=======
.. toctree::
:glob:
:maxdepth: 2
network/network
http/http
accesslog/v2/accesslog.proto
fault/v2/fault.proto

8
docs/root/api-v2/config/filter/http/http.rst
Unescape View File

@ -1,8 +0,0 @@
HTTP filters
============
.. toctree::
:glob:
:maxdepth: 2
*/v2/*

8
docs/root/api-v2/config/filter/network/network.rst
Unescape View File

@ -1,8 +0,0 @@
Network filters
===============
.. toctree::
:glob:
:maxdepth: 2
*/v2/*

9
docs/root/api-v2/http_routes/http_routes.rst
Unescape View File

@ -1,9 +0,0 @@
HTTP route management
=====================
.. toctree::
:glob:
:maxdepth: 2
../api/v2/rds.proto
../api/v2/route/route.proto

9
docs/root/api-v2/listeners/listeners.rst
Unescape View File

@ -1,9 +0,0 @@
Listeners
=========
.. toctree::
:glob:
:maxdepth: 2
../api/v2/lds.proto
../api/v2/listener/listener.proto

9
docs/root/api-v2/types/types.rst
Unescape View File

@ -1,9 +0,0 @@
Types
=====
.. toctree::
:glob:
:maxdepth: 2
../type/percent.proto
../type/range.proto

208
docs/root/configuration/access_log.rst
Unescape View File

@ -1,208 +0,0 @@
.. _config_access_log:
Access logging
==============
Configuration
-------------------------
Access logs are configured as part of the :ref:`HTTP connection manager config
<config_http_conn_man>` or :ref:`TCP Proxy <config_network_filters_tcp_proxy>`.
* :ref:`v1 API reference <config_access_log_v1>`
* :ref:`v2 API reference <envoy_api_msg_config.filter.accesslog.v2.AccessLog>`
.. _config_access_log_format:
Format rules
------------
The access log format string contains either command operators or other characters interpreted as a
plain string. The access log formatter does not make any assumptions about a new line separator, so one
has to specified as part of the format string.
See the :ref:`default format <config_access_log_default_format>` for an example.
Note that the access log line will contain a '-' character for every not set/empty value.
The same format strings are used by different types of access logs (such as HTTP and TCP). Some
fields may have slightly different meanings, depending on what type of log it is. Differences
are noted.
The following command operators are supported:
%START_TIME%
HTTP
Request start time including milliseconds.
TCP
Downstream connection start time including milliseconds.
START_TIME can be customized using a `format string <http://en.cppreference.com/w/cpp/io/manip/put_time>`_, for example:
.. code-block:: none
%START_TIME(%Y/%m/%dT%H:%M:%S%z %s)%
%BYTES_RECEIVED%
HTTP
Body bytes received.
TCP
Downstream bytes received on connection.
%PROTOCOL%
HTTP
Protocol. Currently either *HTTP/1.1* or *HTTP/2*.
TCP
Not implemented ("-").
%RESPONSE_CODE%
HTTP
HTTP response code. Note that a response code of '0' means that the server never sent the
beginning of a response. This generally means that the (downstream) client disconnected.
TCP
Not implemented ("-").
%BYTES_SENT%
HTTP
Body bytes sent.
TCP
Downstream bytes sent on connection.
%DURATION%
HTTP
Total duration in milliseconds of the request from the start time to the last byte out.
TCP
Total duration in milliseconds of the downstream connection.
%RESPONSE_FLAGS%
Additional details about the response or connection, if any. For TCP connections, the response codes mentioned in
the descriptions do not apply. Possible values are:
HTTP and TCP
* **UH**: No healthy upstream hosts in upstream cluster in addition to 503 response code.
* **UF**: Upstream connection failure in addition to 503 response code.
* **UO**: Upstream overflow (:ref:`circuit breaking <arch_overview_circuit_break>`) in addition to 503 response code.
* **NR**: No :ref:`route configured <arch_overview_http_routing>` for a given request in addition to 404 response code.
HTTP only
* **LH**: Local service failed :ref:`health check request <arch_overview_health_checking>` in addition to 503 response code.
* **UT**: Upstream request timeout in addition to 504 response code.
* **LR**: Connection local reset in addition to 503 response code.
* **UR**: Upstream remote reset in addition to 503 response code.
* **UC**: Upstream connection termination in addition to 503 response code.
* **DI**: The request processing was delayed for a period specified via :ref:`fault injection <config_http_filters_fault_injection>`.
* **FI**: The request was aborted with a response code specified via :ref:`fault injection <config_http_filters_fault_injection>`.
* **RL**: The request was ratelimited locally by the :ref:`HTTP rate limit filter <config_http_filters_rate_limit>` in addition to 429 response code.
%UPSTREAM_HOST%
Upstream host URL (e.g., tcp://ip:port for TCP connections).
%UPSTREAM_CLUSTER%
Upstream cluster to which the upstream host belongs to.
%UPSTREAM_LOCAL_ADDRESS%
Local address of the upstream connection. If the address is an IP address it includes both
address and port.
%DOWNSTREAM_ADDRESS%
Remote address of the downstream connection *without IP port if the address is an IP address*.
.. attention::
This field is deprecated. Use **DOWNSTREAM_REMOTE_ADDRESS** or
**DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT** instead.
%DOWNSTREAM_REMOTE_ADDRESS%
Remote address of the downstream connection. If the address is an IP address it includes both
address and port.
.. note::
This may not be the physical remote address of the peer if the address has been inferred from
:ref:`proxy proto <envoy_api_field_listener.FilterChain.use_proxy_proto>` or :ref:`x-forwarded-for
<config_http_conn_man_headers_x-forwarded-for>`.
%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%
Remote address of the downstream connection. If the address is an IP address the output does
*not* include port.
.. note::
This may not be the physical remote address of the peer if the address has been inferred from
:ref:`proxy proto <envoy_api_field_listener.FilterChain.use_proxy_proto>` or :ref:`x-forwarded-for
<config_http_conn_man_headers_x-forwarded-for>`.
%DOWNSTREAM_LOCAL_ADDRESS%
Local address of the downstream connection. If the address is an IP address it includes both
address and port.
If the original connection was redirected by iptables REDIRECT, this represents
the original destination address restored by the
:ref:`Original Destination Filter <config_listener_filters_original_dst>` using SO_ORIGINAL_DST socket option.
If the original connection was redirected by iptables TPROXY, and the listener's transparent
option was set to true, this represents the original destination address and port.
%DOWNSTREAM_LOCAL_ADDRESS_WITHOUT_PORT%
Same as **%DOWNSTREAM_LOCAL_ADDRESS%** excluding port if the address is an IP address.
%REQ(X?Y):Z%
HTTP
An HTTP request header where X is the main HTTP header, Y is the alternative one, and Z is an
optional parameter denoting string truncation up to Z characters long. The value is taken from
the HTTP request header named X first and if it's not set, then request header Y is used. If
none of the headers are present '-' symbol will be in the log.
TCP
Not implemented ("-").
%RESP(X?Y):Z%
HTTP
Same as **%REQ(X?Y):Z%** but taken from HTTP response headers.
TCP
Not implemented ("-").
%DYNAMIC_METADATA(NAMESPACE:KEY*):Z%
HTTP
:ref:`Dynamic Metadata <envoy_api_msg_core.Metadata>` info,
where NAMESPACE is the the filter namespace used when setting the metadata, KEY is an optional
lookup up key in the namespace with the option of specifying nested keys separated by ':',
and Z is an optional parameter denoting string truncation up to Z characters long. Dynamic Metadata
can be set by filters using the :repo:`RequestInfo <include/envoy/request_info/request_info.h>` API:
*setDynamicMetadata*. The data will be logged as a JSON string. For example, for the following dynamic metadata:
``com.test.my_filter: {"test_key": "foo", "test_object": {"inner_key": "bar"}}``
* %DYNAMIC_METADATA(com.test.my_filter)% will log: ``{"test_key": "foo", "test_object": {"inner_key": "bar"}}``
* %DYNAMIC_METADATA(com.test.my_filter:test_key)% will log: ``"foo"``
* %DYNAMIC_METADATA(com.test.my_filter:test_object)% will log: ``{"inner_key": "bar"}``
* %DYNAMIC_METADATA(com.test.my_filter:test_object:inner_key)% will log: ``"bar"``
* %DYNAMIC_METADATA(com.unknown_filter)% will log: ``-``
* %DYNAMIC_METADATA(com.test.my_filter:unknown_key)% will log: ``-``
* %DYNAMIC_METADATA(com.test.my_filter):25% will log (truncation at 25 characters): ``{"test_key": "foo", "test``
TCP
Not implemented ("-").
.. _config_access_log_default_format:
Default format
--------------
If custom format is not specified, Envoy uses the following default format:
.. code-block:: none
[%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%"
%RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION%
%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%"
"%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"\n
Example of the default Envoy access log format:
.. code-block:: none
[2016-04-15T20:17:00.310Z] "POST /api/v1/locations HTTP/2" 204 - 154 0 226 100 "10.0.35.28"
"nsq2http" "cc21d9b0-cf5c-432b-8c7e-98aeb7988cd2" "locations" "tcp://10.0.2.1:80"

31
docs/root/configuration/cluster_manager/cds.rst
Unescape View File

@ -1,31 +0,0 @@
.. _config_cluster_manager_cds:
Cluster discovery service
=========================
The cluster discovery service (CDS) is an optional API that Envoy will call to dynamically fetch
cluster manager members. Envoy will reconcile the API response and add, modify, or remove known
clusters depending on what is required.
.. note::
Any clusters that are statically defined within the Envoy configuration cannot be modified or
removed via the CDS API.
* :ref:`v1 CDS API <config_cluster_manager_cds_v1>`
* :ref:`v2 CDS API <v2_grpc_streaming_endpoints>`
Statistics
----------
CDS has a statistics tree rooted at *cluster_manager.cds.* with the following statistics:
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
config_reload, Counter, Total API fetches that resulted in a config reload due to a different config
update_attempt, Counter, Total API fetches attempted
update_success, Counter, Total API fetches completed successfully
update_failure, Counter, Total API fetches that failed (either network or schema errors)
version, Gauge, Hash of the contents from the last successful API fetch

17
docs/root/configuration/cluster_manager/cluster_circuit_breakers.rst
Unescape View File

@ -1,17 +0,0 @@
.. _config_cluster_manager_cluster_circuit_breakers:
Circuit breaking
================
* Circuit Breaking :ref:`architecture overview <arch_overview_circuit_break>`.
* :ref:`v1 API documentation <config_cluster_manager_cluster_circuit_breakers_v1>`.
* :ref:`v2 API documentation <envoy_api_msg_cluster.CircuitBreakers>`.
Runtime
-------
All circuit breaking settings are runtime configurable for all defined priorities based on cluster
name. They follow the following naming scheme ``circuit_breakers.<cluster_name>.<priority>.<setting>``.
``cluster_name`` is the name field in each cluster's configuration, which is set in the envoy
:ref:`config file <config_cluster_manager_cluster_name>`. Available runtime settings will override
settings set in the envoy config file.

73
docs/root/configuration/cluster_manager/cluster_hc.rst
Unescape View File

@ -1,73 +0,0 @@
.. _config_cluster_manager_cluster_hc:
Health checking
===============
* Health checking :ref:`architecture overview <arch_overview_health_checking>`.
* If health checking is configured for a cluster, additional statistics are emitted. They are
documented :ref:`here <config_cluster_manager_cluster_stats>`.
* :ref:`v1 API documentation <config_cluster_manager_cluster_hc_v1>`.
* :ref:`v2 API documentation <envoy_api_msg_core.HealthCheck>`.
.. _config_cluster_manager_cluster_hc_tcp_health_checking:
TCP health checking
-------------------
.. attention::
This section is written for the v1 API but the concepts also apply to the v2 API. It will be
rewritten to target the v2 API in a future release.
The type of matching performed is the following (this is the MongoDB health check request and
response):
.. code-block:: json
{
"send": [
{"binary": "39000000"},
{"binary": "EEEEEEEE"},
{"binary": "00000000"},
{"binary": "d4070000"},
{"binary": "00000000"},
{"binary": "746573742e"},
{"binary": "24636d6400"},
{"binary": "00000000"},
{"binary": "FFFFFFFF"},
{"binary": "13000000"},
{"binary": "01"},
{"binary": "70696e6700"},
{"binary": "000000000000f03f"},
{"binary": "00"}
],
"receive": [
{"binary": "EEEEEEEE"},
{"binary": "01000000"},
{"binary": "00000000"},
{"binary": "0000000000000000"},
{"binary": "00000000"},
{"binary": "11000000"},
{"binary": "01"},
{"binary": "6f6b"},
{"binary": "00000000000000f03f"},
{"binary": "00"}
]
}
During each health check cycle, all of the "send" bytes are sent to the target server. Each
binary block can be of arbitrary length and is just concatenated together when sent. (Separating
into multiple blocks can be useful for readability).
When checking the response, "fuzzy" matching is performed such that each binary block must be found,
and in the order specified, but not necessarily contiguous. Thus, in the example above,
"FFFFFFFF" could be inserted in the response between "EEEEEEEE" and "01000000" and the check
would still pass. This is done to support protocols that insert non-deterministic data, such as
time, into the response.
Health checks that require a more complex pattern such as send/receive/send/receive are not
currently possible.
If "receive" is an empty array, Envoy will perform "connect only" TCP health checking. During each
cycle, Envoy will attempt to connect to the upstream host, and consider it a success if the
connection succeeds. A new connection is created for each health check cycle.

17
docs/root/configuration/cluster_manager/cluster_manager.rst
Unescape View File

@ -1,17 +0,0 @@
.. _config_cluster_manager:
Cluster manager
===============
.. toctree::
:hidden:
cluster_stats
cluster_runtime
cds
cluster_hc
cluster_circuit_breakers
* Cluster manager :ref:`architecture overview <arch_overview_cluster_manager>`
* :ref:`v1 API reference <config_cluster_manager_v1>`
* :ref:`v2 API reference <envoy_api_msg_config.bootstrap.v2.ClusterManager>`

131
docs/root/configuration/cluster_manager/cluster_runtime.rst
Unescape View File

@ -1,131 +0,0 @@
.. _config_cluster_manager_cluster_runtime:
Runtime
=======
Upstream clusters support the following runtime settings:
Active health checking
----------------------
health_check.min_interval
Min value for the health checking :ref:`interval <config_cluster_manager_cluster_hc_interval>`.
Default value is 0. The health checking interval will be between *min_interval* and
*max_interval*.
health_check.max_interval
Max value for the health checking :ref:`interval <config_cluster_manager_cluster_hc_interval>`.
Default value is MAX_INT. The health checking interval will be between *min_interval* and
*max_interval*.
health_check.verify_cluster
What % of health check requests will be verified against the :ref:`expected upstream service
<config_cluster_manager_cluster_hc_service_name>` as the :ref:`health check filter
<arch_overview_health_checking_filter>` will write the remote service cluster into the response.
.. _config_cluster_manager_cluster_runtime_outlier_detection:
Outlier detection
-----------------
See the outlier detection :ref:`architecture overview <arch_overview_outlier_detection>` for more
information on outlier detection. The runtime parameters supported by outlier detection are the
same as the :ref:`static configuration parameters <config_cluster_manager_cluster_outlier_detection>`, namely:
outlier_detection.consecutive_5xx
:ref:`consecutive_5XX
<config_cluster_manager_cluster_outlier_detection_consecutive_5xx>`
setting in outlier detection
outlier_detection.consecutive_gateway_failure
:ref:`consecutive_gateway_failure
<config_cluster_manager_cluster_outlier_detection_consecutive_gateway_failure>`
setting in outlier detection
outlier_detection.interval_ms
:ref:`interval_ms
<config_cluster_manager_cluster_outlier_detection_interval_ms>`
setting in outlier detection
outlier_detection.base_ejection_time_ms
:ref:`base_ejection_time_ms
<config_cluster_manager_cluster_outlier_detection_base_ejection_time_ms>`
setting in outlier detection
outlier_detection.max_ejection_percent
:ref:`max_ejection_percent
<config_cluster_manager_cluster_outlier_detection_max_ejection_percent>`
setting in outlier detection
outlier_detection.enforcing_consecutive_5xx
:ref:`enforcing_consecutive_5xx
<config_cluster_manager_cluster_outlier_detection_enforcing_consecutive_5xx>`
setting in outlier detection
outlier_detection.enforcing_consecutive_gateway_failure
:ref:`enforcing_consecutive_gateway_failure
<config_cluster_manager_cluster_outlier_detection_enforcing_consecutive_gateway_failure>`
setting in outlier detection
outlier_detection.enforcing_success_rate
:ref:`enforcing_success_rate
<config_cluster_manager_cluster_outlier_detection_enforcing_success_rate>`
setting in outlier detection
outlier_detection.success_rate_minimum_hosts
:ref:`success_rate_minimum_hosts
<config_cluster_manager_cluster_outlier_detection_success_rate_minimum_hosts>`
setting in outlier detection
outlier_detection.success_rate_request_volume
:ref:`success_rate_request_volume
<config_cluster_manager_cluster_outlier_detection_success_rate_request_volume>`
setting in outlier detection
outlier_detection.success_rate_stdev_factor
:ref:`success_rate_stdev_factor
<config_cluster_manager_cluster_outlier_detection_success_rate_stdev_factor>`
setting in outlier detection
Core
----
upstream.healthy_panic_threshold
Sets the :ref:`panic threshold <arch_overview_load_balancing_panic_threshold>` percentage.
Defaults to 50%.
upstream.use_http2
Whether the cluster utilizes the *http2* :ref:`feature <config_cluster_manager_cluster_features>`
if configured. Set to 0 to disable HTTP/2 even if the feature is configured. Defaults to enabled.
upstream.weight_enabled
Binary switch to turn on or off weighted load balancing. If set to non 0, weighted load balancing
is enabled. Defaults to enabled.
.. _config_cluster_manager_cluster_runtime_zone_routing:
Zone aware load balancing
-------------------------
upstream.zone_routing.enabled
% of requests that will be routed to the same upstream zone. Defaults to 100% of requests.
upstream.zone_routing.min_cluster_size
Minimal size of the upstream cluster for which zone aware routing can be attempted. Default value
is 6. If the upstream cluster size is smaller than *min_cluster_size* zone aware routing will not
be performed.
Circuit breaking
----------------
circuit_breakers.<cluster_name>.<priority>.max_connections
:ref:`Max connections circuit breaker setting <config_cluster_manager_cluster_circuit_breakers_max_connections>`
circuit_breakers.<cluster_name>.<priority>.max_pending_requests
:ref:`Max pending requests circuit breaker setting <config_cluster_manager_cluster_circuit_breakers_max_pending_requests>`
circuit_breakers.<cluster_name>.<priority>.max_requests
:ref:`Max requests circuit breaker setting <config_cluster_manager_cluster_circuit_breakers_max_requests>`
circuit_breakers.<cluster_name>.<priority>.max_retries
:ref:`Max retries circuit breaker setting <config_cluster_manager_cluster_circuit_breakers_max_retries>`

218
docs/root/configuration/cluster_manager/cluster_stats.rst
Unescape View File

@ -1,218 +0,0 @@
.. _config_cluster_manager_cluster_stats:
Statistics
==========
.. contents::
:local:
General
-------
The cluster manager has a statistics tree rooted at *cluster_manager.* with the following
statistics. Any ``:`` character in the stats name is replaced with ``_``.
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
cluster_added, Counter, Total clusters added (either via static config or CDS)
cluster_modified, Counter, Total clusters modified (via CDS)
cluster_removed, Counter, Total clusters removed (via CDS)
active_clusters, Gauge, Number of currently active (warmed) clusters
warming_clusters, Gauge, Number of currently warming (not active) clusters
Every cluster has a statistics tree rooted at *cluster.<name>.* with the following statistics:
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
upstream_cx_total, Counter, Total connections
upstream_cx_active, Gauge, Total active connections
upstream_cx_http1_total, Counter, Total HTTP/1.1 connections
upstream_cx_http2_total, Counter, Total HTTP/2 connections
upstream_cx_connect_fail, Counter, Total connection failures
upstream_cx_connect_timeout, Counter, Total connection connect timeouts
upstream_cx_idle_timeout, Counter, Total connection idle timeouts
upstream_cx_connect_attempts_exceeded, Counter, Total consecutive connection failures exceeding configured connection attempts
upstream_cx_overflow, Counter, Total times that the cluster's connection circuit breaker overflowed
upstream_cx_connect_ms, Histogram, Connection establishment milliseconds
upstream_cx_length_ms, Histogram, Connection length milliseconds
upstream_cx_destroy, Counter, Total destroyed connections
upstream_cx_destroy_local, Counter, Total connections destroyed locally
upstream_cx_destroy_remote, Counter, Total connections destroyed remotely
upstream_cx_destroy_with_active_rq, Counter, Total connections destroyed with 1+ active request
upstream_cx_destroy_local_with_active_rq, Counter, Total connections destroyed locally with 1+ active request
upstream_cx_destroy_remote_with_active_rq, Counter, Total connections destroyed remotely with 1+ active request
upstream_cx_close_notify, Counter, Total connections closed via HTTP/1.1 connection close header or HTTP/2 GOAWAY
upstream_cx_rx_bytes_total, Counter, Total received connection bytes
upstream_cx_rx_bytes_buffered, Gauge, Received connection bytes currently buffered
upstream_cx_tx_bytes_total, Counter, Total sent connection bytes
upstream_cx_tx_bytes_buffered, Gauge, Send connection bytes currently buffered
upstream_cx_protocol_error, Counter, Total connection protocol errors
upstream_cx_max_requests, Counter, Total connections closed due to maximum requests
upstream_cx_none_healthy, Counter, Total times connection not established due to no healthy hosts
upstream_rq_total, Counter, Total requests
upstream_rq_active, Gauge, Total active requests
upstream_rq_pending_total, Counter, Total requests pending a connection pool connection
upstream_rq_pending_overflow, Counter, Total requests that overflowed connection pool circuit breaking and were failed
upstream_rq_pending_failure_eject, Counter, Total requests that were failed due to a connection pool connection failure
upstream_rq_pending_active, Gauge, Total active requests pending a connection pool connection
upstream_rq_cancelled, Counter, Total requests cancelled before obtaining a connection pool connection
upstream_rq_maintenance_mode, Counter, Total requests that resulted in an immediate 503 due to :ref:`maintenance mode<config_http_filters_router_runtime_maintenance_mode>`
upstream_rq_timeout, Counter, Total requests that timed out waiting for a response
upstream_rq_per_try_timeout, Counter, Total requests that hit the per try timeout
upstream_rq_rx_reset, Counter, Total requests that were reset remotely
upstream_rq_tx_reset, Counter, Total requests that were reset locally
upstream_rq_retry, Counter, Total request retries
upstream_rq_retry_success, Counter, Total request retry successes
upstream_rq_retry_overflow, Counter, Total requests not retried due to circuit breaking
upstream_flow_control_paused_reading_total, Counter, Total number of times flow control paused reading from upstream
upstream_flow_control_resumed_reading_total, Counter, Total number of times flow control resumed reading from upstream
upstream_flow_control_backed_up_total, Counter, Total number of times the upstream connection backed up and paused reads from downstream
upstream_flow_control_drained_total, Counter, Total number of times the upstream connection drained and resumed reads from downstream
membership_change, Counter, Total cluster membership changes
membership_healthy, Gauge, Current cluster healthy total (inclusive of both health checking and outlier detection)
membership_total, Gauge, Current cluster membership total
retry_or_shadow_abandoned, Counter, Total number of times shadowing or retry buffering was canceled due to buffer limits
config_reload, Counter, Total API fetches that resulted in a config reload due to a different config
update_attempt, Counter, Total cluster membership update attempts
update_success, Counter, Total cluster membership update successes
update_failure, Counter, Total cluster membership update failures
update_empty, Counter, Total cluster membership updates ending with empty cluster load assignment and continuing with previous config
version, Gauge, Hash of the contents from the last successful API fetch
max_host_weight, Gauge, Maximum weight of any host in the cluster
bind_errors, Counter, Total errors binding the socket to the configured source address
Health check statistics
-----------------------
If health check is configured, the cluster has an additional statistics tree rooted at
*cluster.<name>.health_check.* with the following statistics:
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
attempt, Counter, Number of health checks
success, Counter, Number of successful health checks
failure, Counter, Number of immediately failed health checks (e.g. HTTP 503) as well as network failures
passive_failure, Counter, Number of health check failures due to passive events (e.g. x-envoy-immediate-health-check-fail)
network_failure, Counter, Number of health check failures due to network error
verify_cluster, Counter, Number of health checks that attempted cluster name verification
healthy, Gauge, Number of healthy members
.. _config_cluster_manager_cluster_stats_outlier_detection:
Outlier detection statistics
----------------------------
If :ref:`outlier detection <arch_overview_outlier_detection>` is configured for a cluster,
statistics will be rooted at *cluster.<name>.outlier_detection.* and contain the following:
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
ejections_enforced_total, Counter, Number of enforced ejections due to any outlier type
ejections_active, Gauge, Number of currently ejected hosts
ejections_overflow, Counter, Number of ejections aborted due to the max ejection %
ejections_enforced_consecutive_5xx, Counter, Number of enforced consecutive 5xx ejections
ejections_detected_consecutive_5xx, Counter, Number of detected consecutive 5xx ejections (even if unenforced)
ejections_enforced_success_rate, Counter, Number of enforced success rate outlier ejections
ejections_detected_success_rate, Counter, Number of detected success rate outlier ejections (even if unenforced)
ejections_enforced_consecutive_gateway_failure, Counter, Number of enforced consecutive gateway failure ejections
ejections_detected_consecutive_gateway_failure, Counter, Number of detected consecutive gateway failure ejections (even if unenforced)
ejections_total, Counter, Deprecated. Number of ejections due to any outlier type (even if unenforced)
ejections_consecutive_5xx, Counter, Deprecated. Number of consecutive 5xx ejections (even if unenforced)
.. _config_cluster_manager_cluster_stats_dynamic_http:
Dynamic HTTP statistics
-----------------------
If HTTP is used, dynamic HTTP response code statistics are also available. These are emitted by
various internal systems as well as some filters such as the :ref:`router filter
<config_http_filters_router>` and :ref:`rate limit filter <config_http_filters_rate_limit>`. They
are rooted at *cluster.<name>.* and contain the following statistics:
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
upstream_rq_<\*xx>, Counter, "Aggregate HTTP response codes (e.g., 2xx, 3xx, etc.)"
upstream_rq_<\*>, Counter, "Specific HTTP response codes (e.g., 201, 302, etc.)"
upstream_rq_time, Histogram, Request time milliseconds
canary.upstream_rq_<\*xx>, Counter, Upstream canary aggregate HTTP response codes
canary.upstream_rq_<\*>, Counter, Upstream canary specific HTTP response codes
canary.upstream_rq_time, Histogram, Upstream canary request time milliseconds
internal.upstream_rq_<\*xx>, Counter, Internal origin aggregate HTTP response codes
internal.upstream_rq_<\*>, Counter, Internal origin specific HTTP response codes
internal.upstream_rq_time, Histogram, Internal origin request time milliseconds
external.upstream_rq_<\*xx>, Counter, External origin aggregate HTTP response codes
external.upstream_rq_<\*>, Counter, External origin specific HTTP response codes
external.upstream_rq_time, Histogram, External origin request time milliseconds
.. _config_cluster_manager_cluster_stats_alt_tree:
Alternate tree dynamic HTTP statistics
--------------------------------------
If alternate tree statistics are configured, they will be present in the
*cluster.<name>.<alt name>.* namespace. The statistics produced are the same as documented in
the dynamic HTTP statistics section :ref:`above
<config_cluster_manager_cluster_stats_dynamic_http>`.
.. _config_cluster_manager_cluster_per_az_stats:
Per service zone dynamic HTTP statistics
----------------------------------------
If the service zone is available for the local service (via :option:`--service-zone`)
and the :ref:`upstream cluster <arch_overview_service_discovery_types_sds>`,
Envoy will track the following statistics in *cluster.<name>.zone.<from_zone>.<to_zone>.* namespace.
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
upstream_rq_<\*xx>, Counter, "Aggregate HTTP response codes (e.g., 2xx, 3xx, etc.)"
upstream_rq_<\*>, Counter, "Specific HTTP response codes (e.g., 201, 302, etc.)"
upstream_rq_time, Histogram, Request time milliseconds
Load balancer statistics
------------------------
Statistics for monitoring load balancer decisions. Stats are rooted at *cluster.<name>.* and contain
the following statistics:
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
lb_recalculate_zone_structures, Counter, The number of times locality aware routing structures are regenerated for fast decisions on upstream locality selection
lb_healthy_panic, Counter, Total requests load balanced with the load balancer in panic mode
lb_zone_cluster_too_small, Counter, No zone aware routing because of small upstream cluster size
lb_zone_routing_all_directly, Counter, Sending all requests directly to the same zone
lb_zone_routing_sampled, Counter, Sending some requests to the same zone
lb_zone_routing_cross_zone, Counter, Zone aware routing mode but have to send cross zone
lb_local_cluster_not_ok, Counter, Local host set is not set or it is panic mode for local cluster
lb_zone_number_differs, Counter, Number of zones in local and upstream cluster different
lb_zone_no_capacity_left, Counter, Total number of times ended with random zone selection due to rounding error
Load balancer subset statistics
-------------------------------
Statistics for monitoring `load balancer subset <arch_overview_load_balancer_subsets>`
decisions. Stats are rooted at *cluster.<name>.* and contain the following statistics:
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
lb_subsets_active, Gauge, Number of currently available subsets
lb_subsets_created, Counter, Number of subsets created
lb_subsets_removed, Counter, Number of subsets removed due to no hosts
lb_subsets_selected, Counter, Number of times any subset was selected for load balancing
lb_subsets_fallback, Counter, Number of times the fallback policy was invoked

22
docs/root/configuration/configuration.rst
Unescape View File

@ -1,22 +0,0 @@
.. _config:
Configuration reference
=======================
.. toctree::
:maxdepth: 2
:includehidden:
overview/v1_overview
overview/v2_overview
listeners/listeners
listener_filters/listener_filters
network_filters/network_filters
http_conn_man/http_conn_man
http_filters/http_filters
cluster_manager/cluster_manager
access_log
rate_limit
runtime
statistics
tools/router_check

35
docs/root/configuration/http_conn_man/header_sanitizing.rst
Unescape View File

@ -1,35 +0,0 @@
.. _config_http_conn_man_header_sanitizing:
HTTP header sanitizing
======================
For security reasons, Envoy will "sanitize" various incoming HTTP headers depending on whether the
request is an internal or external request. The sanitizing action depends on the header and may
result in addition, removal, or modification. Ultimately, whether the request is considered internal
or external is governed by the :ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>`
header (please read the linked section carefully as how Envoy populates the header is complex and
depends on the :ref:`use_remote_address <config_http_conn_man_use_remote_address>` setting).
Envoy will potentially sanitize the following headers:
* :ref:`x-envoy-decorator-operation <config_http_filters_router_x-envoy-decorator-operation>`
* :ref:`x-envoy-downstream-service-cluster
<config_http_conn_man_headers_downstream-service-cluster>`
* :ref:`x-envoy-downstream-service-node <config_http_conn_man_headers_downstream-service-node>`
* :ref:`x-envoy-expected-rq-timeout-ms <config_http_filters_router_x-envoy-expected-rq-timeout-ms>`
* :ref:`x-envoy-external-address <config_http_conn_man_headers_x-envoy-external-address>`
* :ref:`x-envoy-force-trace <config_http_conn_man_headers_x-envoy-force-trace>`
* :ref:`x-envoy-internal <config_http_conn_man_headers_x-envoy-internal>`
* :ref:`x-envoy-max-retries <config_http_filters_router_x-envoy-max-retries>`
* :ref:`x-envoy-retry-grpc-on <config_http_filters_router_x-envoy-retry-grpc-on>`
* :ref:`x-envoy-retry-on <config_http_filters_router_x-envoy-retry-on>`
* :ref:`x-envoy-upstream-alt-stat-name <config_http_filters_router_x-envoy-upstream-alt-stat-name>`
* :ref:`x-envoy-upstream-rq-per-try-timeout-ms
<config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms>`
* :ref:`x-envoy-upstream-rq-timeout-alt-response
<config_http_filters_router_x-envoy-upstream-rq-timeout-alt-response>`
* :ref:`x-envoy-upstream-rq-timeout-ms <config_http_filters_router_x-envoy-upstream-rq-timeout-ms>`
* :ref:`x-forwarded-client-cert <config_http_conn_man_headers_x-forwarded-client-cert>`
* :ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>`
* :ref:`x-forwarded-proto <config_http_conn_man_headers_x-forwarded-proto>`
* :ref:`x-request-id <config_http_conn_man_headers_x-request-id>`

482
docs/root/configuration/http_conn_man/headers.rst
Unescape View File

@ -1,482 +0,0 @@
.. _config_http_conn_man_headers:
HTTP header manipulation
========================
The HTTP connection manager manipulates several HTTP headers both during decoding (when the request
is being received) as well as during encoding (when the response is being sent).
.. contents::
:local:
.. _config_http_conn_man_headers_user-agent:
user-agent
----------
The *user-agent* header may be set by the connection manager during decoding if the
:ref:`add_user_agent <config_http_conn_man_add_user_agent>` option is enabled. The header is only
modified if it is not already set. If the connection manager does set the header, the value is
determined by the :option:`--service-cluster` command line option.
.. _config_http_conn_man_headers_server:
server
------
The *server* header will be set during encoding to the value in the :ref:`server_name
<config_http_conn_man_server_name>` option.
.. _config_http_conn_man_headers_x-client-trace-id:
x-client-trace-id
-----------------
If an external client sets this header, Envoy will join the provided trace ID with the internally
generated :ref:`config_http_conn_man_headers_x-request-id`. x-client-trace-id needs to be globally
unique and generating a uuid4 is recommended. If this header is set, it has similar effect to
:ref:`config_http_conn_man_headers_x-envoy-force-trace`. See the :ref:`tracing.client_enabled
<config_http_conn_man_runtime_client_enabled>` runtime configuration setting.
.. _config_http_conn_man_headers_downstream-service-cluster:
x-envoy-downstream-service-cluster
----------------------------------
Internal services often want to know which service is calling them. This header is cleaned from
external requests, but for internal requests will contain the service cluster of the caller. Note
that in the current implementation, this should be considered a hint as it is set by the caller and
could be easily spoofed by any internal entity. In the future Envoy will support a mutual
authentication TLS mesh which will make this header fully secure. Like *user-agent*, the value
is determined by the :option:`--service-cluster` command line option. In order to enable this
feature you need to set the :ref:`user_agent <config_http_conn_man_add_user_agent>` option to true.
.. _config_http_conn_man_headers_downstream-service-node:
x-envoy-downstream-service-node
-------------------------------
Internal services may want to know the downstream node request comes from. This header
is quite similar to :ref:`config_http_conn_man_headers_downstream-service-cluster`, except the value is taken from
the :option:`--service-node` option.
.. _config_http_conn_man_headers_x-envoy-external-address:
x-envoy-external-address
------------------------
It is a common case where a service wants to perform analytics based on the origin client's IP
address. Per the lengthy discussion on :ref:`XFF <config_http_conn_man_headers_x-forwarded-for>`,
this can get quite complicated, so Envoy simplifies this by setting *x-envoy-external-address*
to the :ref:`trusted client address <config_http_conn_man_headers_x-forwarded-for_trusted_client_address>`
if the request is from an external client. *x-envoy-external-address* is not set or overwritten
for internal requests. This header can be safely forwarded between internal services for analytics
purposes without having to deal with the complexities of XFF.
.. _config_http_conn_man_headers_x-envoy-force-trace:
x-envoy-force-trace
-------------------
If an internal request sets this header, Envoy will modify the generated
:ref:`config_http_conn_man_headers_x-request-id` such that it forces traces to be collected.
This also forces :ref:`config_http_conn_man_headers_x-request-id` to be returned in the response
headers. If this request ID is then propagated to other hosts, traces will also be collected on
those hosts which will provide a consistent trace for an entire request flow. See the
:ref:`tracing.global_enabled <config_http_conn_man_runtime_global_enabled>` and
:ref:`tracing.random_sampling <config_http_conn_man_runtime_random_sampling>` runtime
configuration settings.
.. _config_http_conn_man_headers_x-envoy-internal:
x-envoy-internal
----------------
It is a common case where a service wants to know whether a request is internal origin or not. Envoy
uses :ref:`XFF <config_http_conn_man_headers_x-forwarded-for>` to determine this and then will set
the header value to *true*.
This is a convenience to avoid having to parse and understand XFF.
.. _config_http_conn_man_headers_x-forwarded-client-cert:
x-forwarded-client-cert
-----------------------
*x-forwarded-client-cert* (XFCC) is a proxy header which indicates certificate information of part
or all of the clients or proxies that a request has flowed through, on its way from the client to the
server. A proxy may choose to sanitize/append/forward the XFCC header before proxying the request.
The XFCC header value is a comma (",") separated string. Each substring is an XFCC element, which
holds information added by a single proxy. A proxy can append the current client certificate
information as an XFCC element, to the end of the request's XFCC header after a comma.
Each XFCC element is a semicolon ";" separated string. Each substring is a key-value pair, grouped
together by an equals ("=") sign. The keys are case-insensitive, the values are case-sensitive. If
",", ";" or "=" appear in a value, the value should be double-quoted. Double-quotes in the value
should be replaced by backslash-double-quote (\").
The following keys are supported:
1. ``By`` The Subject Alternative Name (URI type) of the current proxy's certificate.
2. ``Hash`` The SHA 256 diguest of the current client certificate.
3. ``Cert`` The entire client certificate in URL encoded PEM format.
4. ``Subject`` The Subject field of the current client certificate. The value is always double-quoted.
5. ``URI`` The URI type Subject Alternative Name field of the current client certificate.
6. ``DNS`` The DNS type Subject Alternative Name field of the current client certificate. A client certificate may contain multiple DNS type Subject Alternative Names, each will be a separate key-value pair.
A client certificate may contain multiple Subject Alternative Name types. For details on different Subject Alternative Name types, please refer `RFC 2459`_.
.. _RFC 2459: https://tools.ietf.org/html/rfc2459#section-4.2.1.7
Some examples of the XFCC header are:
1. For one client certificate with only URI type Subject Alternative Name: ``x-forwarded-client-cert: By=http://frontend.lyft.com;Hash=468ed33be74eee6556d90c0149c1309e9ba61d6425303443c0748a02dd8de688;Subject="/C=US/ST=CA/L=San Francisco/OU=Lyft/CN=Test Client";URI=http://testclient.lyft.com``
2. For two client certificates with only URI type Subject Alternative Name: ``x-forwarded-client-cert: By=http://frontend.lyft.com;Hash=468ed33be74eee6556d90c0149c1309e9ba61d6425303443c0748a02dd8de688;URI=http://testclient.lyft.com,By=http://backend.lyft.com;Hash=9ba61d6425303443c0748a02dd8de688468ed33be74eee6556d90c0149c1309e;URI=http://frontend.lyft.com``
3. For one client certificate with both URI type and DNS type Subject Alternative Name: ``x-forwarded-client-cert: By=http://frontend.lyft.com;Hash=468ed33be74eee6556d90c0149c1309e9ba61d6425303443c0748a02dd8de688;Subject="/C=US/ST=CA/L=San Francisco/OU=Lyft/CN=Test Client";URI=http://testclient.lyft.com;DNS=lyft.com;DNS=www.lyft.com``
How Envoy processes XFCC is specified by the
:ref:`forward_client_cert<config_http_conn_man_forward_client_cert>` and the
:ref:`set_current_client_cert_details<config_http_conn_man_set_current_client_cert_details>` HTTP
connection manager options. If *forward_client_cert* is unset, the XFCC header will be sanitized by
default.
.. _config_http_conn_man_headers_x-forwarded-for:
x-forwarded-for
---------------
*x-forwarded-for* (XFF) is a standard proxy header which indicates the IP addresses that a request has
flowed through on its way from the client to the server. A compliant proxy will *append* the IP
address of the nearest client to the XFF list before proxying the request. Some examples of XFF are:
1. ``x-forwarded-for: 50.0.0.1`` (single client)
2. ``x-forwarded-for: 50.0.0.1, 40.0.0.1`` (external proxy hop)
3. ``x-forwarded-for: 50.0.0.1, 10.0.0.1`` (internal proxy hop)
Envoy will only append to XFF if the :ref:`use_remote_address
<config_http_conn_man_use_remote_address>` HTTP connection manager option is set to true.
This means that if *use_remote_address* is false (which is the default), the connection manager
operates in a transparent mode where it does not modify XFF.
.. attention::
In general, *use_remote_address* should be set to true when Envoy is deployed as an edge
node (aka a front proxy), whereas it may need to be set to false when Envoy is used as
an internal service node in a mesh deployment.
.. _config_http_conn_man_headers_x-forwarded-for_trusted_client_address:
The value of *use_remote_address* controls how Envoy determines the *trusted client address*.
Given an HTTP request that has traveled through a series of zero or more proxies to reach
Envoy, the trusted client address is the earliest source IP address that is known to be
accurate. The source IP address of the immediate downstream node's connection to Envoy is
trusted. XFF *sometimes* can be trusted. Malicious clients can forge XFF, but the last
address in XFF can be trusted if it was put there by a trusted proxy.
Envoy's default rules for determining the trusted client address (*before* appending anything
to XFF) are:
* If *use_remote_address* is false and an XFF containing at least one IP address is
present in the request, the trusted client address is the *last* (rightmost) IP address in XFF.
* Otherwise, the trusted client address is the source IP address of the immediate downstream
node's connection to Envoy.
In an environment where there are one or more trusted proxies in front of an edge
Envoy instance, the *xff_num_trusted_hops* configuration option can be used to trust
additional addresses from XFF:
* If *use_remote_address* is false and *xff_num_trusted_hops* is set to a value *N* that is
greater than zero, the trusted client address is the (N+1)th address from the right end
of XFF. (If the XFF contains fewer than N+1 addresses, Envoy falls back to using the
immediate downstream connection's source address as trusted client address.)
* If *use_remote_address* is true and *xff_num_trusted_hops* is set to a value *N* that is
greater than zero, the trusted client address is the Nth address from the right end
of XFF. (If the XFF contains fewer than N addresses, Envoy falls back to using the
immediate downstream connection's source address as trusted client address.)
Envoy uses the trusted client address contents to determine whether a request originated
externally or internally. This influences whether the
:ref:`config_http_conn_man_headers_x-envoy-internal` header is set.
Example 1: Envoy as edge proxy, without a trusted proxy in front of it
Settings:
| use_remote_address = true
| xff_num_trusted_hops = 0
Request details:
| Downstream IP address = 192.0.2.5
| XFF = "203.0.113.128, 203.0.113.10, 203.0.113.1"
Result:
| Trusted client address = 192.0.2.5 (XFF is ignored)
| X-Envoy-External-Address is set to 192.0.2.5
| XFF is changed to "203.0.113.128, 203.0.113.10, 203.0.113.1, 192.0.2.5"
| X-Envoy-Internal is removed (if it was present in the incoming request)
Example 2: Envoy as internal proxy, with the Envoy edge proxy from Example 1 in front of it
Settings:
| use_remote_address = false
| xff_num_trusted_hops = 0
Request details:
| Downstream IP address = 10.11.12.13 (address of the Envoy edge proxy)
| XFF = "203.0.113.128, 203.0.113.10, 203.0.113.1, 192.0.2.5"
Result:
| Trusted client address = 192.0.2.5 (last address in XFF is trusted)
| X-Envoy-External-Address is not modified
| X-Envoy-Internal is removed (if it was present in the incoming request)
Example 3: Envoy as edge proxy, with two trusted external proxies in front of it
Settings:
| use_remote_address = true
| xff_num_trusted_hops = 2
Request details:
| Downstream IP address = 192.0.2.5
| XFF = "203.0.113.128, 203.0.113.10, 203.0.113.1"
Result:
| Trusted client address = 203.0.113.10 (2nd to last address in XFF is trusted)
| X-Envoy-External-Address is set to 203.0.113.10
| XFF is changed to "203.0.113.128, 203.0.113.10, 203.0.113.1, 192.0.2.5"
| X-Envoy-Internal is removed (if it was present in the incoming request)
Example 4: Envoy as internal proxy, with the edge proxy from Example 3 in front of it
Settings:
| use_remote_address = false
| xff_num_trusted_hops = 2
Request details:
| Downstream IP address = 10.11.12.13 (address of the Envoy edge proxy)
| XFF = "203.0.113.128, 203.0.113.10, 203.0.113.1, 192.0.2.5"
Result:
| Trusted client address = 203.0.113.10
| X-Envoy-External-Address is not modified
| X-Envoy-Internal is removed (if it was present in the incoming request)
Example 5: Envoy as an internal proxy, receiving a request from an internal client
Settings:
| use_remote_address = false
| xff_num_trusted_hops = 0
Request details:
| Downstream IP address = 10.20.30.40 (address of the internal client)
| XFF is not present
Result:
| Trusted client address = 10.20.30.40
| X-Envoy-External-Address remains unset
| X-Envoy-Internal is set to "true"
Example 6: The internal Envoy from Example 5, receiving a request proxied by another Envoy
Settings:
| use_remote_address = false
| xff_num_trusted_hops = 0
Request details:
| Downstream IP address = 10.20.30.50 (address of the Envoy instance proxying to this one)
| XFF = "10.20.30.40"
Result:
| Trusted client address = 10.20.30.40
| X-Envoy-External-Address remains unset
| X-Envoy-Internal is set to "true"
A few very important notes about XFF:
1. If *use_remote_address* is set to true, Envoy sets the
:ref:`config_http_conn_man_headers_x-envoy-external-address` header to the trusted
client address.
.. _config_http_conn_man_headers_x-forwarded-for_internal_origin:
2. XFF is what Envoy uses to determine whether a request is internal origin or external origin.
If *use_remote_address* is set to true, the request is internal if and only if the
request contains no XFF and the immediate downstream node's connection to Envoy has
an internal (RFC1918 or RFC4193) source address. If *use_remote_address* is false, the
request is internal if and only if XFF contains a single RFC1918 or RFC4193 address.
* **NOTE**: If an internal service proxies an external request to another internal service, and
includes the original XFF header, Envoy will append to it on egress if
:ref:`use_remote_address <config_http_conn_man_use_remote_address>` is set. This will cause
the other side to think the request is external. Generally, this is what is intended if XFF is
being forwarded. If it is not intended, do not forward XFF, and forward
:ref:`config_http_conn_man_headers_x-envoy-internal` instead.
* **NOTE**: If an internal service call is forwarded to another internal service (preserving XFF),
Envoy will not consider it internal. This is a known "bug" due to the simplification of how
XFF is parsed to determine if a request is internal. In this scenario, do not forward XFF and
allow Envoy to generate a new one with a single internal origin IP.
3. Testing IPv6 in a large multi-hop system can be difficult from a change management perspective.
For testing IPv6 compatibility of upstream services which parse XFF header values,
:ref:`represent_ipv4_remote_address_as_ipv4_mapped_ipv6 <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.represent_ipv4_remote_address_as_ipv4_mapped_ipv6>`
can be enabled in the v2 API. Envoy will append an IPv4 address in mapped IPv6 format, e.g.
::FFFF:50.0.0.1. This change will also apply to
:ref:`config_http_conn_man_headers_x-envoy-external-address`.
.. _config_http_conn_man_headers_x-forwarded-proto:
x-forwarded-proto
-----------------
It is a common case where a service wants to know what the originating protocol (HTTP or HTTPS) was
of the connection terminated by front/edge Envoy. *x-forwarded-proto* contains this information. It
will be set to either *http* or *https*.
.. _config_http_conn_man_headers_x-request-id:
x-request-id
------------
The *x-request-id* header is used by Envoy to uniquely identify a request as well as perform stable
access logging and tracing. Envoy will generate an *x-request-id* header for all external origin
requests (the header is sanitized). It will also generate an *x-request-id* header for internal
requests that do not already have one. This means that *x-request-id* can and should be propagated
between client applications in order to have stable IDs across the entire mesh. Due to the out of
process architecture of Envoy, the header can not be automatically forwarded by Envoy itself. This
is one of the few areas where a thin client library is needed to perform this duty. How that is done
is out of scope for this documentation. If *x-request-id* is propagated across all hosts, the
following features are available:
* Stable :ref:`access logging <config_access_log>` via the
:ref:`v1 API runtime filter<config_http_con_manager_access_log_filters_runtime_v1>` or the
:ref:`v2 API runtime filter<envoy_api_field_config.filter.accesslog.v2.AccessLogFilter.runtime_filter>`.
* Stable tracing when performing random sampling via the :ref:`tracing.random_sampling
<config_http_conn_man_runtime_random_sampling>` runtime setting or via forced tracing using the
:ref:`config_http_conn_man_headers_x-envoy-force-trace` and
:ref:`config_http_conn_man_headers_x-client-trace-id` headers.
.. _config_http_conn_man_headers_x-ot-span-context:
x-ot-span-context
-----------------
The *x-ot-span-context* HTTP header is used by Envoy to establish proper parent-child relationships
between tracing spans when used with the LightStep tracer.
For example, an egress span is a child of an ingress
span (if the ingress span was present). Envoy injects the *x-ot-span-context* header on ingress requests and
forwards it to the local service. Envoy relies on the application to propagate *x-ot-span-context* on
the egress call to an upstream. See more on tracing :ref:`here <arch_overview_tracing>`.
.. _config_http_conn_man_headers_x-b3-traceid:
x-b3-traceid
------------
The *x-b3-traceid* HTTP header is used by the Zipkin tracer in Envoy.
The TraceId is 64-bit in length and indicates the overall ID of the
trace. Every span in a trace shares this ID. See more on zipkin tracing
`here <https://github.com/openzipkin/b3-propagation>`.
.. _config_http_conn_man_headers_x-b3-spanid:
x-b3-spanid
-----------
The *x-b3-spanid* HTTP header is used by the Zipkin tracer in Envoy.
The SpanId is 64-bit in length and indicates the position of the current
operation in the trace tree. The value should not be interpreted: it may or
may not be derived from the value of the TraceId. See more on zipkin tracing
`here <https://github.com/openzipkin/b3-propagation>`.
.. _config_http_conn_man_headers_x-b3-parentspanid:
x-b3-parentspanid
-----------------
The *x-b3-parentspanid* HTTP header is used by the Zipkin tracer in Envoy.
The ParentSpanId is 64-bit in length and indicates the position of the
parent operation in the trace tree. When the span is the root of the trace
tree, the ParentSpanId is absent. See more on zipkin tracing
`here <https://github.com/openzipkin/b3-propagation>`.
.. _config_http_conn_man_headers_x-b3-sampled:
x-b3-sampled
------------
The *x-b3-sampled* HTTP header is used by the Zipkin tracer in Envoy.
When the Sampled flag is either not specified or set to 1, the span will be reported to the tracing
system. Once Sampled is set to 0 or 1, the same
value should be consistently sent downstream. See more on zipkin tracing
`here <https://github.com/openzipkin/b3-propagation>`.
.. _config_http_conn_man_headers_x-b3-flags:
x-b3-flags
----------
The *x-b3-flags* HTTP header is used by the Zipkin tracer in Envoy.
The encode one or more options. For example, Debug is encoded as
``X-B3-Flags: 1``. See more on zipkin tracing
`here <https://github.com/openzipkin/b3-propagation>`.
.. _config_http_conn_man_headers_custom_request_headers:
Custom request/response headers
-------------------------------
Custom request/response headers can be added to a request/response at the weighted cluster,
route, virtual host, and/or global route configuration level. See the relevant :ref:`v1
<config_http_conn_man_route_table>` and :ref:`v2 <envoy_api_msg_RouteConfiguration>` API
documentation.
Headers are appended to requests/responses in the following order: weighted cluster level headers,
route level headers, virtual host level headers and finally global level headers.
Envoy supports adding dynamic values to request and response headers. The percent symbol (%) is
used to delimit variable names.
.. attention::
If a literal percent symbol (%) is desired in a request/response header, it must be escaped by
doubling it. For example, to emit a header with the value ``100%``, the custom header value in
the Envoy configuration must be ``100%%``.
Supported variable names are:
%CLIENT_IP%
The original client IP which is already added by Envoy as a
:ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>` request header.
.. attention::
This field is deprecated. Use **DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT** instead.
%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%
Remote address of the downstream connection. If the address is an IP address the output does
*not* include port.
.. note::
This may not be the physical remote address of the peer if the address has been inferred from
:ref:`proxy proto <envoy_api_field_listener.FilterChain.use_proxy_proto>` or :ref:`x-forwarded-for
<config_http_conn_man_headers_x-forwarded-for>`.
%DOWNSTREAM_LOCAL_ADDRESS%
Local address of the downstream connection. If the address is an IP address it includes both
address and port.
If the original connection was redirected by iptables REDIRECT, this represents
the original destination address restored by the
:ref:`Original Destination Filter <config_listener_filters_original_dst>` using SO_ORIGINAL_DST socket option.
If the original connection was redirected by iptables TPROXY, and the listener's transparent
option was set to true, this represents the original destination address and port.
%DOWNSTREAM_LOCAL_ADDRESS_WITHOUT_PORT%
Same as **%DOWNSTREAM_LOCAL_ADDRESS%** excluding port if the address is an IP address.
%PROTOCOL%
The original protocol which is already added by Envoy as a
:ref:`x-forwarded-proto <config_http_conn_man_headers_x-forwarded-proto>` request header.
%UPSTREAM_METADATA(["namespace", "key", ...])%
Populates the header with :ref:`EDS endpoint metadata <envoy_api_field_endpoint.LbEndpoint.metadata>` from the
upstream host selected by the router. Metadata may be selected from any namespace. In general,
metadata values may be strings, numbers, booleans, lists, nested structures, or null. Upstream
metadata values may be selected from nested structs by specifying multiple keys. Otherwise,
only string, boolean, and numeric values are supported. If the namespace or key(s) are not
found, or if the selected value is not a supported type, then no header is emitted. The
namespace and key(s) are specified as a JSON array of strings. Finally, percent symbols in the
parameters **do not** need to be escaped by doubling them.

20
docs/root/configuration/http_conn_man/http_conn_man.rst
Unescape View File

@ -1,20 +0,0 @@
.. _config_http_conn_man:
HTTP connection manager
=======================
* HTTP connection manager :ref:`architecture overview <arch_overview_http_conn_man>`
* HTTP protocols :ref:`architecture overview <arch_overview_http_protocols>`
* :ref:`v1 API reference <config_network_filters_http_conn_man_v1>`
* :ref:`v2 API reference <envoy_api_msg_config.filter.network.http_connection_manager.v2.HttpConnectionManager>`
.. toctree::
:hidden:
route_matching
traffic_splitting
headers
header_sanitizing
stats
runtime
rds

30
docs/root/configuration/http_conn_man/rds.rst
Unescape View File

@ -1,30 +0,0 @@
.. _config_http_conn_man_rds:
Route discovery service (RDS)
=============================
The route discovery service (RDS) API is an optional API that Envoy will call to dynamically fetch
:ref:`route configurations <config_http_conn_man_route_table>`. A route configuration includes both
HTTP header modifications, virtual hosts, and the individual route entries contained within each
virtual host. Each :ref:`HTTP connection manager filter <config_http_conn_man>` can independently
fetch its own route configuration via the API.
* :ref:`v1 API reference <config_http_conn_man_rds_v1>`
* :ref:`v2 API reference <v2_grpc_streaming_endpoints>`
Statistics
----------
RDS has a statistics tree rooted at *http.<stat_prefix>.rds.<route_config_name>.*.
Any ``:`` character in the ``route_config_name`` name gets replaced with ``_`` in the
stats tree. The stats tree contains the following statistics:
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
config_reload, Counter, Total API fetches that resulted in a config reload due to a different config
update_attempt, Counter, Total API fetches attempted
update_success, Counter, Total API fetches completed successfully
update_failure, Counter, Total API fetches that failed (either network or schema errors)
version, Gauge, Hash of the contents from the last successful API fetch

19
docs/root/configuration/http_conn_man/route_matching.rst
Unescape View File

@ -1,19 +0,0 @@
.. _config_http_conn_man_route_table_route_matching:
Route matching
==============
.. attention::
This section is written for the v1 API but the concepts also apply to the v2 API. It will be
rewritten to target the v2 API in a future release.
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.

36
docs/root/configuration/http_conn_man/runtime.rst
Unescape View File

@ -1,36 +0,0 @@
.. _config_http_conn_man_runtime:
Runtime
=======
The HTTP connection manager supports the following runtime settings:
.. _config_http_conn_man_runtime_represent_ipv4_remote_address_as_ipv4_mapped_ipv6:
http_connection_manager.represent_ipv4_remote_address_as_ipv4_mapped_ipv6
% of requests with a remote address that will have their IPv4 address mapped to IPv6. Defaults to
0.
:ref:`use_remote_address <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.use_remote_address>`
must also be enabled. See
:ref:`represent_ipv4_remote_address_as_ipv4_mapped_ipv6
<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.represent_ipv4_remote_address_as_ipv4_mapped_ipv6>`
for more details.
.. _config_http_conn_man_runtime_client_enabled:
tracing.client_enabled
% of requests that will be force traced if the
:ref:`config_http_conn_man_headers_x-client-trace-id` header is set. Defaults to 100.
.. _config_http_conn_man_runtime_global_enabled:
tracing.global_enabled
% of requests that will be traced after all other checks have been applied (force tracing,
sampling, etc.). Defaults to 100.
.. _config_http_conn_man_runtime_random_sampling:
tracing.random_sampling
% of requests that will be randomly traced. See :ref:`here <arch_overview_tracing>` for more
information. This runtime control is specified in the range 0-10000 and defaults to 10000. Thus,
trace sampling can be specified in 0.01% increments.

126
docs/root/configuration/http_conn_man/stats.rst
Unescape View File

@ -1,126 +0,0 @@
.. _config_http_conn_man_stats:
Statistics
==========
Every connection manager has a statistics tree rooted at *http.<stat_prefix>.* with the following
statistics:
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
downstream_cx_total, Counter, Total connections
downstream_cx_ssl_total, Counter, Total TLS connections
downstream_cx_http1_total, Counter, Total HTTP/1.1 connections
downstream_cx_websocket_total, Counter, Total WebSocket connections
downstream_cx_http2_total, Counter, Total HTTP/2 connections
downstream_cx_destroy, Counter, Total connections destroyed
downstream_cx_destroy_remote, Counter, Total connections destroyed due to remote close
downstream_cx_destroy_local, Counter, Total connections destroyed due to local close
downstream_cx_destroy_active_rq, Counter, Total connections destroyed with 1+ active request
downstream_cx_destroy_local_active_rq, Counter, Total connections destroyed locally with 1+ active request
downstream_cx_destroy_remote_active_rq, Counter, Total connections destroyed remotely with 1+ active request
downstream_cx_active, Gauge, Total active connections
downstream_cx_ssl_active, Gauge, Total active TLS connections
downstream_cx_http1_active, Gauge, Total active HTTP/1.1 connections
downstream_cx_websocket_active, Gauge, Total active WebSocket connections
downstream_cx_http2_active, Gauge, Total active HTTP/2 connections
downstream_cx_protocol_error, Counter, Total protocol errors
downstream_cx_length_ms, Histogram, Connection length milliseconds
downstream_cx_rx_bytes_total, Counter, Total bytes received
downstream_cx_rx_bytes_buffered, Gauge, Total received bytes currently buffered
downstream_cx_tx_bytes_total, Counter, Total bytes sent
downstream_cx_tx_bytes_buffered, Gauge, Total sent bytes currently buffered
downstream_cx_drain_close, Counter, Total connections closed due to draining
downstream_cx_idle_timeout, Counter, Total connections closed due to idle timeout
downstream_flow_control_paused_reading_total, Counter, Total number of times reads were disabled due to flow control
downstream_flow_control_resumed_reading_total, Counter, Total number of times reads were enabled on the connection due to flow control
downstream_rq_total, Counter, Total requests
downstream_rq_http1_total, Counter, Total HTTP/1.1 requests
downstream_rq_http2_total, Counter, Total HTTP/2 requests
downstream_rq_active, Gauge, Total active requests
downstream_rq_response_before_rq_complete, Counter, Total responses sent before the request was complete
downstream_rq_rx_reset, Counter, Total request resets received
downstream_rq_tx_reset, Counter, Total request resets sent
downstream_rq_non_relative_path, Counter, Total requests with a non-relative HTTP path
downstream_rq_too_large, Counter, Total requests resulting in a 413 due to buffering an overly large body
downstream_rq_1xx, Counter, Total 1xx responses
downstream_rq_2xx, Counter, Total 2xx responses
downstream_rq_3xx, Counter, Total 3xx responses
downstream_rq_4xx, Counter, Total 4xx responses
downstream_rq_5xx, Counter, Total 5xx responses
downstream_rq_ws_on_non_ws_route, Counter, Total WebSocket upgrade requests rejected by non WebSocket routes
downstream_rq_time, Histogram, Request time milliseconds
rs_too_large, Counter, Total response errors due to buffering an overly large body
Per user agent statistics
-------------------------
Additional per user agent statistics are rooted at *http.<stat_prefix>.user_agent.<user_agent>.*
Currently Envoy matches user agent for both iOS (*ios*) and Android (*android*) and produces
the following statistics:
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
downstream_cx_total, Counter, Total connections
downstream_cx_destroy_remote_active_rq, Counter, Total connections destroyed remotely with 1+ active requests
downstream_rq_total, Counter, Total requests
.. _config_http_conn_man_stats_per_listener:
Per listener statistics
-----------------------
Additional per listener statistics are rooted at *listener.<address>.http.<stat_prefix>.* with the
following statistics:
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
downstream_rq_1xx, Counter, Total 1xx responses
downstream_rq_2xx, Counter, Total 2xx responses
downstream_rq_3xx, Counter, Total 3xx responses
downstream_rq_4xx, Counter, Total 4xx responses
downstream_rq_5xx, Counter, Total 5xx responses
.. _config_http_conn_man_stats_per_codec:
Per codec statistics
-----------------------
Each codec has the option of adding per-codec statistics. Currently only http2 has codec stats.
Http2 codec statistics
~~~~~~~~~~~~~~~~~~~~~~
All http2 statistics are rooted at *http2.*
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
rx_reset, Counter, Total number of reset stream frames received by Envoy
tx_reset, Counter, Total number of reset stream frames transmitted by Envoy
header_overflow, Counter, Total number of connections reset due to the headers being larger than `Envoy::Http::Http2::ConnectionImpl::StreamImpl::MAX_HEADER_SIZE` (63k)
trailers, Counter, Total number of trailers seen on requests coming from downstream
headers_cb_no_stream, Counter, Total number of errors where a header callback is called without an associated stream. This tracks an unexpected occurrence due to an as yet undiagnosed bug
too_many_header_frames, Counter, Total number of times an HTTP2 connection is reset due to receiving too many headers frames. Envoy currently supports proxying at most one header frame for 100-Continue one non-100 response code header frame and one frame with trailers
Tracing statistics
------------------
Tracing statistics are emitted when tracing decisions are made. All tracing statistics are rooted at *http.<stat_prefix>.tracing.* with the following statistics:
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
random_sampling, Counter, Total number of traceable decisions by random sampling
service_forced, Counter, Total number of traceable decisions by server runtime flag *tracing.global_enabled*
client_enabled, Counter, Total number of traceable decisions by request header *x-envoy-force-trace*
not_traceable, Counter, Total number of non-traceable decisions by request id
health_check, Counter, Total number of non-traceable decisions by health check

145
docs/root/configuration/http_conn_man/traffic_splitting.rst
Unescape View File

@ -1,145 +0,0 @@
.. _config_http_conn_man_route_table_traffic_splitting:
Traffic Shifting/Splitting
===========================================
.. attention::
This section is written for the v1 API but the concepts also apply to the v2 API. It will be
rewritten to target the v2 API in a future release.
.. contents::
:local:
Envoy's router can split traffic to a route in a virtual host across
two or more upstream clusters. There are two common use cases.
1. Version upgrades: traffic to a route is shifted gradually
from one cluster to another. The
:ref:`traffic shifting <config_http_conn_man_route_table_traffic_splitting_shift>`
section describes this scenario in more detail.
2. A/B testing or multivariate testing: ``two or more versions`` of
the same service are tested simultaneously. The traffic to the route has to
be *split* between clusters running different versions of the same
service. The
:ref:`traffic splitting <config_http_conn_man_route_table_traffic_splitting_split>`
section describes this scenario in more detail.
.. _config_http_conn_man_route_table_traffic_splitting_shift:
Traffic shifting between two upstreams
--------------------------------------
The :ref:`runtime <config_http_conn_man_route_table_route_runtime>` object
in the route configuration determines the probability of selecting a
particular route (and hence its cluster). By using the runtime
configuration, traffic to a particular route in a virtual host can be
gradually shifted from one cluster to another. Consider the following
example configuration, where two versions ``helloworld_v1`` and
``helloworld_v2`` of a service named ``helloworld`` are declared in the
envoy configuration file.
.. code-block:: json
{
"route_config": {
"virtual_hosts": [
{
"name": "helloworld",
"domains": ["*"],
"routes": [
{
"prefix": "/",
"cluster": "helloworld_v1",
"runtime": {
"key": "routing.traffic_shift.helloworld",
"default": 50
}
},
{
"prefix": "/",
"cluster": "helloworld_v2",
}
]
}
]
}
}
Envoy matches routes with a :ref:`first match <config_http_conn_man_route_table_route_matching>` policy.
If the route has a runtime object, the request will be additionally matched based on the runtime
:ref:`value <config_http_conn_man_route_table_route_runtime_default>`
(or the default, if no value is specified). Thus, by placing routes
back-to-back in the above example and specifying a runtime object in the
first route, traffic shifting can be accomplished by changing the runtime
value. The following are the approximate sequence of actions required to
accomplish the task.
1. In the beginning, set ``routing.traffic_shift.helloworld`` to ``100``,
so that all requests to the ``helloworld`` virtual host would match with
the v1 route and be served by the ``helloworld_v1`` cluster.
2. To start shifting traffic to ``helloworld_v2`` cluster, set
``routing.traffic_shift.helloworld`` to values ``0 < x < 100``. For
instance at ``90``, 1 out of every 10 requests to the ``helloworld``
virtual host will not match the v1 route and will fall through to the v2
route.
3. Gradually decrease the value set in ``routing.traffic_shift.helloworld``
so that a larger percentage of requests match the v2 route.
4. When ``routing.traffic_shift.helloworld`` is set to ``0``, no requests
to the ``helloworld`` virtual host will match to the v1 route. All
traffic would now fall through to the v2 route and be served by the
``helloworld_v2`` cluster.
.. _config_http_conn_man_route_table_traffic_splitting_split:
Traffic splitting across multiple upstreams
-------------------------------------------
Consider the ``helloworld`` example again, now with three versions (v1, v2 and
v3) instead of two. To split traffic evenly across the three versions
(i.e., ``33%, 33%, 34%``), the ``weighted_clusters`` option can be used to
specify the weight for each upstream cluster.
Unlike the previous example, a **single** :ref:`route
<config_http_conn_man_route_table_route>` entry is sufficient. The
:ref:`weighted_clusters <config_http_conn_man_route_table_route_weighted_clusters>`
configuration block in a route can be used to specify multiple upstream clusters
along with weights that indicate the **percentage** of traffic to be sent
to each upstream cluster.
.. code-block:: json
{
"route_config": {
"virtual_hosts": [
{
"name": "helloworld",
"domains": ["*"],
"routes": [
{
"prefix": "/",
"weighted_clusters": {
"runtime_key_prefix" : "routing.traffic_split.helloworld",
"clusters" : [
{ "name" : "helloworld_v1", "weight" : 33 },
{ "name" : "helloworld_v2", "weight" : 33 },
{ "name" : "helloworld_v3", "weight" : 34 }
]
}
}
]
}
]
}
}
By default, the weights must sum to exactly 100. In the V2 API, the
:ref:`total weight <envoy_api_field_route.WeightedCluster.total_weight>` defaults to 100, but can
be modified to allow finer granularity.
The weights assigned to each cluster can be dynamically adjusted using the
following runtime variables: ``routing.traffic_split.helloworld.helloworld_v1``,
``routing.traffic_split.helloworld.helloworld_v2`` and
``routing.traffic_split.helloworld.helloworld_v3``.

23
docs/root/configuration/http_filters/buffer_filter.rst
Unescape View File

@ -1,23 +0,0 @@
.. _config_http_filters_buffer:
Buffer
======
The buffer filter is used to stop filter iteration and wait for a fully buffered complete request.
This is useful in different situations including protecting some applications from having to deal
with partial requests and high network latency.
* :ref:`v1 API reference <config_http_filters_buffer_v1>`
* :ref:`v2 API reference <envoy_api_msg_config.filter.http.buffer.v2.Buffer>`
Statistics
----------
The buffer filter outputs statistics in the *http.<stat_prefix>.buffer.* namespace. The :ref:`stat
prefix <config_http_conn_man_stat_prefix>` comes from the owning HTTP connection manager.
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
rq_timeout, Counter, Total requests that timed out waiting for a full request

12
docs/root/configuration/http_filters/cors_filter.rst
Unescape View File

@ -1,12 +0,0 @@
.. _config_http_filters_cors:
CORS
====
This is a filter which handles Cross-Origin Resource Sharing requests based on route or virtual host settings.
For the meaning of the headers please refer to the pages below.
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
- https://www.w3.org/TR/cors/
- :ref:`v1 API reference <config_http_filters_cors_v1>`
- :ref:`v2 API reference <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpFilter.name>`

71
docs/root/configuration/http_filters/dynamodb_filter.rst
Unescape View File

@ -1,71 +0,0 @@
.. _config_http_filters_dynamo:
DynamoDB
========
* DynamoDB :ref:`architecture overview <arch_overview_dynamo>`
* :ref:`v1 API reference <config_http_filters_dynamo_v1>`
* :ref:`v2 API reference <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpFilter.name>`
Statistics
----------
The DynamoDB filter outputs statistics in the *http.<stat_prefix>.dynamodb.* namespace. The
:ref:`stat prefix <config_http_conn_man_stat_prefix>` comes from the owning HTTP connection manager.
Per operation stats can be found in the *http.<stat_prefix>.dynamodb.operation.<operation_name>.*
namespace.
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
upstream_rq_total, Counter, Total number of requests with <operation_name>
upstream_rq_time, Histogram, Time spent on <operation_name>
upstream_rq_total_xxx, Counter, Total number of requests with <operation_name> per response code (503/2xx/etc)
upstream_rq_time_xxx, Histogram, Time spent on <operation_name> per response code (400/3xx/etc)
Per table stats can be found in the *http.<stat_prefix>.dynamodb.table.<table_name>.* namespace.
Most of the operations to DynamoDB involve a single table, but BatchGetItem and BatchWriteItem can
include several tables, Envoy tracks per table stats in this case only if it is the same table used
in all operations from the batch.
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
upstream_rq_total, Counter, Total number of requests on <table_name> table
upstream_rq_time, Histogram, Time spent on <table_name> table
upstream_rq_total_xxx, Counter, Total number of requests on <table_name> table per response code (503/2xx/etc)
upstream_rq_time_xxx, Histogram, Time spent on <table_name> table per response code (400/3xx/etc)
*Disclaimer: Please note that this is a pre-release Amazon DynamoDB feature that is not yet widely available.*
Per partition and operation stats can be found in the *http.<stat_prefix>.dynamodb.table.<table_name>.*
namespace. For batch operations, Envoy tracks per partition and operation stats only if it is the same
table used in all operations.
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
capacity.<operation_name>.__partition_id=<last_seven_characters_from_partition_id>, Counter, Total number of capacity for <operation_name> on <table_name> table for a given <partition_id>
Additional detailed stats:
* For 4xx responses and partial batch operation failures, the total number of failures for a given
table and failure are tracked in the *http.<stat_prefix>.dynamodb.error.<table_name>.* namespace.
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
<error_type>, Counter, Total number of specific <error_type> for a given <table_name>
BatchFailureUnprocessedKeys, Counter, Total number of partial batch failures for a given <table_name>
Runtime
-------
The DynamoDB filter supports the following runtime settings:
dynamodb.filter_enabled
The % of requests for which the filter is enabled. Default is 100%.

92
docs/root/configuration/http_filters/fault_filter.rst
Unescape View File

@ -1,92 +0,0 @@
.. _config_http_filters_fault_injection:
Fault Injection
===============
The fault injection filter can be used to test the resiliency of
microservices to different forms of failures. The filter can be used to
inject delays and abort requests with user-specified error codes, thereby
providing the ability to stage different failure scenarios such as service
failures, service overloads, high network latency, network partitions,
etc. Faults injection can be limited to a specific set of requests based on
the (destination) upstream cluster of a request and/or a set of pre-defined
request headers.
The scope of failures is restricted to those that are observable by an
application communicating over the network. CPU and disk failures on the
local host cannot be emulated.
Currently, the fault injection filter has the following limitations:
* Abort codes are restricted to HTTP status codes only
* Delays are restricted to fixed duration.
Future versions will include support for restricting faults to specific
routes, injecting *gRPC* and *HTTP/2* specific error codes and delay
durations based on distributions.
Configuration
-------------
.. note::
The fault injection filter must be inserted before any other filter,
including the router filter.
* :ref:`v1 API reference <config_http_filters_fault_injection_v1>`
* :ref:`v2 API reference <envoy_api_msg_config.filter.http.fault.v2.HTTPFault>`
Runtime
-------
The HTTP fault injection filter supports the following global runtime settings:
fault.http.abort.abort_percent
% of requests that will be aborted if the headers match. Defaults to the
*abort_percent* specified in config. If the config does not contain an
*abort* block, then *abort_percent* defaults to 0.
fault.http.abort.http_status
HTTP status code that will be used as the of requests that will be
aborted if the headers match. Defaults to the HTTP status code specified
in the config. If the config does not contain an *abort* block, then
*http_status* defaults to 0.
fault.http.delay.fixed_delay_percent
% of requests that will be delayed if the headers match. Defaults to the
*delay_percent* specified in the config or 0 otherwise.
fault.http.delay.fixed_duration_ms
The delay duration in milliseconds. If not specified, the
*fixed_duration_ms* specified in the config will be used. If this field
is missing from both the runtime and the config, no delays will be
injected.
*Note*, fault filter runtime settings for the specific downstream cluster
override the default ones if present. The following are downstream specific
runtime keys:
* fault.http.<downstream-cluster>.abort.abort_percent
* fault.http.<downstream-cluster>.abort.http_status
* fault.http.<downstream-cluster>.delay.fixed_delay_percent
* fault.http.<downstream-cluster>.delay.fixed_duration_ms
Downstream cluster name is taken from
:ref:`the HTTP x-envoy-downstream-service-cluster <config_http_conn_man_headers_downstream-service-cluster>`
header. If the following settings are not found in the runtime it defaults to the global runtime settings
which defaults to the config settings.
Statistics
----------
The fault filter outputs statistics in the *http.<stat_prefix>.fault.* namespace. The :ref:`stat
prefix <config_http_conn_man_stat_prefix>` comes from the owning HTTP connection manager.
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
delays_injected, Counter, Total requests that were delayed
aborts_injected, Counter, Total requests that were aborted
<downstream-cluster>.delays_injected, Counter, Total delayed requests for the given downstream cluster
<downstream-cluster>.aborts_injected, Counter, Total aborted requests for the given downstream cluster

50
docs/root/configuration/http_filters/grpc_http1_bridge_filter.rst
Unescape View File

@ -1,50 +0,0 @@
.. _config_http_filters_grpc_bridge:
gRPC HTTP/1.1 bridge
====================
* gRPC :ref:`architecture overview <arch_overview_grpc>`
* :ref:`v1 API reference <config_http_filters_grpc_bridge_v1>`
* :ref:`v2 API reference <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpFilter.name>`
This is a simple filter which enables the bridging of an HTTP/1.1 client which does not support
response trailers to a compliant gRPC server. It works by doing the following:
* When a request is sent, the filter sees if the connection is HTTP/1.1 and the request content type
is *application/grpc*.
* If so, when the response is received, the filter buffers it and waits for trailers and then checks the
*grpc-status* code. If it is not zero, the filter switches the HTTP response code to 503. It also copies
the *grpc-status* and *grpc-message* trailers into the response headers so that the client can look
at them if it wishes.
* The client should send HTTP/1.1 requests that translate to the following pseudo headers:
* *\:method*: POST
* *\:path*: <gRPC-METHOD-NAME>
* *content-type*: application/grpc
* The body should be the serialized grpc body which is:
* 1 byte of zero (not compressed).
* network order 4 bytes of proto message length.
* serialized proto message.
* Because this scheme must buffer the response to look for the *grpc-status* trailer it will only
work with unary gRPC APIs.
This filter also collects stats for all gRPC requests that transit, even if those requests are
normal gRPC requests over HTTP/2.
More info: wire format in `gRPC over HTTP/2 <https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md>`_.
Statistics
----------
The filter emits statistics in the *cluster.<route target cluster>.grpc.* namespace.
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
<grpc service>.<grpc method>.success, Counter, Total successful service/method calls
<grpc service>.<grpc method>.failure, Counter, Total failed service/method calls
<grpc service>.<grpc method>.total, Counter, Total service/method calls

37
docs/root/configuration/http_filters/grpc_json_transcoder_filter.rst
Unescape View File

@ -1,37 +0,0 @@
.. _config_http_filters_grpc_json_transcoder:
gRPC-JSON transcoder
====================
* gRPC :ref:`architecture overview <arch_overview_grpc>`
* :ref:`v1 API reference <config_http_filters_grpc_json_transcoder_v1>`
* :ref:`v2 API reference <envoy_api_msg_config.filter.http.transcoder.v2.GrpcJsonTranscoder>`
This is a filter which allows a RESTful JSON API client to send requests to Envoy over HTTP
and get proxied to a gRPC service. The HTTP mapping for the gRPC service has to be defined by
`custom options <https://cloud.google.com/service-management/reference/rpc/google.api#http>`_.
.. _config_grpc_json_generate_proto_descriptor_set:
How to generate proto descriptor set
------------------------------------
Envoy has to know the proto descriptor of your gRPC service in order to do the transcoding.
To generate a protobuf descriptor set for the gRPC service, you'll also need to clone the
googleapis repository from GitHub before running protoc, as you'll need annotations.proto
in your include path, to define the HTTP mapping.
.. code-block:: bash
git clone https://github.com/googleapis/googleapis
GOOGLEAPIS_DIR=<your-local-googleapis-folder>
Then run protoc to generate the descriptor set from bookstore.proto:
.. code-block:: bash
protoc -I$(GOOGLEAPIS_DIR) -I. --include_imports --include_source_info \
--descriptor_set_out=proto.pb test/proto/bookstore.proto
If you have more than one proto source files, you can pass all of them in one command.

11
docs/root/configuration/http_filters/grpc_web_filter.rst
Unescape View File

@ -1,11 +0,0 @@
.. _config_http_filters_grpc_web:
gRPC-Web
========
* gRPC :ref:`architecture overview <arch_overview_grpc>`
* :ref:`v1 API reference <config_http_filters_grpc_web_v1>`
* :ref:`v2 API reference <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpFilter.name>`
This is a filter which enables the bridging of a gRPC-Web client to a compliant gRPC server by
following https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md.

51
docs/root/configuration/http_filters/gzip_filter.rst
Unescape View File

@ -1,51 +0,0 @@
.. _config_http_filters_gzip:
Gzip
====
Gzip is an HTTP filter which enables Envoy to compress dispatched data
from an upstream service upon client request. Compression is useful in
situations where large payloads need to be transmitted without
compromising the response time.
Configuration
-------------
* :ref:`v2 API reference <envoy_api_msg_config.filter.http.gzip.v2.Gzip>`
.. attention::
The *window bits* is a number that tells the compressor how far ahead in the
text the algorithm should be looking for repeated sequence of characters.
Due to a known bug in the underlying zlib library, *window bits* with value
eight does not work as expected. Therefore any number below that will be
automatically set to 9. This issue might be solved in future releases of
the library.
How it works
------------
When gzip filter is enabled, request and response headers are inspected to
determine whether or not the content should be compressed. The content is
compressed and then sent to the client with the appropriate headers if either
response and request allow.
By *default* compression will be *skipped* when:
- A request does NOT contain *accept-encoding* header.
- A request includes *accept-encoding* header, but it does not contain "gzip".
- A response contains a *content-encoding* header.
- A Response contains a *cache-control* header whose value includes "no-transform".
- A response contains a *transfer-encoding* header whose value includes "gzip".
- A response does not contain a *content-type* value that matches one of the selected
mime-types, which default to *application/javascript*, *application/json*,
*application/xhtml+xml*, *image/svg+xml*, *text/css*, *text/html*, *text/plain*,
*text/xml*.
- Neither *content-length* nor *transfer-encoding* headers are present in
the response.
- Response size is smaller than 30 bytes (only applicable when *transfer-encoding*
is not chuncked).
When compression is *applied*:
- The *content-length* is removed from response headers.
- Response headers contain "*transfer-encoding: chunked*" and
"*content-encoding: gzip*".
- The "*vary: accept-encoding*" header is inserted on every response.

17
docs/root/configuration/http_filters/health_check_filter.rst
Unescape View File

@ -1,17 +0,0 @@
.. _config_http_filters_health_check:
Health check
============
* Health check filter :ref:`architecture overview <arch_overview_health_checking_filter>`
* :ref:`v1 API reference <config_http_filters_health_check_v1>`
* :ref:`v2 API reference <envoy_api_msg_config.filter.http.health_check.v2.HealthCheck>`
.. note::
Note that the filter will automatically fail health checks and set the
:ref:`x-envoy-immediate-health-check-fail
<config_http_filters_router_x-envoy-immediate-health-check-fail>` header if the
:ref:`/healthcheck/fail <operations_admin_interface_healthcheck_fail>` admin endpoint has been
called. (The :ref:`/healthcheck/ok <operations_admin_interface_healthcheck_ok>` admin endpoint
reverses this behavior).

22
docs/root/configuration/http_filters/http_filters.rst
Unescape View File

@ -1,22 +0,0 @@
.. _config_http_filters:
HTTP filters
============
.. toctree::
:maxdepth: 2
buffer_filter
cors_filter
dynamodb_filter
fault_filter
grpc_http1_bridge_filter
grpc_json_transcoder_filter
grpc_web_filter
gzip_filter
health_check_filter
ip_tagging_filter
lua_filter
rate_limit_filter
router_filter
squash_filter

41
docs/root/configuration/http_filters/ip_tagging_filter.rst
Unescape View File

@ -1,41 +0,0 @@
.. _config_http_filters_ip_tagging:
IP Tagging
==========
The HTTP IP Tagging filter sets the header *x-envoy-ip-tags* with the string tags for the trusted address from
:ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>`. If there are no tags for an address,
the header is not set.
The implementation for IP Tagging provides a scalable way to compare an IP address to a large list of CIDR
ranges efficiently. The underlying algorithm for storing tags and IP address subnets is a Level-Compressed trie
described in the paper `IP-address lookup using
LC-tries <https://www.nada.kth.se/~snilsson/publications/IP-address-lookup-using-LC-tries/>`_ by S. Nilsson and
G. Karlsson.
Configuration
-------------
* :ref:`v2 API reference <envoy_api_msg_config.filter.http.ip_tagging.v2.IPTagging>`
Statistics
----------
The IP Tagging filter outputs statistics in the *http.<stat_prefix>.ip_tagging.* namespace. The stat prefix comes from
the owning HTTP connection manager.
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
<tag_name>.hit, Counter, Total number of requests that have the <tag_name> applied to it
no_hit, Counter, Total number of requests with no applicable IP tags
total, Counter, Total number of requests the IP Tagging Filter operated on
Runtime
-------
The IP Tagging filter supports the following runtime settings:
ip_tagging.http_filter_enabled
The % of requests for which the filter is enabled. Default is 100.

417
docs/root/configuration/http_filters/lua_filter.rst
Unescape View File

@ -1,417 +0,0 @@
.. _config_http_filters_lua:
Lua
===
.. attention::
The Lua scripting HTTP filter is **experimental**. Use in production at your own risk. It is
being released for initial feedback on the exposed API and for further development, testing,
and verification. This warning will be removed when we feel that the filter has received enough
testing and API stability to call it generally production ready.
.. attention::
By default Envoy is built without exporting symbols that you may need when interacting with Lua
modules installed as shared objects. Envoy may need to be built with support for exported symbols.
Please see the :repo:`Bazel docs <bazel/README.md>` for more information.
Overview
--------
The HTTP Lua filter allows `Lua <https://www.lua.org/>`_ scripts to be run during both the request
and response flows. `LuaJIT <http://luajit.org/>`_ is used as the runtime. Because of this, the
supported Lua version is mostly 5.1 with some 5.2 features. See the `LuaJIT documentation
<http://luajit.org/extensions.html>`_ for more details.
The filter only supports loading Lua code in-line in the configuration. If local filesystem code
is desired, a trivial in-line script can be used to load the rest of the code from the local
environment.
The design of the filter and Lua support at a high level is as follows:
* All Lua environments are :ref:`per worker thread <arch_overview_threading>`. This means that
there is no truly global data. Any globals create and populated at load time will be visible
from each worker thread in isolation. True global support may be added via an API in the future.
* All scripts are run as coroutines. This means that they are written in a synchronous style even
though they may perform complex asynchronous tasks. This makes the scripts substantially easier
to write. All network/async processing is performed by Envoy via a set of APIs. Envoy will
yield the script as appropriate and resume it when async tasks are complete.
* **Do not perform blocking operations from scripts.** It is critical for performance that
Envoy APIs are used for all IO.
Currently supported high level features
---------------------------------------
**NOTE:** It is expected that this list will expand over time as the filter is used in production.
The API surface has been kept small on purpose. The goal is to make scripts extremely simple and
safe to write. Very complex or high performance use cases are assumed to use the native C++ filter
API.
* Inspection of headers, body, and trailers while streaming in either the request flow, response
flow, or both.
* Modification of headers and trailers.
* Blocking and buffering the full request/response body for inspection.
* Performing an outbound async HTTP call to an upstream host. Such a call can be performed while
buffering body data so that when the call completes upstream headers can be modified.
* Performing a direct response and skipping further filter iteration. For example, a script
could make an upstream HTTP call for authentication, and then directly respond with a 403
response code.
Configuration
-------------
* :ref:`v1 API reference <config_http_filters_lua_v1>`
* :ref:`v2 API reference <envoy_api_msg_config.filter.http.lua.v2.Lua>`
Script examples
---------------
This section provides some concrete examples of Lua scripts as a more gentle introduction and quick
start. Please refer to the :ref:`stream handle API <config_http_filters_lua_stream_handle_api>` for
more details on the supported API.
.. code-block:: lua
-- Called on the request path.
function envoy_on_request(request_handle)
-- Wait for the entire request body and add a request header with the body size.
request_handle:headers():add("request_body_size", request_handle:body():length())
end
-- Called on the response path.
function envoy_on_response(response_handle)
-- Wait for the entire response body and a response header with the the body size.
response_handle:headers():add("response_body_size", response_handle:body():length())
-- Remove a response header named 'foo'
response_handle:headers():remove("foo")
end
.. code-block:: lua
function envoy_on_request(request_handle)
-- Make an HTTP call to an upstream host with the following headers, body, and timeout.
local headers, body = request_handle:httpCall(
"lua_cluster",
{
[":method"] = "POST",
[":path"] = "/",
[":authority"] = "lua_cluster"
},
"hello world",
5000)
-- Add information from the HTTP call into the headers that are about to be sent to the next
-- filter in the filter chain.
request_handle:headers():add("upstream_foo", headers["foo"])
request_handle:headers():add("upstream_body_size", #body)
end
.. code-block:: lua
function envoy_on_request(request_handle)
-- Make an HTTP call.
local headers, body = request_handle:httpCall(
"lua_cluster",
{
[":method"] = "POST",
[":path"] = "/",
[":authority"] = "lua_cluster"
},
"hello world",
5000)
-- Response directly and set a header from the HTTP call. No further filter iteration
-- occurs.
request_handle:respond(
{[":status"] = "403",
["upstream_foo"] = headers["foo"]},
"nope")
end
.. _config_http_filters_lua_stream_handle_api:
Stream handle API
-----------------
When Envoy loads the script in the configuration, it looks for two global functions that the
script defines:
.. code-block:: lua
function envoy_on_request(request_handle)
end
function envoy_on_response(response_handle)
end
A script can define either or both of these functions. During the request path, Envoy will
run *envoy_on_request* as a coroutine, passing an API handle. During the response path, Envoy will
run *envoy_on_response* as a coroutine, passing an API handle.
.. attention::
It is critical that all interaction with Envoy occur through the passed stream handle. The stream
handle should not be assigned to any global variable and should not be used outside of the
coroutine. Envoy will fail your script if the handle is used incorrectly.
The following methods on the stream handle are supported:
headers()
^^^^^^^^^
.. code-block:: lua
headers = handle:headers()
Returns the stream's headers. The headers can be modified as long as they have not been sent to
the next filter in the header chain. For example, they can be modified after an *httpCall()* or
after a *body()* call returns. The script will fail if the headers are modified in any other
situation.
Returns a :ref:`header object <config_http_filters_lua_header_wrapper>`.
body()
^^^^^^
.. code-block:: lua
body = handle:body()
Returns the stream's body. This call will cause Envoy to yield the script until the entire body
has been buffered. Note that all buffering must adhere to the flow control policies in place.
Envoy will not buffer more data than is allowed by the connection manager.
Returns a :ref:`buffer object <config_http_filters_lua_buffer_wrapper>`.
bodyChunks()
^^^^^^^^^^^^
.. code-block:: lua
iterator = handle:bodyChunks()
Returns an iterator that can be used to iterate through all received body chunks as they arrive.
Envoy will yield the script in between chunks, but *will not buffer* them. This can be used by
a script to inspect data as it is streaming by.
.. code-block:: lua
for chunk in request_handle:bodyChunks() do
request_handle:log(0, chunk:length())
end
Each chunk the iterator returns is a :ref:`buffer object <config_http_filters_lua_buffer_wrapper>`.
trailers()
^^^^^^^^^^
.. code-block:: lua
trailers = handle:trailers()
Returns the stream's trailers. May return nil if there are no trailers. The trailers may be
modified before they are sent to the next filter.
Returns a :ref:`header object <config_http_filters_lua_header_wrapper>`.
log*()
^^^^^^
.. code-block:: lua
handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)
Logs a message using Envoy's application logging. *message* is a string to log.
httpCall()
^^^^^^^^^^
.. code-block:: lua
headers, body = handle:httpCall(cluster, headers, body, timeout)
Makes an HTTP call to an upstream host. Envoy will yield the script until the call completes or
has an error. *cluster* is a string which maps to a configured cluster manager cluster. *headers*
is a table of key/value pairs to send. Note that the *:method*, *:path*, and *:authority* headers
must be set. *body* is an optional string of body data to send. *timeout* is an integer that
specifies the call timeout in milliseconds.
Returns *headers* which is a table of response headers. Returns *body* which is the string response
body. May be nil if there is no body.
respond()
^^^^^^^^^^
.. code-block:: lua
handle:respond(headers, body)
Respond immediately and do not continue further filter iteration. This call is *only valid in
the request flow*. Additionally, a response is only possible if request headers have not yet been
passed to subsequent filters. Meaning, the following Lua code is invalid:
.. code-block:: lua
function envoy_on_request(request_handle)
for chunk in request_handle:bodyChunks() do
request_handle:respond(
{[":status"] = "100"},
"nope")
end
end
*headers* is a table of key/value pairs to send. Note that the *:status* header
must be set. *body* is a string and supplies the optional response body. May be nil.
metadata()
^^^^^^^^^^
.. code-block:: lua
metadata = handle:metadata()
Returns the current route entry metadata. Note that the metadata should be specified
under the filter name i.e. *envoy.lua*. Below is an example of a *metadata* in a
:ref:`route entry <config_http_conn_man_route_table_route>`.
.. code-block:: yaml
metadata:
filter_metadata:
envoy.lua:
foo: bar
baz:
- bad
- baz
Returns a :ref:`metadata object <config_http_filters_lua_metadata_wrapper>`.
.. _config_http_filters_lua_header_wrapper:
Header object API
-----------------
add()
^^^^^
.. code-block:: lua
headers:add(key, value)
Adds a header. *key* is a string that supplies the header key. *value* is a string that supplies
the header value.
.. attention::
Envoy treats certain headers specially. These are known as the O(1) or *inline* headers. The
list of inline headers can be found `here <https://github.com/envoyproxy/envoy/blob/6b6ce85a24094146c5c225f19b6ecc47b2ca84bf/include/envoy/http/header_map.h#L228>`_.
If an inline header is already present in the header map, *add()* will have no effect. If
attempting to *add()* a non-inline header, the additional header will be added so that the
resultant headers contains multiple header entries with the same name. Consider using the
*replace* function if want to replace a header with another value. Note also that we
understand this behavior is confusing and we may change it in a future release.
get()
^^^^^
.. code-block:: lua
headers:get(key)
Gets a header. *key* is a string that supplies the header key. Returns a string that is the header
value or nil if there is no such header.
__pairs()
^^^^^^^^^
.. code-block:: lua
for key, value in pairs(headers) do
end
Iterates through every header. *key* is a string that supplies the header key. *value* is a string
that supplies the header value.
.. attention::
In the currently implementation, headers cannot be modified during iteration. Additionally, if
it is desired to modify headers after iteration, the iteration must be completed. Meaning, do
not use `break` or any other mechanism to exit the loop early. This may be relaxed in the future.
remove()
^^^^^^^^
.. code-block:: lua
headers:remove(key)
Removes a header. *key* supplies the header key to remove.
replace()
^^^^^^^^^
.. code-block:: lua
headers:replace(key, value)
Replaces a header. *key* is a string that supplies the header key. *value* is a string that supplies
the header value. If the header does not exist, it is added as per the *add()* function.
.. _config_http_filters_lua_buffer_wrapper:
Buffer API
----------
length()
^^^^^^^^^^
.. code-block:: lua
size = buffer:length()
Gets the size of the buffer in bytes. Returns an integer.
getBytes()
^^^^^^^^^^
.. code-block:: lua
buffer:getBytes(index, length)
Get bytes from the buffer. By default Envoy will not copy all buffer bytes to Lua. This will
cause a buffer segment to be copied. *index* is an integer and supplies the buffer start index to
copy. *length* is an integer and supplies the buffer length to copy. *index* + *length* must be
less than the buffer length.
.. _config_http_filters_lua_metadata_wrapper:
Metadata object API
-------------------
get()
^^^^^
.. code-block:: lua
metadata:get(key)
Gets a metadata. *key* is a string that supplies the metadata key. Returns the corresponding
value of the given metadata key. The type of the value can be: *null*, *boolean*, *number*,
*string* and *table*.
__pairs()
^^^^^^^^^
.. code-block:: lua
for key, value in pairs(metadata) do
end
Iterates through every *metadata* entry. *key* is a string that supplies a *metadata*
key. *value* is *metadata* entry value.

126
docs/root/configuration/http_filters/rate_limit_filter.rst
Unescape View File

@ -1,126 +0,0 @@
.. _config_http_filters_rate_limit:
Rate limit
==========
* Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`
* :ref:`v1 API reference <config_http_filters_rate_limit_v1>`
* :ref:`v2 API reference <envoy_api_msg_config.filter.http.rate_limit.v2.RateLimit>`
The HTTP rate limit filter will call the rate limit service when the request's route or virtual host
has one or more :ref:`rate limit configurations<config_http_conn_man_route_table_route_rate_limits>`
that match the filter stage setting. The :ref:`route<config_http_conn_man_route_table_route_include_vh>`
can optionally include the virtual host rate limit configurations. More than one configuration can
apply to a request. Each configuration results in a descriptor being sent to the rate limit service.
If the rate limit service is called, and the response for any of the descriptors is over limit, a
429 response is returned.
.. _config_http_filters_rate_limit_composing_actions:
Composing Actions
-----------------
.. attention::
This section is written for the v1 API but the concepts also apply to the v2 API. It will be
rewritten to target the v2 API in a future release.
Each :ref:`rate limit action <config_http_conn_man_route_table_rate_limit_config>` on the route or
virtual host populates a descriptor entry. A vector of descriptor entries compose a descriptor. To
create more complex rate limit descriptors, actions can be composed in any order. The descriptor
will be populated in the order the actions are specified in the configuration.
Example 1
^^^^^^^^^
For example, to generate the following descriptor:
.. code-block:: cpp
("generic_key", "some_value")
("source_cluster", "from_cluster")
The configuration would be:
.. code-block:: json
{
"actions" : [
{
"type" : "generic_key",
"descriptor_value" : "some_value"
},
{
"type" : "source_cluster"
}
]
}
Example 2
^^^^^^^^^
If an action doesn't append a descriptor entry, no descriptor is generated for
the configuration.
For the following configuration:
.. code-block:: json
{
"actions" : [
{
"type" : "generic_key",
"descriptor_value" : "some_value"
},
{
"type" : "remote_address"
},
{
"type" : "souce_cluster"
}
]
}
If a request did not set :ref:`x-forwarded-for<config_http_conn_man_headers_x-forwarded-for>`,
no descriptor is generated.
If a request sets :ref:`x-forwarded-for<config_http_conn_man_headers_x-forwarded-for>`, the
the following descriptor is generated:
.. code-block:: cpp
("generic_key", "some_value")
("remote_address", "<trusted address from x-forwarded-for>")
("source_cluster", "from_cluster")
Statistics
----------
The buffer filter outputs statistics in the *cluster.<route target cluster>.ratelimit.* namespace.
429 responses are emitted to the normal cluster :ref:`dynamic HTTP statistics
<config_cluster_manager_cluster_stats_dynamic_http>`.
.. csv-table::
:header: Name, Type, Description
:widths: 1, 1, 2
ok, Counter, Total under limit responses from the rate limit service
error, Counter, Total errors contacting the rate limit service
over_limit, Counter, total over limit responses from the rate limit service
Runtime
-------
The HTTP rate limit filter supports the following runtime settings:
ratelimit.http_filter_enabled
% of requests that will call the rate limit service. Defaults to 100.
ratelimit.http_filter_enforcing
% of requests that will call the rate limit service and enforce the decision. Defaults to 100.
This can be used to test what would happen before fully enforcing the outcome.
ratelimit.<route_key>.http_filter_enabled
% of requests that will call the rate limit service for a given *route_key* specified in the
:ref:`rate limit configuration <config_http_conn_man_route_table_rate_limit_config>`. Defaults to 100.

Some files were not shown because too many files have changed in this diff Show More

Write Preview
Loading…
Cancel
Save