Adds documentation for WAN address translation.

website/source/docs/agent/dns.html.markdown

@@ -207,3 +207,12 @@ By default, all DNS results served by Consul set a 0 TTL value. This disables
 caching of DNS results. However, there are many situations in which caching is
 desirable for performance and scalability. This is discussed more in the guide
 for [DNS Caching](/docs/guides/dns-cache.html).
+
+## WAN Address Translation
+
+Be default, Consul DNS queries will return a node's local address, even when
+being queried from a remote datacenter. If you need to use a different address
+to reach a node from outside its datacenter, you can configure this behavior
+using the [`advertise-wan`](/docs/agent/options.html#_advertise-wan) and
+[`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs) configuration
+options.

website/source/docs/agent/http/catalog.html.markdown

@@ -48,6 +48,9 @@ body must look something like:
       "v1"
     ],
     "Address": "127.0.0.1",
+    "TaggedAddresses": {
+      "wan": "127.0.0.1"
+    },
     "Port": 8000
   },
   "Check": {
@@ -64,7 +67,9 @@ body must look something like:
 The behavior of the endpoint depends on what keys are provided. The endpoint
 requires `Node` and `Address` to be provided while `Datacenter` will be defaulted
 to match that of the agent. If only those are provided, the endpoint will register
-the node with the catalog.
+the node with the catalog. `TaggedAddresses` can be used in conjunction with the
+[`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs) configuration
+option. Currently only the "wan" tag is supported.
 
 If the `Service` key is provided, the service will also be registered. If
 `ID` is not provided, it will be defaulted to the value of the `Service.Service` property.
@@ -191,10 +196,16 @@ It returns a JSON body like this:
   {
     "Node": "baz",
     "Address": "10.1.10.11"
+    "TaggedAddresses": {
+      "wan": "10.1.10.11"
+    }
   },
   {
     "Node": "foobar",
-    "Address": "10.1.10.12"
+    "Address": "10.1.10.12",
+    "TaggedAddresses": {
+      "wan": "10.1.10.12"
+    }
   }
 ]
 ```
@@ -271,7 +282,10 @@ It returns a JSON body like this:
 {
   "Node": {
     "Node": "foobar",
-    "Address": "10.1.10.12"
+    "Address": "10.1.10.12",
+    "TaggedAddresses": {
+      "wan": "10.1.10.12"
+    }
   },
   "Services": {
     "consul": {

website/source/docs/agent/http/health.html.markdown

@@ -127,7 +127,10 @@ It returns a JSON body like this:
   {
     "Node": {
       "Node": "foobar",
-      "Address": "10.1.10.12"
+      "Address": "10.1.10.12",
+      "TaggedAddresses": {
+        "wan": "10.1.10.12"
+      }
     },
     "Service": {
       "ID": "redis",

website/source/docs/agent/options.html.markdown

@@ -41,18 +41,22 @@ The options below are all specified on the command-line.
   If this address is not routable, the node will be in a constant flapping state
   as other nodes will treat the non-routability as a failure.
 
-* <a name="_advertise-wan"></a><a href="#_advertise-wan">`-advertise-wan`</a> - The advertise wan
+* <a name="_advertise-wan"></a><a href="#_advertise-wan">`-advertise-wan`</a> - The
-  address is used to change the address that we advertise to server nodes joining
+  advertise WAN address is used to change the address that we advertise to server nodes
-  through the WAN. By default, the [`-advertise`](#_advertise) address is advertised.
+  joining through the WAN. This can also be set on client agents when used in combination
-  However, in some cases all members of all datacenters cannot be on the same
+  with the <a href="#translate_wan_addrs">`translate_wan_addrs`</a> configuration
-  physical or virtual network, especially on hybrid setups mixing cloud and private datacenters.
+  option. By default, the [`-advertise`](#_advertise) address is advertised. However, in some
-  This flag enables server nodes gossiping through the public network for the WAN while using
+  cases all members of all datacenters cannot be on the same physical or virtual network,
-  private VLANs for gossiping to each other and their client agents.
+  especially on hybrid setups mixing cloud and private datacenters. This flag enables server
+  nodes gossiping through the public network for the WAN while using private VLANs for gossiping
+  to each other and their client agents, and it allows client agents to be reached at this
+  address when being accessed from a remote datacenter if the remote datacenter is configured
+  with <a href="#translate_wan_addrs">`translate_wan_addrs`</a>.
 
 * <a name="_atlas"></a><a href="#_atlas">`-atlas`</a> - This flag
   enables [Atlas](https://atlas.hashicorp.com) integration.
-  It is used to provide the Atlas infrastructure name and the SCADA connection. The format of 
+  It is used to provide the Atlas infrastructure name and the SCADA connection. The format of
-  this is `username/environment`. This enables Atlas features such as the Monitoring UI 
+  this is `username/environment`. This enables Atlas features such as the Monitoring UI
   and node auto joining.
 
 * <a name="_atlas_join"></a><a href="#_atlas_join">`-atlas-join`</a> - When set, enables auto-join
@@ -623,6 +627,13 @@ definitions support being updated during a reload.
   [`enable_syslog`](#enable_syslog) is provided, this controls to which
   facility messages are sent. By default, `LOCAL0` will be used.
 
+* <a name="translate_wan_addrs"</a><a href="#translate_wan_addrs">`translate_wan_addrs`</a> If
+  set to true, Consul will prefer a node's configured <a href="#_advertise-wan">WAN address</a>
+  when servicing DNS requests for a node in a remote datacenter. This allows the node to be
+  reached within its own datacenter using its local address, and reached from other datacenters
+  using its WAN address, which is useful in hybrid setups with mixed networks. This is disabled
+  by default.
+
 * <a name="ui"></a><a href="#ui">`ui`</a> - Equivalent to the [`-ui`](#_ui)
   command-line flag.