api: populate secure edge defaults manifest. (envoyproxy#11364)

Adding API annotations and manifest entries to match https://www.envoyproxy.io/docs/envoy/latest/configuration/best_practices/edge#best-practices-edge.

Risk level: Low (API/docs only change)
Testing: Docs build and inspection.

Fixes envoyproxy#11085

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

api/envoy/config/cluster/v3/cluster.proto

@@ -19,6 +19,7 @@ import "google/protobuf/struct.proto";
 import "google/protobuf/wrappers.proto";
 
 import "envoy/annotations/deprecation.proto";
+import "udpa/annotations/security.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 import "validate/validate.proto";
@@ -584,7 +585,8 @@ message Cluster {
 
   // Soft limit on size of the cluster’s connections read and write buffers. If
   // unspecified, an implementation defined default is applied (1MiB).
-  google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5;
+  google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5
+      [(udpa.annotations.security).configure_for_untrusted_upstream = true];
 
   // The :ref:`load balancer type <arch_overview_load_balancing_types>` to use
   // when picking a host in the cluster.
@@ -635,7 +637,8 @@ message Cluster {
   // supports prior knowledge for upstream connections. Even if TLS is used
   // with ALPN, `http2_protocol_options` must be specified. As an aside this allows HTTP/2
   // connections to happen over plain text.
-  core.v3.Http2ProtocolOptions http2_protocol_options = 14;
+  core.v3.Http2ProtocolOptions http2_protocol_options = 14
+      [(udpa.annotations.security).configure_for_untrusted_upstream = true];
 
   // The extension_protocol_options field is used to provide extension-specific protocol options
   // for upstream connections. The key should match the extension filter name, such as

api/envoy/config/cluster/v4alpha/cluster.proto

@@ -19,6 +19,7 @@ import "google/protobuf/struct.proto";
 import "google/protobuf/wrappers.proto";
 
 import "envoy/annotations/deprecation.proto";
+import "udpa/annotations/security.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 import "validate/validate.proto";
@@ -585,7 +586,8 @@ message Cluster {
 
   // Soft limit on size of the cluster’s connections read and write buffers. If
   // unspecified, an implementation defined default is applied (1MiB).
-  google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5;
+  google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5
+      [(udpa.annotations.security).configure_for_untrusted_upstream = true];
 
   // The :ref:`load balancer type <arch_overview_load_balancing_types>` to use
   // when picking a host in the cluster.
@@ -636,7 +638,8 @@ message Cluster {
   // supports prior knowledge for upstream connections. Even if TLS is used
   // with ALPN, `http2_protocol_options` must be specified. As an aside this allows HTTP/2
   // connections to happen over plain text.
-  core.v4alpha.Http2ProtocolOptions http2_protocol_options = 14;
+  core.v4alpha.Http2ProtocolOptions http2_protocol_options = 14
+      [(udpa.annotations.security).configure_for_untrusted_upstream = true];
 
   // The extension_protocol_options field is used to provide extension-specific protocol options
   // for upstream connections. The key should match the extension filter name, such as

api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto

@@ -19,6 +19,7 @@ import "google/protobuf/struct.proto";
 import "google/protobuf/wrappers.proto";
 
 import "envoy/annotations/deprecation.proto";
+import "udpa/annotations/security.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 import "validate/validate.proto";
@@ -281,13 +282,15 @@ message HttpConnectionManager {
 
   // Additional settings for HTTP requests handled by the connection manager. These will be
   // applicable to both HTTP1 and HTTP2 requests.
-  config.core.v3.HttpProtocolOptions common_http_protocol_options = 35;
+  config.core.v3.HttpProtocolOptions common_http_protocol_options = 35
+      [(udpa.annotations.security).configure_for_untrusted_downstream = true];
 
   // Additional HTTP/1 settings that are passed to the HTTP/1 codec.
   config.core.v3.Http1ProtocolOptions http_protocol_options = 8;
 
   // Additional HTTP/2 settings that are passed directly to the HTTP/2 codec.
-  config.core.v3.Http2ProtocolOptions http2_protocol_options = 9;
+  config.core.v3.Http2ProtocolOptions http2_protocol_options = 9
+      [(udpa.annotations.security).configure_for_untrusted_downstream = true];
 
   // An optional override that the connection manager will write to the server
   // header in responses. If not set, the default is *envoy*.
@@ -332,13 +335,15 @@ message HttpConnectionManager {
   //
   // A value of 0 will completely disable the connection manager stream idle
   // timeout, although per-route idle timeout overrides will continue to apply.
-  google.protobuf.Duration stream_idle_timeout = 24;
+  google.protobuf.Duration stream_idle_timeout = 24
+      [(udpa.annotations.security).configure_for_untrusted_downstream = true];
 
   // The amount of time that Envoy will wait for the entire request to be received.
   // The timer is activated when the request is initiated, and is disarmed when the last byte of the
   // request is sent upstream (i.e. all decoding filters have processed the request), OR when the
   // response is initiated. If not specified or set to 0, this timeout is disabled.
-  google.protobuf.Duration request_timeout = 28;
+  google.protobuf.Duration request_timeout = 28
+      [(udpa.annotations.security).configure_for_untrusted_downstream = true];
 
   // The time that Envoy will wait between sending an HTTP/2 “shutdown
   // notification” (GOAWAY frame with max stream ID) and a final GOAWAY frame.
@@ -394,7 +399,8 @@ message HttpConnectionManager {
   // :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.
-  google.protobuf.BoolValue use_remote_address = 14;
+  google.protobuf.BoolValue use_remote_address = 14
+      [(udpa.annotations.security).configure_for_untrusted_downstream = true];
 
   // The number of additional ingress proxy hops from the right side of the
   // :ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header to trust when

api/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto

@@ -19,6 +19,7 @@ import "google/protobuf/struct.proto";
 import "google/protobuf/wrappers.proto";
 
 import "envoy/annotations/deprecation.proto";
+import "udpa/annotations/security.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 import "validate/validate.proto";
@@ -281,13 +282,15 @@ message HttpConnectionManager {
 
   // Additional settings for HTTP requests handled by the connection manager. These will be
   // applicable to both HTTP1 and HTTP2 requests.
-  config.core.v4alpha.HttpProtocolOptions common_http_protocol_options = 35;
+  config.core.v4alpha.HttpProtocolOptions common_http_protocol_options = 35
+      [(udpa.annotations.security).configure_for_untrusted_downstream = true];
 
   // Additional HTTP/1 settings that are passed to the HTTP/1 codec.
   config.core.v4alpha.Http1ProtocolOptions http_protocol_options = 8;
 
   // Additional HTTP/2 settings that are passed directly to the HTTP/2 codec.
-  config.core.v4alpha.Http2ProtocolOptions http2_protocol_options = 9;
+  config.core.v4alpha.Http2ProtocolOptions http2_protocol_options = 9
+      [(udpa.annotations.security).configure_for_untrusted_downstream = true];
 
   // An optional override that the connection manager will write to the server
   // header in responses. If not set, the default is *envoy*.
@@ -332,13 +335,15 @@ message HttpConnectionManager {
   //
   // A value of 0 will completely disable the connection manager stream idle
   // timeout, although per-route idle timeout overrides will continue to apply.
-  google.protobuf.Duration stream_idle_timeout = 24;
+  google.protobuf.Duration stream_idle_timeout = 24
+      [(udpa.annotations.security).configure_for_untrusted_downstream = true];
 
   // The amount of time that Envoy will wait for the entire request to be received.
   // The timer is activated when the request is initiated, and is disarmed when the last byte of the
   // request is sent upstream (i.e. all decoding filters have processed the request), OR when the
   // response is initiated. If not specified or set to 0, this timeout is disabled.
-  google.protobuf.Duration request_timeout = 28;
+  google.protobuf.Duration request_timeout = 28
+      [(udpa.annotations.security).configure_for_untrusted_downstream = true];
 
   // The time that Envoy will wait between sending an HTTP/2 “shutdown
   // notification” (GOAWAY frame with max stream ID) and a final GOAWAY frame.
@@ -394,7 +399,8 @@ message HttpConnectionManager {
   // :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.
-  google.protobuf.BoolValue use_remote_address = 14;
+  google.protobuf.BoolValue use_remote_address = 14
+      [(udpa.annotations.security).configure_for_untrusted_downstream = true];
 
   // The number of additional ingress proxy hops from the right side of the
   // :ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header to trust when

docs/BUILD

@@ -1,3 +1,3 @@
 licenses(["notice"])  # Apache 2
 
-exports_files(["edge_defaults_manifest.yaml"])
+exports_files(["protodoc_manifest.yaml"])

docs/protodoc_manifest.yaml

@@ -0,0 +1,51 @@
+fields:
+  envoy.config.bootstrap.v3.Bootstrap.overload_manager:
+    edge_config:
+      example:
+        refresh_interval: 0.25s
+        resource_monitors:
+        - name: "envoy.resource_monitors.fixed_heap"
+          typed_config:
+            "@type": type.googleapis.com/envoy.config.resource_monitor.fixed_heap.v2alpha.FixedHeapConfig
+            max_heap_size_bytes: 1073741824
+        actions:
+        - name: "envoy.overload_actions.shrink_heap"
+          triggers:
+          - name: "envoy.resource_monitors.fixed_heap"
+            threshold:
+              value: 0.90
+        - name: "envoy.overload_actions.stop_accepting_requests"
+          triggers:
+          - name: "envoy.resource_monitors.fixed_heap"
+            threshold:
+              value: 0.95
+  envoy.config.cluster.v3.Cluster.per_connection_buffer_limit_bytes:
+    edge_config: { example: 32768 }
+  envoy.config.cluster.v3.Cluster.http2_protocol_options:
+    edge_config:
+      example:
+        initial_stream_window_size: 65536 # 64 KiB
+        initial_connection_window_size: 1048576 # 1 MiB
+  envoy.config.listener.v3.Listener.per_connection_buffer_limit_bytes:
+    edge_config: { example: 32768 }
+  envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.common_http_protocol_options:
+    edge_config:
+      example:
+        idle_timeout: 900s # 15 mins
+        headers_with_underscores_action: REJECT_REQUEST
+  envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.http2_protocol_options:
+    edge_config:
+      example:
+        max_concurrent_streams: 100
+        initial_stream_window_size: 65536 # 64 KiB
+        initial_connection_window_size: 1048576 # 1 MiB
+  envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stream_idle_timeout:
+    edge_config:
+      example: 300s # 5 mins
+  envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.request_timeout:
+    edge_config:
+      note: >
+        This timeout is not compatible with streaming requests.
+      example: 300s # 5 mins
+  envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.use_remote_address:
+    edge_config: { example: true }