diff --git a/website/content/docs/discovery/services.mdx b/website/content/docs/discovery/services.mdx index d15d9d018..2f627ab32 100644 --- a/website/content/docs/discovery/services.mdx +++ b/website/content/docs/discovery/services.mdx @@ -275,6 +275,260 @@ For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0 supports both `enable_tag_override` and `enableTagOverride` but the latter is deprecated and has been removed as of Consul 1.1. +### Tagged Addresses + +Tagged addresses are additional addresses which may be defined for a node or +service. Tagged addresses can be used by remote agents and services as alternative +addresses for communicating with the given node or service. Multiple tagged +addresses may be configured on a node or service. + +The syntax for defining a tagged address is as follows. + + + +```hcl +service { + name = "redis" + port = 80 + tagged_addresses { + = { + address = "
" + port = port + } + } +} +``` + +```json +{ + "service": { + "name": "redis", + "port": 80, + "tagged_addresses": { + "": { + "address": "
", + "port": port + } + } + } +} +``` + + + +Consul supports several tagged address types. The various types and their use +cases are detailed below. + +#### LAN + +LAN addresses are intended to be directly accessible only from services within +the same Consul data center. + +##### Supported tags + +* `lan` - The IPv4 LAN address at which the node or service is accessible. +* `lan_ipv4` - The IPv4 LAN address at which the node or service is accessible. +* `lan_ipv6` - The IPv6 LAN address at which the node or service is accessible. + + + + + +```hcl +service { + name = "redis" + address = "192.0.2.10" + port = 80 + tagged_addresses { + lan = { + address = "192.0.2.10" + port = 80 + } + lan_ipv4 = { + address = "192.0.2.10" + port = 80 + } + lan_ipv6 = { + address = "2001:db8:1:2:cafe::1337" + port = 80 + } + } +} +``` + + + + + +```json +{ + "service": { + "name": "redis", + "address": "192.0.2.10", + "port": 80, + "tagged_addresses": { + "lan": { + "address": "192.0.2.10", + "port": 80 + }, + "lan_ipv4": { + "address": "192.0.2.10", + "port": 80 + }, + "lan_ipv6": { + "address": "2001:db8:1:2:cafe::1337", + "port": 80 + } + } + } +} +``` + + + + +#### Virtual + +Virtual tagged addresses are logical address types which can be configured on +[Connect](/docs/connect)-enabled services. The virtual address provides a fixed +IP address that can be used by downstream services when connecting to an +upstream service. Connections to the virtual address are load balanced across +available instances of a service, provided the following conditions are satisfied: + +1. [Transparent proxy](/docs/connect/transparent-proxy) is enabled for the + downstream and upstream services. +1. The upstream service is not configured for individual instances to be + [dialed directly](/docs/connect/config-entries/service-defaults#dialeddirectly). + +-> **Note**: Virtual addresses are not required to be routable IPs within the +network. They are strictly a control plane construct used to provide a fixed +address for the instances of a given logical service. Egress connections from +the proxy to an upstream service will be destined to the IP address of an +individual service instance, not the virtual address of the logical service. + +##### Supported tags + +Use the following address tag to specify the logical address at which the +service can be reached by other services in the mesh. + +- `virtual` - The virtual IP address at which a logical service is reachable. + + + + + +```hcl +service { + name = "redis" + address = "192.0.2.10" + port = 80 + tagged_addresses { + virtual = { + address = "203.0.113.50" + port = 80 + } + } +} +``` + + + + + +```json +{ + "service": { + "name": "redis", + "address": "192.0.2.10", + "port": 80, + "tagged_addresses": { + "virtual": { + "address": "203.0.113.50", + "port": 80 + } + } + } +} +``` + + + + +#### WAN + +Define a WAN address for the service or node when it should be accessed at an +alternate address by services in a remote datacenter. + +##### Supported tags + +One or more of the following address tags can be configured for a node or service +to advertise how it should be accessed over the WAN. + +- `wan` - The IPv4 WAN address at which the node or service is accessible when + being dialed from a remote data center. +- `wan_ipv4` - The IPv4 WAN address at which the node or service is accessible + when being dialed from a remote data center. +- `wan_ipv6` - The IPv6 WAN address at which the node or service is accessible + when being dialed from a remote data center. + + + + + +```hcl +service { + name = "redis" + address = "192.0.2.10" + port = 80 + tagged_addresses { + wan = { + address = "198.51.100.200" + port = 80 + } + wan_ipv4 = { + address = "198.51.100.200" + port = 80 + } + wan_ipv6 = { + address = "2001:db8:5:6:1337::1eaf" + port = 80 + } + } +} +``` + + + + + +```json +{ + "service": { + "name": "redis", + "address": "192.0.2.10", + "port": 80, + "tagged_addresses": { + "wan": { + "address": "198.51.100.200", + "port": 80 + }, + "wan_ipv4": { + "address": "198.51.100.200", + "port": 80 + }, + "wan_ipv6": { + "address": "2001:db8:5:6:1337::1eaf", + "port": 80 + } + } + } +} +``` + + + + + ## Multiple Service Definitions Multiple services definitions can be provided at once when registering services