From 373fb7f4354cd7a3ef7360b9b76b3a17dce01aba Mon Sep 17 00:00:00 2001
From: Blake Covarrubias <blake@covarrubi.as>
Date: Tue, 29 Jun 2021 10:57:33 -0700
Subject: [PATCH] docs: Clarify serf_lan/retry_join behavior with network
 segments (#10386)

* docs: Add info on using cloud auto-join with Network Segments

Resolves hashicorp/go-discover#57

* Add note about joining network segments

Specifically call out that agents can be configured to join a network
segment by either specifying the Serf LAN port in the join address,
changing the agent's default Serf LAN port by configuring
`ports.serf_lan`, or specifying the port in the `-serf-lan-port`
command line flag.

Resolves #9972
---
 website/content/docs/agent/options.mdx        | 17 ++++--
 .../content/docs/install/cloud-auto-join.mdx  | 57 +++++++++++++++++++
 2 files changed, 70 insertions(+), 4 deletions(-)

diff --git a/website/content/docs/agent/options.mdx b/website/content/docs/agent/options.mdx
index d4c49811b1..04e42a035b 100644
--- a/website/content/docs/agent/options.mdx
+++ b/website/content/docs/agent/options.mdx
@@ -307,8 +307,11 @@ The options below are all specified on the command-line.
   specify multiple agents to join. The value can contain IPv4, IPv6, or DNS
   addresses. In Consul 1.1.0 and later this can be set to a
   [go-sockaddr](https://godoc.org/github.com/hashicorp/go-sockaddr/template)
-  template. If Consul is running on the non-default Serf LAN port, this must be
-  specified as well. IPv6 must use the "bracketed" syntax. If multiple values
+  template. If Consul is running on the non-default Serf LAN port, the port must
+  be specified in the join address, or configured as the agent's default Serf port
+  using the [`ports.serf_lan`](#serf_lan_port) configuration option or
+  [`-serf-lan-port`](#_serf_lan_port) command line flag.
+  IPv6 must use the "bracketed" syntax. If multiple values
   are given, they are tried and retried in the order listed until the first
   succeeds. Here are some examples:
 
@@ -322,6 +325,11 @@ The options below are all specified on the command-line.
   $ consul agent -retry-join "10.0.4.67"
   ```
 
+  ```shell
+  # Using a non-default Serf LAN port
+  $ consul agent -retry-join "192.0.2.10:8304"
+  ```
+
   ```shell
   # Using IPv6
   $ consul agent -retry-join "[::1]:8301"
@@ -1719,8 +1727,9 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
     in `-dev` mode. Currently gRPC is only used to expose Envoy xDS API to Envoy
     proxies.
   - `serf_lan` ((#serf_lan_port)) - The Serf LAN port. Default 8301. TCP
-    and UDP.
-  - `serf_wan` ((#serf_wan_port)) - The Serf WAN port. Default 8302. Set
+    and UDP. Equivalent to the [`-serf-lan-port` command line flag](#_serf_lan_port).
+  - `serf_wan` ((#serf_wan_port)) - The Serf WAN port. Default 8302.
+    Equivalent to the [`-serf-wan-port` command line flag](#_serf_wan_port). Set
     to -1 to disable. **Note**: this will disable WAN federation which is not recommended.
     Various catalog and WAN related endpoints will return errors or empty results.
     TCP and UDP.
diff --git a/website/content/docs/install/cloud-auto-join.mdx b/website/content/docs/install/cloud-auto-join.mdx
index 259cb7714b..3362aa9936 100644
--- a/website/content/docs/install/cloud-auto-join.mdx
+++ b/website/content/docs/install/cloud-auto-join.mdx
@@ -33,6 +33,63 @@ or via a configuration file:
 }
 ```
 
+## Auto-join with Network Segments <EnterpriseAlert inline />
+
+In order to use cloud auto-join with [Network Segments](/docs/enterprise/network-segments),
+you must reconfigure the Consul agent's Serf LAN port to match that of the
+segment you wish to join.
+
+For example, given the following segment configuration on the server agents:
+
+```hcl
+# server-config.hcl
+segments = [
+  {
+    name = "alpha"
+    bind = "{{GetPrivateIP}}"
+    advertise = "{{GetPrivateIP}}"
+    port = 8303
+  },
+  {
+    name = "beta"
+    bind = "{{GetPrivateIP}}"
+    advertise = "{{GetPrivateIP}}"
+    port = 8304
+  }
+]
+```
+
+A Consul client agent wishing to join the "alpha" segment would need to be configured
+to use port `8303` as its Serf LAN port prior to attempting to join the cluster.
+
+<Tabs>
+<Tab heading="Agent configuration">
+
+The following example configuration overrides the default Serf LAN port using the
+[`ports.serf_lan`](/docs/agent/options#serf_lan_port) configuration option.
+
+```hcl
+# client-config.hcl
+ports {
+  serf_lan = 8303
+}
+```
+
+</Tab>
+<Tab heading="Command-line flag">
+
+The following example overrides the default Serf LAN port using the
+[`-serf-lan-port`](/docs/agent/options#_serf_lan_port) command line flag.
+
+```shell
+$ consul agent -serf-lan-port=8303 -retry-join "provider=..."
+```
+
+</Tab>
+</Tabs>
+
+## Provider-specific configurations
+
 The cloud provider-specific configurations are detailed below. This can be
 combined with static IP or DNS addresses or even multiple configurations
 for different providers.