docs: update custom header docs to match envoy behavior

api/rds.proto

@@ -52,7 +52,9 @@ message RouteConfiguration {
   // Specifies a list of HTTP headers that should be added to each response that
   // the connection manager encodes. Headers specified at this level are applied
   // after headers from any enclosed :ref:`envoy_api_msg_VirtualHost` or
-  // :ref:`envoy_api_msg_RouteAction`.
+  // :ref:`envoy_api_msg_RouteAction`. For more information, including details on
+  // header value syntax, see the documentation on :ref:`custom request headers
+  // <config_http_conn_man_headers_custom_request_headers>`.
   repeated HeaderValueOption response_headers_to_add = 4;
 
   // Specifies a list of HTTP headers that should be removed from each response
@@ -62,8 +64,9 @@ message RouteConfiguration {
   // Specifies a list of HTTP headers that should be added to each request
   // routed by the HTTP connection manager. Headers specified at this level are
   // applied after headers from any enclosed :ref:`envoy_api_msg_VirtualHost` or
-  // :ref:`envoy_api_msg_RouteAction`. For more information see the documentation on
-  // :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
+  // :ref:`envoy_api_msg_RouteAction`. For more information, including details on
+  // header value syntax, see the documentation on :ref:`custom request headers
+  // <config_http_conn_man_headers_custom_request_headers>`.
   repeated HeaderValueOption request_headers_to_add = 6;
 
   // An optional boolean that specifies whether the clusters that the route
@@ -137,14 +140,17 @@ message VirtualHost {
   // Specifies a list of HTTP headers that should be added to each request
   // handled by this virtual host. Headers specified at this level are applied
   // after headers from enclosed :ref:`envoy_api_msg_RouteAction` and before headers from the
-  // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information see the documentation
-  // on :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
+  // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on
+  // header value syntax, see the documentation on :ref:`custom request headers
+  // <config_http_conn_man_headers_custom_request_headers>`.
   repeated HeaderValueOption request_headers_to_add = 7;
 
   // Specifies a list of HTTP headers that should be added to each response
   // handled by this virtual host. Headers specified at this level are applied
   // after headers from enclosed :ref:`envoy_api_msg_RouteAction` and before headers from the
-  // enclosing :ref:`envoy_api_msg_RouteConfiguration`.
+  // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on
+  // header value syntax, see the documentation on :ref:`custom request headers
+  // <config_http_conn_man_headers_custom_request_headers>`.
   repeated HeaderValueOption response_headers_to_add = 10;
 
   // Specifies a list of HTTP headers that should be removed from each response
@@ -449,14 +455,16 @@ message RouteAction {
   // Specifies a set of headers that will be added to requests matching this
   // route. Headers specified at this level are applied before headers from the
   // enclosing :ref:`envoy_api_msg_VirtualHost` and :ref:`envoy_api_msg_RouteConfiguration`.
-  // For more information see the documentation on :ref:`custom request headers
-  // <config_http_conn_man_headers_custom_request_headers>`.
+  // For more information, including details on header value syntax, see the documentation on
+  // :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
   repeated HeaderValueOption request_headers_to_add = 12;
 
   // Specifies a set of headers that will be added to responses to requests
   // matching this route. Headers specified at this level are applied before
   // headers from the enclosing :ref:`envoy_api_msg_VirtualHost` and
-  // :ref:`envoy_api_msg_RouteConfiguration`.
+  // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including
+  // details on header value syntax, see the documentation on
+  // :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
   repeated HeaderValueOption response_headers_to_add = 18;
 
   // Specifies a list of HTTP headers that should be removed from each response

docs/root/api-v1/route_config/route_config.rst

@@ -55,6 +55,9 @@ response_headers_to_add
       {"key": "header2", "value": "value2"}
     ]
 
+  For more information, including details on header value syntax, see the documentation on
+  :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
+
 response_headers_to_remove
   *(optional, array)* Optionally specifies a list of HTTP headers that should be removed from each
   response that the connection manager encodes. Headers are specified in the following form:
@@ -76,8 +79,8 @@ request_headers_to_add
       {"key": "header2", "value": "value2"}
     ]
 
-  For more information see the documentation on :ref:`custom request headers
-  <config_http_conn_man_headers_custom_request_headers>`.
+  For more information, including details on header value syntax, see the documentation on
+  :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
 
 .. toctree::
   :hidden:

docs/root/configuration/http_conn_man/headers.rst

@@ -286,39 +286,48 @@ the route, virtual host, and global route configuration level. See the relevant
 <config_http_conn_man_route_table>` and :ref:`v2 <envoy_api_msg_RouteConfiguration>` API
 documentation.
 
-**Note:** Headers are appended to requests/responses in the following order: route level headers, virtual host
-level headers and finally global level headers.
+Headers are appended to requests/responses in the following order: route level headers,
+virtual host level headers and finally global level headers.
 
-Envoy additionally supports adding dynamic values to request and response headers.
-Supported dynamic values are:
+Envoy supports adding dynamic values to request and response headers. The percent symbol (%) is
+used to delimit variable names.
+
+.. attention::
+
+  If a literal percent symbol (%) is desired in a request/response header, it must be escaped by
+  doubling it. For example, to emit a header with the value ``100%``, the custom header value in
+  the Envoy configuration must be ``100%%``.
+
+Supported variable names are:
 
 %CLIENT_IP%
-   The original client IP which is already added by Envoy as a
-   :ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>` request header.
+    The original client IP which is already added by Envoy as a
+    :ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>` request header.
 
-   .. attention::
+    .. attention::
 
-     This field is deprecated. Use **DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT** instead.
+      This field is deprecated. Use **DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT** instead.
 
- %DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%
-   Remote address of the downstream connection. If the address is an IP address the output does
-   *not* include port.
+%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%
+    Remote address of the downstream connection. If the address is an IP address the output does
+    *not* include port.
 
-   .. note::
+    .. 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_FilterChain.use_proxy_proto>` or :ref:`x-forwarded-for
-     <config_http_conn_man_headers_x-forwarded-for>`.
+      This may not be the physical remote address of the peer if the address has been inferred from
+      :ref:`proxy proto <envoy_api_field_FilterChain.use_proxy_proto>` or :ref:`x-forwarded-for
+      <config_http_conn_man_headers_x-forwarded-for>`.
 
 %PROTOCOL%
     The original protocol which is already added by Envoy as a
     :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_file_api/eds.proto>` from the
+    Populates the header with :ref:`EDS endpoint metadata <envoy_api_file_api/eds.proto>` 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,
     only string, boolean, and numeric values are supported. If the namespace or key(s) are not
     found, or if the selected value is not a supported type, then no header is emitted. The
-    namespace and key(s) are specified as a JSON array of strings.
+    namespace and key(s) are specified as a JSON array of strings. Finally, percent symbols in the
+    parameters **do not** need to be escaped by doubling them.