http_conn_man: ipv4-mapped ipv6 remote address toggle (#467)

Signed-off-by: Daniel Hochman <danielhochman@users.noreply.github.com>

docs/root/configuration/http_conn_man/headers.rst

@@ -177,6 +177,14 @@ Envoy uses the trusted client address contents to determine whether a request or
 externally or internally. This influences whether the
 :ref:`config_http_conn_man_headers_x-envoy-internal` header is set.
 
+Testing IPv6 in a large multi-hop system can be difficult from a change management perspective. For
+testing IPv6 compatibility of upstream services which parse XFF header values,
+:ref:`represent_ipv4_remote_address_as_ipv4_mapped_ipv6
+<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.represent_ipv4_remote_address_as_ipv4_mapped_ipv6>`
+can be enabled in the v2 API. Envoy will append an IPv4 address in mapped IPv6 format, e.g.
+::FFFF:50.0.0.1. This change will also apply to
+:ref:`config_http_conn_man_headers_x-envoy-external-address`.
+
 A few very important notes about XFF:
 
 1. If *use_remote_address* is set to true, Envoy sets the

docs/root/configuration/http_conn_man/runtime.rst

@@ -5,6 +5,17 @@ Runtime
 
 The HTTP connection manager supports the following runtime settings:
 
+.. _config_http_conn_man_runtime_represent_ipv4_remote_address_as_ipv4_mapped_ipv6:
+
+http_connection_manager.represent_ipv4_remote_address_as_ipv4_mapped_ipv6
+  % of requests with a remote address that will have their IPv4 address mapped to IPv6. Defaults to
+  0.
+  :ref:`use_remote_address <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.use_remote_address>`
+  must also be enabled. See
+  :ref:`represent_ipv4_remote_address_as_ipv4_mapped_ipv6
+  <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.represent_ipv4_remote_address_as_ipv4_mapped_ipv6>`
+  for more details.
+
 .. _config_http_conn_man_runtime_client_enabled:
 
 tracing.client_enabled

envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto

@@ -230,6 +230,20 @@ message HttpConnectionManager {
   // downstream. If this is false or not set, Envoy will instead strip the
   // "Expect: 100-continue" header, and send a "100 Continue" response itself.
   bool proxy_100_continue = 18;
+
+  // If
+  // :ref:`use_remote_address
+  // <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.use_remote_address>`
+  // is true and represent_ipv4_remote_address_as_ipv4_mapped_ipv6 is true and the remote address is
+  // an IPv4 address, the address will be mapped to IPv6 before it is appended to *x-forwarded-for*.
+  // This is useful for testing compatibility of upstream services that parse the header value. For
+  // example, 50.0.0.1 is represented as ::FFFF:50.0.0.1. See `IPv4-Mapped IPv6 Addresses
+  // <https://tools.ietf.org/html/rfc4291#section-2.5.5.2>`_ for details. This will also affect the
+  // :ref:`config_http_conn_man_headers_x-envoy-external-address` header. See
+  // :ref:`http_connection_manager.represent_ipv4_remote_address_as_ipv4_mapped_ipv6
+  // <config_http_conn_man_runtime_represent_ipv4_remote_address_as_ipv4_mapped_ipv6>` for runtime
+  // control.
+  bool represent_ipv4_remote_address_as_ipv4_mapped_ipv6 = 19;
 }
 
 message Rds {