From 590ab94d8d2b6dff7ac8d3b847a7aa62686a7cd4 Mon Sep 17 00:00:00 2001 From: James Phillips Date: Sun, 7 Feb 2016 10:56:47 -0800 Subject: [PATCH] Adds documentation for WAN address translation. --- website/source/docs/agent/dns.html.markdown | 9 ++++++ .../docs/agent/http/catalog.html.markdown | 20 +++++++++++-- .../docs/agent/http/health.html.markdown | 5 +++- .../source/docs/agent/options.html.markdown | 29 +++++++++++++------ 4 files changed, 50 insertions(+), 13 deletions(-) diff --git a/website/source/docs/agent/dns.html.markdown b/website/source/docs/agent/dns.html.markdown index 4a06353e96..a104fc607f 100644 --- a/website/source/docs/agent/dns.html.markdown +++ b/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. diff --git a/website/source/docs/agent/http/catalog.html.markdown b/website/source/docs/agent/http/catalog.html.markdown index 323166f387..6b9d4cfc01 100644 --- a/website/source/docs/agent/http/catalog.html.markdown +++ b/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": { diff --git a/website/source/docs/agent/http/health.html.markdown b/website/source/docs/agent/http/health.html.markdown index 7aee45933b..6f0c4a99ef 100644 --- a/website/source/docs/agent/http/health.html.markdown +++ b/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", diff --git a/website/source/docs/agent/options.html.markdown b/website/source/docs/agent/options.html.markdown index dd4cd58517..3a27023575 100644 --- a/website/source/docs/agent/options.html.markdown +++ b/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. -* `-advertise-wan` - The advertise wan - address is used to change the address that we advertise to server nodes joining - through the WAN. By default, the [`-advertise`](#_advertise) address is advertised. - However, in some cases all members of all datacenters cannot be on the same - physical or virtual network, 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. +* `-advertise-wan` - The + advertise WAN address is used to change the address that we advertise to server nodes + joining through the WAN. This can also be set on client agents when used in combination + with the `translate_wan_addrs` configuration + option. By default, the [`-advertise`](#_advertise) address is advertised. However, in some + cases all members of all datacenters cannot be on the same physical or virtual network, + 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 `translate_wan_addrs`. * `-atlas` - 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 - this is `username/environment`. This enables Atlas features such as the Monitoring UI + 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 and node auto joining. * `-atlas-join` - 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. +* `translate_wan_addrs` If + set to true, Consul will prefer a node's configured WAN address + 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. + * `ui` - Equivalent to the [`-ui`](#_ui) command-line flag.