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

docs: Finish RDS / ratelimit docs (#273)

Browse Source 
Signed-off-by: Matt Klein <mklein@lyft.com>
pull/274/head
Matt Klein 7 years ago committed by GitHub
parent 8577f13587
commit 6928bdd17a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 186 additions and 114 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. 133
      api/rds.proto
  2. 74
      docs/root/api-v1/route_config/rate_limits.rst
  3. 4
      docs/root/configuration/http_conn_man/http_conn_man.rst
  4. 4
      docs/root/configuration/http_conn_man/rds.rst
  5. 78
      docs/root/configuration/http_filters/rate_limit_filter.rst
  6. 7
      tools/protodoc/protodoc.py

133
api/rds.proto
Unescape View File

@ -203,6 +203,7 @@ message RouteAction {
// :ref:`retry overview <arch_overview_http_routing_retry>`.
google.protobuf.Duration timeout = 8;
// HTTP retry :ref:`architecture overview <arch_overview_http_routing_retry>`.
message RetryPolicy {
// 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
@ -261,6 +262,8 @@ message RouteAction {
// Specifies a set of headers that will be added to requests matching this
// route. Headers specified at this level are applied before headers from the
// enclosing :ref:`envoy_api_msg_VirtualHost` and :ref:`envoy_api_msg_RouteConfiguration`.
// For more information see the documentation on :ref:`custom request headers
// <config_http_conn_man_headers_custom_request_headers>`.
repeated HeaderValueOption request_headers_to_add = 12;
// Specifies a set of headers that will be added to responses to requests
@ -282,6 +285,8 @@ message RouteAction {
// :ref:`rate_limits <envoy_api_field_VirtualHost.rate_limits>` are not applied to the request.
google.protobuf.BoolValue include_vh_rate_limits = 14;
// Specifies the route's hashing policy if the upstream cluster uses a hashing :ref:`load balancer
// <arch_overview_load_balancing_types>`.
message HashPolicy {
message Header {
// The name of the request header that will be used to obtain the hash
@ -408,6 +413,13 @@ message Decorator {
string operation = 1 [(validate.rules).string.min_len = 1];
}
// A route is both a specification of how to match a request as well as an indication of what to do
// next (e.g., redirect, forward, rewrite, etc.).
//
// .. attention::
//
// Envoy supports routing on HTTP method via :ref:`header matching
// <envoy_api_msg_HeaderMatcher>`.
message Route {
// Route matching parameters.
RouteMatch match = 1 [(validate.rules).message.required = true];
@ -447,12 +459,6 @@ message Route {
// statistics are perfect in the sense that they are emitted on the downstream
// side such that they include network level failures.
//
// 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>`.
//
// .. note::
@ -464,6 +470,12 @@ message VirtualCluster {
// 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>`_.
//
// 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*
string pattern = 1 [(validate.rules).string.min_len = 1];
// Specifies the name of the virtual cluster. The virtual cluster name as well
@ -476,6 +488,7 @@ message VirtualCluster {
RequestMethod method = 3;
}
// Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`.
message RateLimit {
// 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
@ -484,80 +497,126 @@ message RateLimit {
// .. note::
//
// The filter supports a range of 0 - 10 inclusively for stage numbers.
google.protobuf.UInt32Value stage = 1;
google.protobuf.UInt32Value stage = 1 [(validate.rules).uint32.lte = 10];
// The key to be set in runtime to disable this rate limit configuration.
string disable_key = 2;
message Action {
// The following descriptor entry is appended to the descriptor:
// ("source_cluster", "<local service cluster>")
message SourceCluster {
}
//
// .. code-block:: cpp
//
// ("source_cluster", "<local service cluster>")
//
// <local service cluster> is derived from the :option:`--service-cluster` option.
message SourceCluster {}
// The following descriptor entry is appended to the descriptor:
// ("destination_cluster", "<routed target cluster>")
message DestinationCluster {
}
// The following descriptor entry is appended when a header contains a key
// that matches the header_name:
// ("<descriptor_key>", "<header_value_queried_from_header>")
//
// .. 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 <envoy_api_msg_RouteConfiguration>`
// settings:
//
// * :ref:`cluster <envoy_api_field_RouteAction.cluster>` indicates the upstream cluster
// to route to.
// * :ref:`weighted_clusters <envoy_api_field_RouteAction.weighted_clusters>`
// chooses a cluster randomly from a set of clusters with attributed weight.
// * :ref:`cluster_header <envoy_api_field_RouteAction.cluster_header>` indicates which
// header in the request contains the target cluster.
message DestinationCluster {}
// 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>")
message RequestHeaders {
// 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.
string header_name = 1;
string header_name = 1 [(validate.rules).string.min_len = 1];
// The key to use in the descriptor entry.
string descriptor_key = 2;
string descriptor_key = 2 [(validate.rules).string.min_len = 1];
}
// The following descriptor entry is appended to the descriptor and is
// populated using the trusted address from x-forwarded-for:
// ("remote_address", "<trusted address from x-forwarded-for>")
message RemoteAddress {
}
// 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>")
message RemoteAddress {}
// The following descriptor entry is appended to the descriptor:
// ("generic_key", "<descriptor_value>")
//
// .. code-block:: cpp
//
// ("generic_key", "<descriptor_value>")
message GenericKey {
// The value to use in the descriptor entry.
string descriptor_value = 1;
string descriptor_value = 1 [(validate.rules).string.min_len = 1];
}
// The following descriptor entry is appended to the descriptor:
// (“header_match”, “<descriptor_value>”)
//
// .. code-block:: cpp
//
// ("header_match", "<descriptor_value>")
message HeaderValueMatch {
// The value to use in the descriptor entry.
string descriptor_value = 1;
string descriptor_value = 1 [(validate.rules).string.min_len = 1];
// If set to true, the action will append a descriptor entry when the
// request matches the headers. If set to false, the action will append a
// descriptor entry when the request does not match the headers. The
// default value is true.
google.protobuf.BoolValue expect_match = 2;
// 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).
repeated HeaderMatcher headers = 3;
repeated HeaderMatcher headers = 3 [(validate.rules).repeated.min_items = 1];
}
oneof action_specifier {
option (validate.required) = true;
// Rate limit on source cluster.
SourceCluster source_cluster = 1;
// Rate limit on destination cluster.
DestinationCluster destination_cluster = 2;
// Rate limit on request headers.
RequestHeaders request_headers = 3;
// Rate limit on remote address.
RemoteAddress remote_address = 4;
// Rate limit on a generic key.
GenericKey generic_key = 5;
// Rate limit on the existence of request headers.
HeaderValueMatch header_value_match = 6;
}
}
// 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 composing actions for additional documentation.
repeated Action actions = 3;
// configuration. See :ref:`composing actions
// <config_http_filters_rate_limit_composing_actions>` for additional documentation.
repeated Action actions = 3 [(validate.rules).string.min_len = 1];
}
// .. attention::
@ -654,7 +713,8 @@ message VirtualHost {
// Specifies a list of HTTP headers that should be added to each request
// handled by this virtual host. Headers specified at this level are applied
// after headers from enclosed :ref:`envoy_api_msg_RouteAction` and before headers from the
// enclosing :ref:`envoy_api_msg_RouteConfiguration`.
// enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information see the documentation
// on :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
repeated HeaderValueOption request_headers_to_add = 7;
// Specifies a list of HTTP headers that should be added to each response
@ -705,7 +765,8 @@ message RouteConfiguration {
// Specifies a list of HTTP headers that should be added to each request
// routed by the HTTP connection manager. Headers specified at this level are
// applied after headers from any enclosed :ref:`envoy_api_msg_VirtualHost` or
// :ref:`envoy_api_msg_RouteAction`.
// :ref:`envoy_api_msg_RouteAction`. For more information see the documentation on
// :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
repeated HeaderValueOption request_headers_to_add = 6;
// An optional boolean that specifies whether the clusters that the route
@ -714,8 +775,10 @@ message RouteConfiguration {
// 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 route_config option. This setting default to
// false if the route table is loaded dynamically via the rds option. Users
// is statically defined via the :ref:`route_config
// <envoy_api_field_filter.network.HttpConnectionManager.route_config>` option. This setting
// default to false if the route table is loaded dynamically via the :ref:`rds
// <envoy_api_field_filter.network.HttpConnectionManager.rds>` option. Users
// may which to override the default behavior in certain cases (for example
// when using CDS with a static route table).
google.protobuf.BoolValue validate_clusters = 7;

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

@ -27,7 +27,7 @@ actions
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_conn_man_route_table_rate_limit_composing_actions>` for additional documentation.
<config_http_filters_rate_limit_composing_actions>` for additional documentation.
.. _config_http_conn_man_route_table_rate_limit_actions:
@ -181,75 +181,3 @@ The following descriptor entry is appended to the descriptor:
.. code-block:: cpp
("header_match", "<descriptor_value>")
.. _config_http_conn_man_route_table_rate_limit_composing_actions:
Composing Actions
-----------------
Each action 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")

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

@ -3,8 +3,8 @@
HTTP connection manager
=======================
* HTTP connection manager :ref:`architecture overview <arch_overview_http_conn_man>`.
* HTTP protocols :ref:`architecture overview <arch_overview_http_protocols>`.
* 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_filter.network.HttpConnectionManager>`

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

@ -1,7 +1,7 @@
.. _config_http_conn_man_rds:
Route discovery service
=======================
v1 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

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

@ -47,6 +47,84 @@ timeout_ms
*(optional, integer)* The timeout in milliseconds for the rate limit service RPC. If not set,
this defaults to 20ms.
.. _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
----------

7
tools/protodoc/protodoc.py
Unescape View File

@ -357,8 +357,11 @@ def FormatMessageAsJson(type_context, msg):
lines.append('"%s": %s' % (field.name,
FormatFieldTypeAsJson(type_context, field)))
return '.. code-block:: json\n\n {\n' + ',\n'.join(IndentLines(
4, lines)) + '\n }\n\n'
if lines:
return '.. code-block:: json\n\n {\n' + ',\n'.join(IndentLines(
4, lines)) + '\n }\n\n'
else:
return '.. code-block:: json\n\n {}\n\n'
def NormalizeFQN(fqn):

Write Preview
Loading…
Cancel
Save