From a4d2dc0ce2ac76f10a442a572f79e702343436eb Mon Sep 17 00:00:00 2001 From: Connor Date: Mon, 10 Jan 2022 20:10:25 -0600 Subject: [PATCH] Add go-sockaddr examples for multiple interfaces (#11998) * Add overview example for multiple interfaces with go-sockaddr * Include go-sockaddr examples in agent configuration * Add changelog entry * Make suggested changes * Simplify hcl comment * Update link and fix gRPC * Switch index.mdx from Tabs to CodeTabs * Reformat new links for screen readers * Apply suggestions from code review Co-authored-by: mrspanishviking * Fix spacing in code block Co-authored-by: mrspanishviking --- website/content/docs/agent/index.mdx | 83 +++++++++++++++++++------- website/content/docs/agent/options.mdx | 35 ++++++++++- 2 files changed, 95 insertions(+), 23 deletions(-) diff --git a/website/content/docs/agent/index.mdx b/website/content/docs/agent/index.mdx index 8e67dbca1..a19c1e312 100644 --- a/website/content/docs/agent/index.mdx +++ b/website/content/docs/agent/index.mdx @@ -193,11 +193,9 @@ The following settings are commonly used in the configuration file (also called The following example configuration is for a server agent named "`consul-server`". The server is [bootstrapped](/docs/agent/options#_bootstrap) and the Consul GUI is enabled. The reason this server agent is configured for a service mesh is that the `connect` configuration is enabled. Connect is Consul's service mesh component that provides service-to-service connection authorization and encryption using mutual Transport Layer Security (TLS). Applications can use sidecar proxies in a service mesh configuration to establish TLS connections for inbound and outbound connections without being aware of Connect at all. See [Connect](/docs/connect) for details. - - + ```hcl - node_name = "consul-server" server = true bootstrap = true @@ -215,8 +213,6 @@ connect { } ``` - - ```json { @@ -238,19 +234,16 @@ connect { } ``` - - + ### Server Node with Encryption Enabled The following example shows a server node configured with encryption enabled. Refer to the [Security](/docs/security) chapter for additional information about how to configure security options for Consul. - - + ```hcl - node_name = "consul-server" server = true ui_config { @@ -274,8 +267,6 @@ key_file = "/consul/config/certs/dc1-server-consul-0-key.pem" ``` - - ```json { @@ -299,19 +290,16 @@ key_file = "/consul/config/certs/dc1-server-consul-0-key.pem" } ``` - - + ### Client Node Registering a Service Using Consul as a central service registry is a common use case. The following example configuration includes common settings to register a service with a Consul agent and enable health checks (see [Checks](/docs/discovery/checks) to learn more about health checks): - - + ```hcl - node_name = "consul-client" server = false datacenter = "dc1" @@ -335,9 +323,6 @@ service { ``` - - - ```json { "node_name": "consul-client", @@ -363,8 +348,58 @@ service { } ``` - - + + +## Client Node with Multiple Interfaces or IP addresses + +The following example shows how to configure Consul to listen on multiple interfaces or IP addresses using a [go-sockaddr template]. + +The `bind_addr` is used for internal RPC and Serf communication ([read the Agent Configuration for more information](/docs/agent/options#bind_addr)). + +The `client_addr` configuration specifies IP addresses used for HTTP, HTTPS, DNS and gRPC servers. ([read the Agent Configuration for more information](/docs/agent/options#client_addr)). + + + +```hcl +node_name = "consul-server" +server = true +bootstrap = true +ui_config { + enabled = true +} +datacenter = "dc1" +data_dir = "consul/data" +log_level = "INFO" + +# used for internal RPC and Serf +bind_addr = "0.0.0.0" + +# Used for HTTP, HTTPS, DNS, and gRPC addresses. +# loopback is not included in GetPrivateInterfaces because it is not routable. +client_addr = "{{ GetPrivateInterfaces | exclude \"type\" \"ipv6\" | join \"address\" \" \" }} {{ GetAllInterfaces | include \"flags\" \"loopback\" | join \"address\" \" \" }}" + +# advertises gossip and RPC interface to other nodes +advertise_addr = "{{ GetInterfaceIP \"en0\" }}" +``` + +```json +{ + "node_name": "consul-server", + "server": true, + "bootstrap": true, + "ui_config": { + "enabled": true + }, + "datacenter": "dc1", + "data_dir": "consul/data", + "log_level": "INFO", + "bind_addr": "{{ GetPrivateIP }}", + "client_addr": "{{ GetPrivateInterfaces | exclude \"type\" \"ipv6\" | join \"address\" \" \" }} {{ GetAllInterfaces | include \"flags\" \"loopback\" | join \"address\" \" \" }}", + "advertise_addr": "{{ GetInterfaceIP \"en0\"}}" +} +``` + + ## Stopping an Agent @@ -402,3 +437,7 @@ from the load balancer pool. The [`skip_leave_on_interrupt`](/docs/agent/options#skip_leave_on_interrupt) and [`leave_on_terminate`](/docs/agent/options#leave_on_terminate) configuration options allow you to adjust this behavior. + + + +[go-sockaddr template]: https://godoc.org/github.com/hashicorp/go-sockaddr/template diff --git a/website/content/docs/agent/options.mdx b/website/content/docs/agent/options.mdx index 78149a43f..33930d225 100644 --- a/website/content/docs/agent/options.mdx +++ b/website/content/docs/agent/options.mdx @@ -66,6 +66,15 @@ The options below are all specified on the command-line. state as other nodes will treat the non-routability as a failure. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] template that is resolved at runtime. + + + ```shell + # Using a static network interface name + $ consul agent -advertise '{{ GetInterfaceIP "eth0" }}' + ``` + + + - `-advertise-wan` ((#\_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`](#translate_wan_addrs) configuration option. By default, the [`-advertise`](#_advertise) address @@ -139,11 +148,35 @@ The options below are all specified on the command-line. capture, it is possible to use [`discard_check_output`](#discard_check_output). - `-client` ((#\_client)) - The address to which Consul will bind client - interfaces, including the HTTP and DNS servers. By default, this is "127.0.0.1", + interfaces, including the HTTP, HTTPS, gRPC and DNS servers. By default, this is "127.0.0.1", allowing only loopback connections. In Consul 1.0 and later this can be set to a space-separated list of addresses to bind to, or a [go-sockaddr] template that can potentially resolve to multiple addresses. + + + ```shell + $ consul agent -dev -client '{{ GetPrivateInterfaces | exclude "type" "ipv6" | join "address" " " }}' + ``` + + + + + + ```shell + $ consul agent -dev -client '{{ GetPrivateInterfaces | join "address" " " }} {{ GetAllInterfaces | include "flags" "loopback" | join "address" " " }}' + ``` + + + + + + ```shell + $ consul agent -dev -client '{{ GetPrivateInterfaces | exclude "name" "br.*" | join "address" " " }}' + ``` + + + - `-config-file` ((#\_config_file)) - A configuration file to load. For more information on the format of this file, read the [Configuration Files](#configuration_files) section. This option can be specified multiple times to load multiple configuration