upstreams: APIs, docs, and stubs for pluggable upstreams (#11554)

split out from #11327

There's a bit of transitive ugliness: declaring the extensions requires security posture, requires stub build files, requires codeowners before the code move, but it'll be pretty short lived.

Risk Level: Low (mostly only APIs)
Testing: n/a
Docs Changes: some of the new docs
Release Notes: n/a

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

Mirrored from https://github.com/envoyproxy/envoy @ e8dc25ecec277c0b94d02151de79353a9ba07b4e

BUILD

@@ -233,6 +233,9 @@ proto_library(
         "//envoy/extensions/transport_sockets/raw_buffer/v3:pkg",
         "//envoy/extensions/transport_sockets/tap/v3:pkg",
         "//envoy/extensions/transport_sockets/tls/v3:pkg",
+        "//envoy/extensions/upstreams/http/generic/v3:pkg",
+        "//envoy/extensions/upstreams/http/http/v3:pkg",
+        "//envoy/extensions/upstreams/http/tcp/v3:pkg",
         "//envoy/extensions/wasm/v3:pkg",
         "//envoy/service/accesslog/v3:pkg",
         "//envoy/service/auth/v3:pkg",

envoy/config/cluster/v3/cluster.proto

@@ -8,6 +8,7 @@ import "envoy/config/cluster/v3/outlier_detection.proto";
 import "envoy/config/core/v3/address.proto";
 import "envoy/config/core/v3/base.proto";
 import "envoy/config/core/v3/config_source.proto";
+import "envoy/config/core/v3/extension.proto";
 import "envoy/config/core/v3/health_check.proto";
 import "envoy/config/core/v3/protocol.proto";
 import "envoy/config/endpoint/v3/endpoint.proto";
@@ -32,7 +33,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // [#protodoc-title: Cluster configuration]
 
 // Configuration for a single upstream cluster.
-// [#next-free-field: 48]
+// [#next-free-field: 49]
 message Cluster {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster";
 
@@ -816,6 +817,26 @@ message Cluster {
   // of 0 would indicate that none of the timeout was used or that the timeout was infinite. A value
   // of 100 would indicate that the request took the entirety of the timeout given to it.
   bool track_timeout_budgets = 47;
+
+  // [#not-implemented-hide:]
+  // Optional customization and configuration of upstream connection pool, and upstream type.
+  //
+  // Currently this field only applies for HTTP traffic but is designed for eventual use for custom
+  // TCP upstreams.
+  //
+  // For HTTP traffic, Envoy will generally take downstream HTTP and send it upstream as upstream
+  // HTTP, using the http connection pool and the codec from `http2_protocol_options`
+  //
+  // For routes where CONNECT termination is configured, Envoy will take downstream CONNECT
+  // requests and forward the CONNECT payload upstream over raw TCP using the tcp connection pool.
+  //
+  // The default pool used is the generic connection pool which creates the HTTP upstream for most
+  // HTTP requests, and the TCP upstream if CONNECT termination is configured.
+  //
+  // If users desire custom connection pool or upstream behavior, for example terminating
+  // CONNECT only if a custom filter indicates it is appropriate, the custom factories
+  // can be registered and configured here.
+  core.v3.TypedExtensionConfig upstream_config = 48;
 }
 
 // [#not-implemented-hide:] Extensible load balancing policy configuration.

envoy/config/cluster/v4alpha/cluster.proto

@@ -8,6 +8,7 @@ import "envoy/config/cluster/v4alpha/outlier_detection.proto";
 import "envoy/config/core/v4alpha/address.proto";
 import "envoy/config/core/v4alpha/base.proto";
 import "envoy/config/core/v4alpha/config_source.proto";
+import "envoy/config/core/v4alpha/extension.proto";
 import "envoy/config/core/v4alpha/health_check.proto";
 import "envoy/config/core/v4alpha/protocol.proto";
 import "envoy/config/endpoint/v3/endpoint.proto";
@@ -32,7 +33,7 @@ option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSIO
 // [#protodoc-title: Cluster configuration]
 
 // Configuration for a single upstream cluster.
-// [#next-free-field: 48]
+// [#next-free-field: 49]
 message Cluster {
   option (udpa.annotations.versioning).previous_message_type = "envoy.config.cluster.v3.Cluster";
 
@@ -817,6 +818,26 @@ message Cluster {
   // of 0 would indicate that none of the timeout was used or that the timeout was infinite. A value
   // of 100 would indicate that the request took the entirety of the timeout given to it.
   bool track_timeout_budgets = 47;
+
+  // [#not-implemented-hide:]
+  // Optional customization and configuration of upstream connection pool, and upstream type.
+  //
+  // Currently this field only applies for HTTP traffic but is designed for eventual use for custom
+  // TCP upstreams.
+  //
+  // For HTTP traffic, Envoy will generally take downstream HTTP and send it upstream as upstream
+  // HTTP, using the http connection pool and the codec from `http2_protocol_options`
+  //
+  // For routes where CONNECT termination is configured, Envoy will take downstream CONNECT
+  // requests and forward the CONNECT payload upstream over raw TCP using the tcp connection pool.
+  //
+  // The default pool used is the generic connection pool which creates the HTTP upstream for most
+  // HTTP requests, and the TCP upstream if CONNECT termination is configured.
+  //
+  // If users desire custom connection pool or upstream behavior, for example terminating
+  // CONNECT only if a custom filter indicates it is appropriate, the custom factories
+  // can be registered and configured here.
+  core.v4alpha.TypedExtensionConfig upstream_config = 48;
 }
 
 // [#not-implemented-hide:] Extensible load balancing policy configuration.

envoy/extensions/upstreams/http/generic/v3/BUILD

@@ -0,0 +1,9 @@
+# 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 = ["@com_github_cncf_udpa//udpa/annotations:pkg"],
+)

envoy/extensions/upstreams/http/generic/v3/generic_connection_pool.proto

@@ -0,0 +1,18 @@
+syntax = "proto3";
+
+package envoy.extensions.upstreams.http.generic.v3;
+
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.upstreams.http.generic.v3";
+option java_outer_classname = "GenericConnectionPoolProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Generic Connection Pool]
+
+// A connection pool which forwards downstream HTTP as TCP or HTTP to upstream,
+// based on CONNECT configuration.
+// [#extension: envoy.upstreams.http.generic]
+message GenericConnectionPoolProto {
+}

envoy/extensions/upstreams/http/http/v3/BUILD

@@ -0,0 +1,9 @@
+# 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 = ["@com_github_cncf_udpa//udpa/annotations:pkg"],
+)

envoy/extensions/upstreams/http/http/v3/http_connection_pool.proto

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package envoy.extensions.upstreams.http.http.v3;
+
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.upstreams.http.http.v3";
+option java_outer_classname = "HttpConnectionPoolProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Http Connection Pool]
+
+// A connection pool which forwards downstream HTTP as HTTP to upstream.
+// [#extension: envoy.upstreams.http.http]
+message HttpConnectionPoolProto {
+}

envoy/extensions/upstreams/http/tcp/v3/BUILD

@@ -0,0 +1,9 @@
+# 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 = ["@com_github_cncf_udpa//udpa/annotations:pkg"],
+)

envoy/extensions/upstreams/http/tcp/v3/tcp_connection_pool.proto

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package envoy.extensions.upstreams.http.tcp.v3;
+
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.upstreams.http.tcp.v3";
+option java_outer_classname = "TcpConnectionPoolProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Tcp Connection Pool]
+
+// A connection pool which forwards downstream HTTP as TCP to upstream,
+// [#extension: envoy.upstreams.http.tcp]
+message TcpConnectionPoolProto {
+}

versioning/BUILD

@@ -116,6 +116,9 @@ proto_library(
         "//envoy/extensions/transport_sockets/raw_buffer/v3:pkg",
         "//envoy/extensions/transport_sockets/tap/v3:pkg",
         "//envoy/extensions/transport_sockets/tls/v3:pkg",
+        "//envoy/extensions/upstreams/http/generic/v3:pkg",
+        "//envoy/extensions/upstreams/http/http/v3:pkg",
+        "//envoy/extensions/upstreams/http/tcp/v3:pkg",
         "//envoy/extensions/wasm/v3:pkg",
         "//envoy/service/accesslog/v3:pkg",
         "//envoy/service/auth/v3:pkg",