rate limit: add local rate limit network filter

CODEOWNERS

@@ -92,3 +92,4 @@ extensions/filters/common/original_src @snowp @klarose
 /*/extensions/filters/network/echo @htuch @alyssawilk
 /*/extensions/filters/udp/udp_proxy @mattklein123 @danzh2010
 /*/extensions/clusters/aggregate @yxue @snowp
+/*/extensions/filters/network/local_ratelimit @mattklein123 @junr03

api/docs/BUILD

@@ -57,6 +57,7 @@ proto_library(
         "//envoy/config/filter/network/dubbo_proxy/v2alpha1:pkg",
         "//envoy/config/filter/network/ext_authz/v2:pkg",
         "//envoy/config/filter/network/http_connection_manager/v2:pkg",
+        "//envoy/config/filter/network/local_rate_limit/v2alpha:pkg",
         "//envoy/config/filter/network/mongo_proxy/v2:pkg",
         "//envoy/config/filter/network/mysql_proxy/v1alpha1:pkg",
         "//envoy/config/filter/network/rate_limit/v2:pkg",

api/envoy/api/v2/route/route.proto

@@ -1171,7 +1171,7 @@ message VirtualCluster {
   core.RequestMethod method = 3 [deprecated = true];
 }
 
-// Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`.
+// Global rate limiting :ref:`architecture overview <arch_overview_global_rate_limit>`.
 message RateLimit {
   // [#next-free-field: 7]
   message Action {

api/envoy/api/v3alpha/route/route.proto

@@ -1165,7 +1165,7 @@ message VirtualCluster {
   string name = 2 [(validate.rules).string = {min_bytes: 1}];
 }
 
-// Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`.
+// Global rate limiting :ref:`architecture overview <arch_overview_global_rate_limit>`.
 message RateLimit {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit";
 

api/envoy/config/filter/network/local_rate_limit/v2alpha/BUILD

@@ -0,0 +1,12 @@
+# DO NOT EDIT. This file is generated by tools/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = [
+        "//envoy/api/v2/core:pkg",
+        "//envoy/type:pkg",
+    ],
+)

api/envoy/config/filter/network/local_rate_limit/v2alpha/local_rate_limit.proto

@@ -0,0 +1,31 @@
+syntax = "proto3";
+
+package envoy.config.filter.network.local_rate_limit.v2alpha;
+
+option java_package = "io.envoyproxy.envoy.config.filter.network.local_rate_limit.v2alpha";
+option java_outer_classname = "LocalRateLimitProto";
+option java_multiple_files = true;
+
+import "envoy/api/v2/core/base.proto";
+import "envoy/type/token_bucket.proto";
+
+import "validate/validate.proto";
+
+// [#protodoc-title: Local rate limit]
+// Local rate limit :ref:`configuration overview <config_network_filters_local_rate_limit>`.
+// [#extension: envoy.filters.network.local_ratelimit]
+
+message LocalRateLimit {
+  // The prefix to use when emitting :ref:`statistics
+  // <config_network_filters_local_rate_limit_stats>`.
+  string stat_prefix = 1 [(validate.rules).string = {min_bytes: 1}];
+
+  // The token bucket configuration to use for rate limiting connections. Each incoming connection
+  // consumes a single token. If the token is available, the connection will be allowed. If no
+  // tokens are available, the connection will be immediately closed.
+  type.TokenBucket token_bucket = 2 [(validate.rules).message = {required: true}];
+
+  // Runtime flag that controls whether the filter is enabled or not. If not specified, defaults
+  // to enabled.
+  api.v2.core.RuntimeFeatureFlag enabled = 3;
+}

api/envoy/config/filter/network/local_rate_limit/v3alpha/BUILD

@@ -0,0 +1,14 @@
+# DO NOT EDIT. This file is generated by tools/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = [
+        "//envoy/api/v3alpha/core:pkg",
+        "//envoy/config/filter/network/local_rate_limit/v2alpha:pkg",
+        "//envoy/type/v3alpha:pkg",
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+    ],
+)

api/envoy/config/filter/network/local_rate_limit/v3alpha/local_rate_limit.proto

@@ -0,0 +1,36 @@
+syntax = "proto3";
+
+package envoy.config.filter.network.local_rate_limit.v3alpha;
+
+option java_package = "io.envoyproxy.envoy.config.filter.network.local_rate_limit.v3alpha";
+option java_outer_classname = "LocalRateLimitProto";
+option java_multiple_files = true;
+
+import "envoy/api/v3alpha/core/base.proto";
+import "envoy/type/v3alpha/token_bucket.proto";
+
+import "udpa/annotations/versioning.proto";
+
+import "validate/validate.proto";
+
+// [#protodoc-title: Local rate limit]
+// Local rate limit :ref:`configuration overview <config_network_filters_local_rate_limit>`.
+// [#extension: envoy.filters.network.local_ratelimit]
+
+message LocalRateLimit {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.config.filter.network.local_rate_limit.v2alpha.LocalRateLimit";
+
+  // The prefix to use when emitting :ref:`statistics
+  // <config_network_filters_local_rate_limit_stats>`.
+  string stat_prefix = 1 [(validate.rules).string = {min_bytes: 1}];
+
+  // The token bucket configuration to use for rate limiting connections. Each incoming connection
+  // consumes a single token. If the token is available, the connection will be allowed. If no
+  // tokens are available, the connection will be immediately closed.
+  type.v3alpha.TokenBucket token_bucket = 2 [(validate.rules).message = {required: true}];
+
+  // Runtime flag that controls whether the filter is enabled or not. If not specified, defaults
+  // to enabled.
+  api.v3alpha.core.RuntimeFeatureFlag enabled = 3;
+}

api/envoy/type/token_bucket.proto

@@ -0,0 +1,33 @@
+syntax = "proto3";
+
+package envoy.type;
+
+option java_package = "io.envoyproxy.envoy.type";
+option java_outer_classname = "TokenBucketProto";
+option java_multiple_files = true;
+
+import "google/protobuf/duration.proto";
+import "google/protobuf/wrappers.proto";
+
+import "validate/validate.proto";
+
+// [#protodoc-title: Token bucket]
+
+// Configures a token bucket, typically used for rate limiting.
+message TokenBucket {
+  // The maximum tokens that the bucket can hold. This is also the number of tokens that the bucket
+  // initially contains.
+  uint32 max_tokens = 1 [(validate.rules).uint32 = {gt: 0}];
+
+  // The number of tokens added to the bucket during each fill interval. If not specified, defaults
+  // to a single token.
+  google.protobuf.UInt32Value tokens_per_fill = 2 [(validate.rules).uint32 = {gt: 0}];
+
+  // The fill interval that tokens are added to the bucket. Must be greater than 50ms. During
+  // each fill interval `tokens_per_fill` are added to the bucket. The bucket will never contain
+  // more than `max_tokens` tokens.
+  google.protobuf.Duration fill_interval = 3 [(validate.rules).duration = {
+    required: true
+    gt {nanos: 50000000}
+  }];
+}

api/envoy/type/v3alpha/token_bucket.proto

@@ -0,0 +1,37 @@
+syntax = "proto3";
+
+package envoy.type.v3alpha;
+
+option java_package = "io.envoyproxy.envoy.type.v3alpha";
+option java_outer_classname = "TokenBucketProto";
+option java_multiple_files = true;
+
+import "google/protobuf/duration.proto";
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/versioning.proto";
+
+import "validate/validate.proto";
+
+// [#protodoc-title: Token bucket]
+
+// Configures a token bucket, typically used for rate limiting.
+message TokenBucket {
+  option (udpa.annotations.versioning).previous_message_type = "envoy.type.TokenBucket";
+
+  // The maximum tokens that the bucket can hold. This is also the number of tokens that the bucket
+  // initially contains.
+  uint32 max_tokens = 1 [(validate.rules).uint32 = {gt: 0}];
+
+  // The number of tokens added to the bucket during each fill interval. If not specified, defaults
+  // to a single token.
+  google.protobuf.UInt32Value tokens_per_fill = 2 [(validate.rules).uint32 = {gt: 0}];
+
+  // The fill interval that tokens are added to the bucket. Must be greater than 50ms. During
+  // each fill interval `tokens_per_fill` are added to the bucket. The bucket will never contain
+  // more than `max_tokens` tokens.
+  google.protobuf.Duration fill_interval = 3 [(validate.rules).duration = {
+    required: true
+    gt {nanos: 50000000}
+  }];
+}

docs/root/api-v2/config/filter/network/network.rst

@@ -8,4 +8,5 @@ Network filters
   */empty/*
   */v1alpha1/*
   */v2/*
+  */v2alpha/*
   */v2alpha1/*

docs/root/api-v2/types/types.rst

@@ -10,6 +10,7 @@ Types
   ../type/http_status.proto
   ../type/percent.proto
   ../type/range.proto
+  ../type/token_bucket.proto
   ../type/matcher/metadata.proto
   ../type/matcher/number.proto
   ../type/matcher/regex.proto

docs/root/configuration/http/http_filters/rate_limit_filter.rst

@@ -3,7 +3,7 @@
 Rate limit
 ==========
 
-* Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`
+* Global rate limiting :ref:`architecture overview <arch_overview_global_rate_limit>`
 * :ref:`v2 API reference <envoy_api_msg_config.filter.http.rate_limit.v2.RateLimit>`
 * This filter should be configured with the name *envoy.rate_limit*.
 

docs/root/configuration/listeners/network_filters/local_rate_limit_filter.rst

@@ -0,0 +1,38 @@
+.. _config_network_filters_local_rate_limit:
+
+Local rate limit
+================
+
+* Local rate limiting :ref:`architecture overview <arch_overview_local_rate_limit>`
+* :ref:`v2 API reference
+  <envoy_api_msg_config.filter.network.local_rate_limit.v2alpha.LocalRateLimit>`
+* This filter should be configured with the name *envoy.filters.network.local_ratelimit*.
+
+Overview
+--------
+
+The local rate limit filter applies a :ref:`token bucket
+<envoy_api_field_config.filter.network.local_rate_limit.v2alpha.LocalRateLimit.token_bucket>` rate
+limit to incoming connections. Each connection utilizes a single token, and if no tokens are
+available, the connection will be immediately closed without further filter iteration.
+
+.. _config_network_filters_local_rate_limit_stats:
+
+Statistics
+----------
+
+Every configured local rate limit filter has statistics rooted at *local_ratelimit.<stat_prefix>.*
+with the following statistics:
+
+.. csv-table::
+  :header: Name, Type, Description
+  :widths: 1, 1, 2
+
+  rate_limit, Counter, Total connections that have been closed due to rate limit exceeded
+
+Runtime
+-------
+
+The local rate limit filter can be runtime feature flagged via the :ref:`enabled
+<envoy_api_field_config.filter.network.local_rate_limit.v2alpha.LocalRateLimit.enabled>`
+configuration field.

docs/root/configuration/listeners/network_filters/network_filters.rst

@@ -14,6 +14,7 @@ filters.
   client_ssl_auth_filter
   echo_filter
   ext_authz_filter
+  local_rate_limit_filter
   mongo_proxy_filter
   mysql_proxy_filter
   rate_limit_filter

docs/root/configuration/listeners/network_filters/rate_limit_filter.rst

@@ -3,7 +3,7 @@
 Rate limit
 ==========
 
-* Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`
+* Global rate limiting :ref:`architecture overview <arch_overview_global_rate_limit>`
 * :ref:`v2 API reference <envoy_api_msg_config.filter.network.rate_limit.v2.RateLimit>`
 * This filter should be configured with the name *envoy.ratelimit*.
 

docs/root/configuration/other_features/rate_limit.rst

@@ -3,7 +3,7 @@
 Rate limit service
 ==================
 
-The :ref:`rate limit service <arch_overview_rate_limit>` configuration specifies the global rate
+The :ref:`rate limit service <arch_overview_global_rate_limit>` configuration specifies the global rate
 limit service Envoy should talk to when it needs to make global rate limit decisions. If no rate
 limit service is configured, a "null" service will be used which will always return OK if called.
 

docs/root/configuration/other_protocols/thrift_filters/rate_limit_filter.rst

@@ -3,7 +3,7 @@
 Rate limit
 ==========
 
-* Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`
+* Global rate limiting :ref:`architecture overview <arch_overview_global_rate_limit>`
 * :ref:`v2 API reference <envoy_api_msg_config.filter.thrift.rate_limit.v2alpha1.RateLimit>`
 * This filter should be configured with the name *envoy.filters.thrift.rate_limit*.
 

docs/root/faq/load_balancing/transient_failures.rst

@@ -38,7 +38,7 @@ The following application status codes in gRPC are considered safe for automatic
 
 * *CANCELLED* - Return this code if there is an error that can be retried in the service.
 * *RESOURCE_EXHAUSTED* - Return this code if some of the resources that service depends on are exhausted in that instance so that retrying 
-  to another instance would help. Please note that for shared resource exhaustion, returning this will not help. Instead :ref:`rate limiting <arch_overview_rate_limit>`
+  to another instance would help. Please note that for shared resource exhaustion, returning this will not help. Instead :ref:`rate limiting <arch_overview_global_rate_limit>`
   should be used to handle such cases.
 
 The HTTP Status codes *502 (Bad Gateway)*, *503 (Service Unavailable)* and *504 (Gateway Timeout)* are all mapped to gRPC status code *UNAVAILABLE*. 

docs/root/install/ref_configs.rst

@@ -50,7 +50,7 @@ A few notes about the example configurations:
   disable this or enable `Zipkin <https://zipkin.io>`_ or `Datadog <https://datadoghq.com>`_ tracing, delete or
   change the :ref:`tracing configuration <envoy_api_file_envoy/config/trace/v2/trace.proto>` accordingly.
 * The configuration demonstrates the use of a :ref:`global rate limiting service
-  <arch_overview_rate_limit>`. To disable this delete the :ref:`rate limit configuration
+  <arch_overview_global_rate_limit>`. To disable this delete the :ref:`rate limit configuration
   <config_rate_limit_service>`.
 * :ref:`Route discovery service <config_http_conn_man_rds>` is configured for the service to service
   reference configuration and it is assumed to be running at `rds.yourcompany.net`.

docs/root/intro/arch_overview/listeners/listener_filters.rst

@@ -11,6 +11,6 @@ and also make interaction between multiple such features more explicit.
 The API for listener filters is relatively simple since ultimately these filters operate on newly
 accepted sockets. Filters in the chain can stop and subsequently continue iteration to
 further filters. This allows for more complex scenarios such as calling a :ref:`rate limiting
-service <arch_overview_rate_limit>`, etc. Envoy already includes several listener filters that
+service <arch_overview_global_rate_limit>`, etc. Envoy already includes several listener filters that
 are documented in this architecture overview as well as the :ref:`configuration reference
 <config_listener_filters>`.

docs/root/intro/arch_overview/listeners/listeners.rst

@@ -18,7 +18,7 @@ composed of one or more network level (L3/L4) :ref:`filters <arch_overview_netwo
 a new connection is received on a listener, the appropriate filter chain is selected, and the
 configured connection local filter stack is instantiated and begins processing subsequent events.
 The generic listener architecture is used to perform the vast majority of different proxy tasks that
-Envoy is used for (e.g., :ref:`rate limiting <arch_overview_rate_limit>`, :ref:`TLS client
+Envoy is used for (e.g., :ref:`rate limiting <arch_overview_global_rate_limit>`, :ref:`TLS client
 authentication <arch_overview_ssl_auth_filter>`, :ref:`HTTP connection management
 <arch_overview_http_conn_man>`, MongoDB :ref:`sniffing <arch_overview_mongo>`, raw :ref:`TCP proxy
 <arch_overview_tcp_proxy>`, etc.).

docs/root/intro/arch_overview/listeners/network_filters.rst

@@ -17,7 +17,7 @@ The API for network level filters is relatively simple since ultimately the filt
 bytes and a small number of connection events (e.g., TLS handshake complete, connection disconnected
 locally or remotely, etc.). Filters in the chain can stop and subsequently continue iteration to
 further filters. This allows for more complex scenarios such as calling a :ref:`rate limiting
-service <arch_overview_rate_limit>`, etc. Network level filters can also share state (static and
+service <arch_overview_global_rate_limit>`, etc. Network level filters can also share state (static and
 dynamic) among themselves within the context of a single downstream connection. Refer to
 :ref:`data sharing between filters <arch_overview_data_sharing_between_filters>` for more details.
 Envoy already includes several network level filters that are documented in this architecture

docs/root/intro/arch_overview/other_features/global_rate_limiting.rst

@@ -1,4 +1,4 @@
-.. _arch_overview_rate_limit:
+.. _arch_overview_global_rate_limit:
 
 Global rate limiting
 ====================
@@ -29,3 +29,7 @@ written in Go which uses a Redis backend. Envoy’s rate limit integration has t
   :ref:`Configuration reference <config_http_filters_rate_limit>`
 
 Rate limit service :ref:`configuration <config_rate_limit_service>`.
+
+Note that Envoy also supports :ref:`local rate limiting <config_network_filters_local_rate_limit>`.
+Local rate limiting can be used in conjunction with global rate limiting to reduce load on the
+global rate limit service.

docs/root/intro/arch_overview/other_features/local_rate_limiting.rst

@@ -0,0 +1,11 @@
+.. _arch_overview_local_rate_limit:
+
+Local rate limiting
+===================
+
+Envoy supports local (non-distributed) rate limiting of L4 connections via the
+:ref:`local rate limit filter <config_network_filters_local_rate_limit>`.
+
+Note that Envoy also supports :ref:`global rate limiting <arch_overview_global_rate_limit>`. Local
+rate limiting can be used in conjunction with global rate limiting to reduce load on the global
+rate limit service.

docs/root/intro/arch_overview/other_features/other_features.rst

@@ -4,6 +4,7 @@ Other features
 .. toctree::
   :maxdepth: 2
 
+  local_rate_limiting
   global_rate_limiting
   scripting
   ip_transparency