ip tagging filter: update proto and add documentation (#506)
Updates the L7 IP tagging filter proto, v1 configuration documentation and overview documentation. Signed-off-by: Constance Caramanolis <ccaramanolis@lyft.com>pull/516/head
Constance Caramanolis
7 years ago
committed by
htuch
parent
2900f81223
commit
60dc08ddbc
10 changed files with 129 additions and 16 deletions
@ -0,0 +1,52 @@ |
||||
.. _config_http_filters_ip_tagging_v1: |
||||
|
||||
HTTP IP Tagging Filter |
||||
====================== |
||||
|
||||
HTTP IP Tagging :ref:`configuration overview <config_http_filters_ip_tagging>`. |
||||
|
||||
.. code-block:: json |
||||
|
||||
{ |
||||
"name": "ip_tagging", |
||||
"config": { |
||||
"request_type": "...", |
||||
"ip_tags": [] |
||||
} |
||||
} |
||||
|
||||
request_type |
||||
*(optional, string)* The type of requests the filter should apply to. The supported |
||||
types are *INTERNAL*, *EXTERNAL* or *BOTH*. The |
||||
:ref:`x-forwarded-for<config_http_conn_man_headers_x-forwarded-for_internal_origin>` header is |
||||
used to determine if a request is internal and will result in |
||||
:ref:`x-envoy-internal<config_http_conn_man_headers_x-envoy-internal>` |
||||
being set. The filter defaults to both, and it will apply to all request types. |
||||
|
||||
ip_tags |
||||
*(required, array)* A list of tags and the associated IP addresses subnets. |
||||
|
||||
IP Tags |
||||
------- |
||||
|
||||
.. code-block:: json |
||||
|
||||
{ |
||||
"ip_tag_name": {}, |
||||
"ip_list": [] |
||||
} |
||||
|
||||
ip_tag_name |
||||
*(required, string)* Specifies the IP tag name to apply to a request. |
||||
|
||||
ip_list |
||||
*(required, array)* A list of IP address subnets in the form "ip_address/xx". |
||||
|
||||
.. code-block:: json |
||||
|
||||
[ |
||||
"10.15.0.0/16", |
||||
"2001:db8::/32" |
||||
] |
||||
|
||||
|
||||
@ -0,0 +1,42 @@ |
||||
.. _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:`v1 API reference <config_http_filters_ip_tagging_v1>` |
||||
* :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. |
||||
@ -1,37 +1,47 @@ |
||||
syntax = "proto3"; |
||||
|
||||
// [#proto-status: experimental] |
||||
|
||||
package envoy.config.filter.http.ip_tagging.v2; |
||||
option go_package = "v2"; |
||||
|
||||
import "envoy/api/v2/core/address.proto"; |
||||
|
||||
// This is an HTTP filter which enables Envoy to tag requests with extra |
||||
// information such as location, cloud source, and any extra data. This is |
||||
// useful to prevent against DDoS. |
||||
import "google/protobuf/wrappers.proto"; |
||||
|
||||
import "validate/validate.proto"; |
||||
|
||||
message IPTagging { |
||||
|
||||
// The type of requests the filter should apply to. The supported types |
||||
// are internal, external or both. The |
||||
// :ref:`x-forwarded-for<config_http_conn_man_headers_x-forwarded-for_internal_origin>` header is |
||||
// used to determine if a request is internal and will result in |
||||
// :ref:`x-envoy-internal<config_http_conn_man_headers_x-envoy-internal>` |
||||
// being set. The filter defaults to both, and it will apply to all request types. |
||||
enum RequestType { |
||||
// Both external and internal requests will be tagged. This is the default value. |
||||
BOTH = 0; |
||||
|
||||
// Only internal requests will be tagged. |
||||
INTERNAL = 1; |
||||
|
||||
// Only external requests will be tagged. |
||||
EXTERNAL = 2; |
||||
} |
||||
|
||||
// The type of requests the filter should apply to. The supported types |
||||
// are internal, external or both. A request is considered internal if |
||||
// x-envoy-internal is set to true. If 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. |
||||
RequestType request_type = 1; |
||||
|
||||
repeated IPTag ip_tags = 2; |
||||
// The type of request the filter should apply to. |
||||
RequestType request_type = 1 [(validate.rules).enum.defined_only = true]; |
||||
|
||||
// Supplies the IP tag name and the IP address subnets. |
||||
message IPTag { |
||||
// Specifies the ip tag name to apply. |
||||
// Specifies the IP tag name to apply. |
||||
string ip_tag_name = 1; |
||||
|
||||
// A list of IP address and subnet masks that will be tagged with the |
||||
// ip_tag_name. Both IPv4 and IPv6 CIDR addresses are allowed here. |
||||
// A list of IP address subnets that will be tagged with |
||||
// ip_tag_name. Both IPv4 and IPv6 are supported. |
||||
repeated envoy.api.v2.core.CidrRange ip_list = 2; |
||||
} |
||||
|
||||
// [#comment:TODO(ccaraman): Extend functionality to load IP tags from file system.] |
||||
// The set of IP tags for the filter. |
||||
repeated IPTag ip_tags = 4 [(validate.rules).repeated .min_items = 1]; |
||||
} |
||||
|
||||
Loading…
Reference in new issue