envoyproxy · mattklein123 · May 4, 2020 · Apr 2, 2020 · Apr 3, 2020 · Apr 7, 2020
diff --git a/docs/root/configuration/best_practices/edge.rst b/docs/root/configuration/best_practices/edge.rst
@@ -11,19 +11,19 @@ TCP proxies should configure:
 
 * restrict access to the admin endpoint,
 * :ref:`overload_manager <config_overload_manager>`,
-* :ref:`listener buffer limits <envoy_api_field_Listener.per_connection_buffer_limit_bytes>` to 32 KiB,
-* :ref:`cluster buffer limits <envoy_api_field_Cluster.per_connection_buffer_limit_bytes>` to 32 KiB.
+* :ref:`listener buffer limits <envoy_v3_api_field_config.listener.v3.Listener.per_connection_buffer_limit_bytes>` to 32 KiB,
+* :ref:`cluster buffer limits <envoy_v3_api_field_config.cluster.v3.Cluster.per_connection_buffer_limit_bytes>` to 32 KiB.
 
 HTTP proxies should additionally configure:
 
-* :ref:`use_remote_address <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.use_remote_address>`
+* :ref:`use_remote_address <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.use_remote_address>`
   to true (to avoid consuming HTTP headers from external clients, see :ref:`HTTP header sanitizing <config_http_conn_man_header_sanitizing>`
   for details),
 * :ref:`connection and stream timeouts <faq_configuration_timeouts>`,
-* :ref:`HTTP/2 maximum concurrent streams limit <envoy_api_field_core.Http2ProtocolOptions.max_concurrent_streams>` to 100,
-* :ref:`HTTP/2 initial stream window size limit <envoy_api_field_core.Http2ProtocolOptions.initial_stream_window_size>` to 64 KiB,
-* :ref:`HTTP/2 initial connection window size limit <envoy_api_field_core.Http2ProtocolOptions.initial_connection_window_size>` to 1 MiB.
-* :ref:`headers_with_underscores_action setting <envoy_api_field_core.HttpProtocolOptions.headers_with_underscores_action>` to REJECT_REQUEST, to protect upstream services that treat '_' and '-' as interchangeable.
+* :ref:`HTTP/2 maximum concurrent streams limit <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.max_concurrent_streams>` to 100,
+* :ref:`HTTP/2 initial stream window size limit <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.initial_stream_window_size>` to 64 KiB,
+* :ref:`HTTP/2 initial connection window size limit <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.initial_connection_window_size>` to 1 MiB.
+* :ref:`headers_with_underscores_action setting <envoy_v3_api_field_config.core.v3.HttpProtocolOptions.headers_with_underscores_action>` to REJECT_REQUEST, to protect upstream services that treat '_' and '-' as interchangeable.
 
 The following is a YAML example of the above recommendation.
 
@@ -69,17 +69,20 @@ The following is a YAML example of the above recommendation.
       filter_chains:
       - filter_chain_match:
           server_names: ["example.com", "www.example.com"]
-        tls_context:
-          common_tls_context:
-            tls_certificates:
-            - certificate_chain: { filename: "example_com_cert.pem" }
-              private_key: { filename: "example_com_key.pem" }
+        transport_socket:
+          name: envoy.transport_sockets.tls
+          typed_config:
+            "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
+            common_tls_context:
+              tls_certificates:
+              - certificate_chain: { filename: "example_com_cert.pem" }
+                private_key: { filename: "example_com_key.pem" }
         # Uncomment if Envoy is behind a load balancer that exposes client IP address using the PROXY protocol.
         # use_proxy_proto: true
         filters:
         - name: envoy.filters.network.http_connection_manager
           typed_config:
-            "@type": type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager
+            "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
             stat_prefix: ingress_http
             use_remote_address: true
             common_http_protocol_options:
@@ -104,10 +107,15 @@ The following is a YAML example of the above recommendation.
       name: service_foo
       connect_timeout: 15s
       per_connection_buffer_limit_bytes: 32768 # 32 KiB
-      hosts:
-        socket_address:
-          address: 127.0.0.1
-          port_value: 8080
+      load_assignment:
+        cluster_name: some_service
+        endpoints:
+          - lb_endpoints:
+            - endpoint:
+                address:
+                  socket_address:
+                    address: 127.0.0.1
+                    port_value: 8080
       http2_protocol_options:
         initial_stream_window_size: 65536 # 64 KiB
         initial_connection_window_size: 1048576 # 1 MiB
diff --git a/docs/root/configuration/best_practices/level_two.rst b/docs/root/configuration/best_practices/level_two.rst
@@ -12,7 +12,7 @@ edge use case may need to be adjusted when using Envoy in a multi-level deployme
 **In summary, if you run level two Envoy version 1.11.1 or greater which terminates 
 HTTP/2, we strongly advise you to change the HTTP/2 configuration of your level 
 two Envoy, by setting its downstream**
-:ref:`validation of HTTP/2 messaging option <envoy_api_field_core.Http2ProtocolOptions.stream_error_on_invalid_http_messaging>`
+:ref:`validation of HTTP/2 messaging option <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.stream_error_on_invalid_http_messaging>`
 **to true.**
 
 If there is an invalid HTTP/2 request and this option is not set, the Envoy in 
@@ -30,7 +30,7 @@ user has insight into what traffic will bypass level one checks, they could spra
 traffic.
 
 Please note that the
-:ref:`validation of HTTP/2 messaging option <envoy_api_field_core.Http2ProtocolOptions.stream_error_on_invalid_http_messaging>`
+:ref:`validation of HTTP/2 messaging option <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.stream_error_on_invalid_http_messaging>`
 is planned to be deprecated and replaced with mandatory configuration in the HttpConnectionManager, to ensure
 that what is now an easily overlooked option would need to be configured, ideally
 appropriately for the given Envoy deployment. Please refer to the

diff --git a/docs/root/configuration/http/http_conn_man/header_casing.rst b/docs/root/configuration/http/http_conn_man/header_casing.rst
@@ -7,5 +7,5 @@ existing systems that might rely on specific header casing.
 
 To support these use cases, Envoy allows configuring a formatting scheme for the headers, which
 will have Envoy transform the header keys during serialization. To configure this formatting on
-response headers, specify the format in the :ref:`http_protocol_options <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.http_protocol_options>`.
-To configure this for upstream request headers, specify the formatting on the :ref:`Cluster <envoy_api_field_Cluster.http_protocol_options>`.
+response headers, specify the format in the :ref:`http_protocol_options <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.http_protocol_options>`.
+To configure this for upstream request headers, specify the formatting on the :ref:`Cluster <envoy_v3_api_field_config.cluster.v3.Cluster.http_protocol_options>`.
diff --git a/docs/root/configuration/http/http_conn_man/header_sanitizing.rst b/docs/root/configuration/http/http_conn_man/header_sanitizing.rst
@@ -9,10 +9,10 @@ result in addition, removal, or modification. Ultimately, whether the request is
 or external is governed by the :ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>`
 header (please read the linked section carefully as how Envoy populates the header is complex and depends on the
 :ref:`use_remote_address
-<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.use_remote_address>`
+<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.use_remote_address>`
 setting). In addition, the
 :ref:`internal_address_config
-<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.internal_address_config>`
+<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.internal_address_config>`
 setting can be used to configure the internal/external determination.
 
 Envoy will potentially sanitize the following headers:

diff --git a/docs/root/configuration/http/http_conn_man/headers.rst b/docs/root/configuration/http/http_conn_man/headers.rst
@@ -15,7 +15,7 @@ user-agent
 ----------
 
 The *user-agent* header may be set by the connection manager during decoding if the :ref:`add_user_agent
-<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.add_user_agent>` option is
+<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.add_user_agent>` option is
 enabled. The header is only modified if it is not already set. If the connection manager does set the header, the value
 is determined by the :option:`--service-cluster` command line option.
 
@@ -25,7 +25,7 @@ server
 ------
 
 The *server* header will be set during encoding to the value in the :ref:`server_name
-<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.server_name>` option.
+<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.server_name>` option.
 
 .. _config_http_conn_man_headers_x-client-trace-id:
 
@@ -49,7 +49,7 @@ that in the current implementation, this should be considered a hint as it is se
 could be easily spoofed by any internal entity. In the future Envoy will support a mutual
 authentication TLS mesh which will make this header fully secure. Like *user-agent*, the value
 is determined by the :option:`--service-cluster` command line option. In order to enable this
-feature you need to set the :ref:`user_agent <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.add_user_agent>` option to true.
+feature you need to set the :ref:`user_agent <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.add_user_agent>` option to true.
 
 .. _config_http_conn_man_headers_downstream-service-node:
 
@@ -108,7 +108,7 @@ The header used to override destination address when using the
 load balancing policy.
 
 It is ignored, unless the use of it is enabled via
-:ref:`use_http_header <envoy_api_field_Cluster.OriginalDstLbConfig.use_http_header>`.
+:ref:`use_http_header <envoy_v3_api_field_config.cluster.v3.Cluster.OriginalDstLbConfig.use_http_header>`.
 
 .. _config_http_conn_man_headers_x-forwarded-client-cert:
 
@@ -149,9 +149,9 @@ Some examples of the XFCC header are:
 3. For one client certificate with both URI type and DNS type Subject Alternative Name: ``x-forwarded-client-cert: By=http://frontend.lyft.com;Hash=468ed33be74eee6556d90c0149c1309e9ba61d6425303443c0748a02dd8de688;Subject="/C=US/ST=CA/L=San Francisco/OU=Lyft/CN=Test Client";URI=http://testclient.lyft.com;DNS=lyft.com;DNS=www.lyft.com``
 
 How Envoy processes XFCC is specified by the
-:ref:`forward_client_cert_details<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.forward_client_cert_details>`
+:ref:`forward_client_cert_details<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.forward_client_cert_details>`
 and the
-:ref:`set_current_client_cert_details<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.set_current_client_cert_details>`
+:ref:`set_current_client_cert_details<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.set_current_client_cert_details>`
 HTTP connection manager options. If *forward_client_cert_details* is unset, the XFCC header will be sanitized by
 default.
 
@@ -169,9 +169,9 @@ address of the nearest client to the XFF list before proxying the request. Some
 3. ``x-forwarded-for: 50.0.0.1, 10.0.0.1`` (internal proxy hop)
 
 Envoy will only append to XFF if the :ref:`use_remote_address
-<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.use_remote_address>`
+<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.use_remote_address>`
 HTTP connection manager option is set to true and the :ref:`skip_xff_append
-<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.skip_xff_append>`
+<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.skip_xff_append>`
 is set false. This means that if *use_remote_address* is false (which is the default) or
 *skip_xff_append* is true, the connection manager operates in a transparent mode where it does not
 modify XFF.
@@ -318,7 +318,7 @@ A few very important notes about XFF:
 
    * **NOTE**: If an internal service proxies an external request to another internal service, and
      includes the original XFF header, Envoy will append to it on egress if
-     :ref:`use_remote_address <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.use_remote_address>` is set. This will cause
+     :ref:`use_remote_address <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.use_remote_address>` is set. This will cause
      the other side to think the request is external. Generally, this is what is intended if XFF is
      being forwarded. If it is not intended, do not forward XFF, and forward
      :ref:`config_http_conn_man_headers_x-envoy-internal` instead.
@@ -352,7 +352,7 @@ is out of scope for this documentation. If *x-request-id* is propagated across a
 following features are available:
 
 * Stable :ref:`access logging <config_access_log>` via the
-  :ref:`v2 API runtime filter<envoy_api_field_config.filter.accesslog.v2.AccessLogFilter.runtime_filter>`.
+  :ref:`v3 API runtime filter<envoy_v3_api_field_config.accesslog.v3.AccessLogFilter.runtime_filter>`.
 * Stable tracing when performing random sampling via the :ref:`tracing.random_sampling
   <config_http_conn_man_runtime_random_sampling>` runtime setting or via forced tracing using the
   :ref:`config_http_conn_man_headers_x-envoy-force-trace` and
@@ -467,13 +467,13 @@ Custom request/response headers
 
 Custom request/response headers can be added to a request/response at the weighted cluster,
 route, virtual host, and/or global route configuration level. See the
-:ref:`v2 <envoy_api_msg_RouteConfiguration>` API documentation.
+:ref:`v3 <envoy_v3_api_msg_config.route.v3.RouteConfiguration>` API documentation.
 
 No *:-prefixed* pseudo-header may be modified via this mechanism. The *:path*
 and *:authority* headers may instead be modified via mechanisms such as
-:ref:`prefix_rewrite <envoy_api_field_route.RouteAction.prefix_rewrite>`,
-:ref:`regex_rewrite <envoy_api_field_route.RouteAction.regex_rewrite>`, and
-:ref:`host_rewrite <envoy_api_field_route.RouteAction.host_rewrite>`.
+:ref:`prefix_rewrite <envoy_v3_api_field_config.route.v3.RouteAction.prefix_rewrite>`,
+:ref:`regex_rewrite <envoy_v3_api_field_config.route.v3.RouteAction.regex_rewrite>`, and
+:ref:`host_rewrite <envoy_v3_api_field_config.route.v3.RouteAction.host_rewrite_literal>`.
 
 Headers are appended to requests/responses in the following order: weighted cluster level headers,
 route level headers, virtual host level headers and finally global level headers.
@@ -496,7 +496,7 @@ Supported variable names are:
     .. note::
 
       This may not be the physical remote address of the peer if the address has been inferred from
-      :ref:`proxy proto <envoy_api_field_listener.FilterChain.use_proxy_proto>` or :ref:`x-forwarded-for
+      :ref:`proxy proto <envoy_v3_api_field_config.listener.v3.FilterChain.use_proxy_proto>` or :ref:`x-forwarded-for
       <config_http_conn_man_headers_x-forwarded-for>`.
 
 %DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%
@@ -603,7 +603,7 @@ Supported variable names are:
     :ref:`x-forwarded-proto <config_http_conn_man_headers_x-forwarded-proto>` request header.
 
 %UPSTREAM_METADATA(["namespace", "key", ...])%
-    Populates the header with :ref:`EDS endpoint metadata <envoy_api_field_endpoint.LbEndpoint.metadata>` from the
+    Populates the header with :ref:`EDS endpoint metadata <envoy_v3_api_field_config.endpoint.v3.LbEndpoint.metadata>` from the
     upstream host selected by the router. Metadata may be selected from any namespace. In general,
     metadata values may be strings, numbers, booleans, lists, nested structures, or null. Upstream
     metadata values may be selected from nested structs by specifying multiple keys. Otherwise,

diff --git a/docs/root/configuration/http/http_conn_man/overview.rst b/docs/root/configuration/http/http_conn_man/overview.rst
@@ -3,5 +3,5 @@ Overview
 
 * HTTP connection manager :ref:`architecture overview <arch_overview_http_conn_man>`
 * HTTP protocols :ref:`architecture overview <arch_overview_http_protocols>`
-* :ref:`v2 API reference
-  <envoy_api_msg_config.filter.network.http_connection_manager.v2.HttpConnectionManager>`
+* :ref:`v3 API reference
+  <envoy_v3_api_msg_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager>`
diff --git a/docs/root/configuration/http/http_conn_man/rds.rst b/docs/root/configuration/http/http_conn_man/rds.rst
@@ -4,7 +4,7 @@ Route discovery service (RDS)
 =============================
 
 The route discovery service (RDS) API is an optional API that Envoy will call to dynamically fetch
-:ref:`route configurations <envoy_api_msg_RouteConfiguration>`. A route configuration includes both
+:ref:`route configurations <envoy_v3_api_msg_config.route.v3.RouteConfiguration>`. A route configuration includes both
 HTTP header modifications, virtual hosts, and the individual route entries contained within each
 virtual host. Each :ref:`HTTP connection manager filter <config_http_conn_man>` can independently
 fetch its own route configuration via the API. Optionally, the 

diff --git a/docs/root/configuration/http/http_conn_man/route_matching.rst b/docs/root/configuration/http/http_conn_man/route_matching.rst
@@ -6,9 +6,9 @@ Route matching
 When Envoy matches a route, it uses the following procedure:
 
 #. The HTTP request's *host* or *:authority* header is matched to a :ref:`virtual host
-   <envoy_api_msg_route.VirtualHost>`.
-#. Each :ref:`route entry <envoy_api_msg_route.Route>` in the virtual host is checked,
+   <envoy_v3_api_msg_config.route.v3.VirtualHost>`.
+#. Each :ref:`route entry <envoy_v3_api_msg_config.route.v3.Route>` in the virtual host is checked,
    *in order*. If there is a match, the route is used and no further route checks are made.
-#. Independently, each :ref:`virtual cluster <envoy_api_msg_route.VirtualCluster>` in the
+#. Independently, each :ref:`virtual cluster <envoy_v3_api_msg_config.route.v3.VirtualCluster>` in the
    virtual host is checked, *in order*. If there is a match, the virtual cluster is used and no
    further virtual cluster checks are made.
diff --git a/docs/root/configuration/http/http_conn_man/runtime.rst b/docs/root/configuration/http/http_conn_man/runtime.rst
@@ -9,7 +9,7 @@ The HTTP connection manager supports the following runtime settings:
 
 http_connection_manager.normalize_path
   % of requests that will have path normalization applied if not already configured in
-  :ref:`normalize_path <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.normalize_path>`.
+  :ref:`normalize_path <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.normalize_path>`.
   This is evaluated at configuration load time and will apply to all requests for a given
   configuration.