docs: access log / custom header updates (#352)

Signed-off-by: Matt Klein <mklein@lyft.com>

docs/root/configuration/access_log.rst

@@ -98,10 +98,40 @@ The following command operators are supported:
   Upstream cluster to which the upstream host belongs to.
 
 %UPSTREAM_LOCAL_ADDRESS%
-  Local address of the upstream connection.
+  Local address of the upstream connection. If the address is an IP address it includes both
+  address and port.
 
 %DOWNSTREAM_ADDRESS%
-  Remote address of the downstream connection.
+  Remote address of the downstream connection *without IP port if the address is an IP address*.
+
+  .. attention::
+
+    This field is deprecated. Use **DOWNSTREAM_REMOTE_ADDRESS** or
+    **DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT** instead.
+
+%DOWNSTREAM_REMOTE_ADDRESS%
+  Remote address of the downstream connection. If the address is an IP address it includes both
+  address and port.
+
+  .. 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>`.
+
+%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::
+
+    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>`.
+
+%DOWNSTREAM_LOCAL_ADDRESS%
+  Remote address of the downstream connection. If the address is an IP address it includes both
+  address and port.
 
 %REQ(X?Y):Z%
   HTTP

docs/root/configuration/http_conn_man/headers.rst

@@ -296,6 +296,20 @@ Supported dynamic values are:
    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::
+
+     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.
+
+   .. 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>`.
+
 %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.