upstreams: APIs, docs, and stubs for pluggable upstreams

CODEOWNERS

@@ -119,3 +119,8 @@ extensions/filters/common/original_src @snowp @klarose
 /*/extensions/compression/common @junr03 @rojkov
 /*/extensions/compression/gzip @junr03 @rojkov
 /*/extensions/filters/http/decompressor @rojkov @dio
+# Core upstream code
+extensions/upstreams/http @alyssawilk @snowp @mattklein123
+extensions/upstreams/http/http @alyssawilk @snowp @mattklein123
+extensions/upstreams/http/tcp @alyssawilk @mattklein123
+extensions/upstreams/http/default @alyssawilk @snowp @mattklein123

api/BUILD

@@ -232,6 +232,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",

api/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";
 
@@ -815,6 +816,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.

api/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";
 
@@ -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.v4alpha.TypedExtensionConfig upstream_config = 48;
 }
 
 // [#not-implemented-hide:] Extensible load balancing policy configuration.

api/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"],
+)

api/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 {
+}

api/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"],
+)

api/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 {
+}

api/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"],
+)

api/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 {
+}

api/versioning/BUILD

@@ -115,6 +115,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",

docs/root/api-v3/config/config.rst

@@ -19,3 +19,4 @@ Extensions
   trace/trace
   internal_redirect/internal_redirect
   endpoint/endpoint
+  upstream/upstream

docs/root/api-v3/config/upstream/upstream.rst

@@ -0,0 +1,8 @@
+Upstream Configuration
+======================
+
+.. toctree::
+  :glob:
+  :maxdepth: 3
+
+  ../../extensions/upstreams/http/*/v3/**