From 86cc952e7fc38815844b5e108ae3107e9aba9818 Mon Sep 17 00:00:00 2001
From: Luke Kysow <1034429+lkysow@users.noreply.github.com>
Date: Mon, 14 Jun 2021 09:15:40 -0700
Subject: [PATCH] Update k8s term gateway docs to make address clear (#10389)

Previously if you were to follow these docs and register two external
services, you would set the Address field on the node. The second
registered service would change the address of the node for the first
service.

Now the docs explain the address key and how to register more than one
external service.
---
 .../docs/k8s/connect/terminating-gateways.mdx    | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/website/content/docs/k8s/connect/terminating-gateways.mdx b/website/content/docs/k8s/connect/terminating-gateways.mdx
index 2f065e39a9..d68c1897c2 100644
--- a/website/content/docs/k8s/connect/terminating-gateways.mdx
+++ b/website/content/docs/k8s/connect/terminating-gateways.mdx
@@ -84,17 +84,23 @@ Registering the external services with Consul is a multi-step process:
 
 ### Register external services with Consul
 
+-> **Note:** Normal Consul services are registered with the Consul client on the node that
+they're running on. Since this is an external service, there is no Consul node
+to register it onto. Instead, we will make up a node name and register the
+service to that node.
+
 Create a sample external service and register it with Consul.
 
 ```json
 {
-  "Node": "legacy_node",
+  "Node": "example_com",
   "Address": "example.com",
   "NodeMeta": {
     "external-node": "true",
     "external-probe": "true"
   },
   "Service": {
+    "Address": "example.com",
     "ID": "example-https",
     "Service": "example-https",
     "Port": 443
@@ -102,6 +108,14 @@ Create a sample external service and register it with Consul.
 }
 ```
 
+- `"Node": "example_com"` is our made up node name.
+- `"Address": "example.com"` is the address of our node. Services registered to that node will use this address if
+  their own address isn't specified. If you're registering multiple external services, ensure you
+  use different node names with different addresses or set the `Service.Address` key.
+- `"Service": { "Address": "example.com" ... }` is the address of our service. In this example this doesn't need to be set
+  since the address of the node is the same, but if there were two services registered to that same node
+  then this should be set.
+
 Register the external service with Consul:
 
 ```shell-session