From b8ef47f6d6f214385695d5b1045fc7978746df8f Mon Sep 17 00:00:00 2001 From: freddygv Date: Tue, 18 Oct 2022 10:08:43 -0600 Subject: [PATCH 1/4] Add docs about upgrading primary mesh gateways Care must be taken when replacing mesh gateways in the primary datacenter, because if the old addresses become unreachable before the secondary datacenters receive the new addresses then the primary datacenter overall will become unreachable. This commit adds docs related to this class of upgrades. --- .../wan-federation-via-mesh-gateways.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx index 55a8194f54..3a995da947 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx @@ -184,3 +184,17 @@ expected result: - Ensure any API request that activates datacenter request forwarding. such as [`/v1/catalog/services?dc=`](/api-docs/catalog#dc-1) succeeds. + +### Upgrading the primary gateways + +Once federation has been established, updates for the addresses of new primary +gateways are propagated through the gateways in the primary themselves. If the primary +gateways are upgraded, and their previous instances are decommissioned before +the updates are propagated, then the primary datacenter will become unreachable. + +To safely upgrade primary gateways it is preferable to do one of the following: +- Avoid decommissioning primary gateway IP addresses, since the [primary_gateways](/docs/agent/config/config-files#primary_gateways) addresses configured on the secondary +servers acts as a fallback mechanism to re-establish connectivity to the primary. + +- Verify that addresses of the new mesh gateways in the primary were propagated +to the secondary datacenters before decommissioning the old mesh gateways in the primary. From b9fa83b72b3427e20797d552fc6ffc2262193926 Mon Sep 17 00:00:00 2001 From: Freddy Date: Fri, 21 Oct 2022 15:17:00 -0600 Subject: [PATCH 2/4] Update website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../mesh-gateway/wan-federation-via-mesh-gateways.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx index 3a995da947..5b30f0983d 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx @@ -192,9 +192,8 @@ gateways are propagated through the gateways in the primary themselves. If the p gateways are upgraded, and their previous instances are decommissioned before the updates are propagated, then the primary datacenter will become unreachable. -To safely upgrade primary gateways it is preferable to do one of the following: -- Avoid decommissioning primary gateway IP addresses, since the [primary_gateways](/docs/agent/config/config-files#primary_gateways) addresses configured on the secondary -servers acts as a fallback mechanism to re-establish connectivity to the primary. +To safely upgrade primary gateways, we recommend that you apply one of the following policies: +- Avoid decommissioning primary gateway IP addresses. This is because the [primary_gateways](/docs/agent/config/config-files#primary_gateways) addresses configured on the secondary servers act as a fallback mechanism for re-establishing connectivity to the primary. - Verify that addresses of the new mesh gateways in the primary were propagated to the secondary datacenters before decommissioning the old mesh gateways in the primary. From ca9df9c851ecf92979265c68188f07fff84ef317 Mon Sep 17 00:00:00 2001 From: freddygv Date: Fri, 21 Oct 2022 15:50:49 -0600 Subject: [PATCH 3/4] Clarify how addresses are propagated --- .../mesh-gateway/wan-federation-via-mesh-gateways.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx index 5b30f0983d..c35f5717b2 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx @@ -187,10 +187,12 @@ expected result: ### Upgrading the primary gateways -Once federation has been established, updates for the addresses of new primary -gateways are propagated through the gateways in the primary themselves. If the primary -gateways are upgraded, and their previous instances are decommissioned before -the updates are propagated, then the primary datacenter will become unreachable. +Once federation is established, secondary datacenters will continuously request +updated mesh gateway addresses from the primary datacenter. These requests +themselves flow through the mesh gateways of the primary datacenter, since +secondary datacenters cannot dial the primary datacenter's Consul servers directly. +If the primary gateways are upgraded, and their previous instances are decommissioned +before the updates are propagated, then the primary datacenter will become unreachable. To safely upgrade primary gateways, we recommend that you apply one of the following policies: - Avoid decommissioning primary gateway IP addresses. This is because the [primary_gateways](/docs/agent/config/config-files#primary_gateways) addresses configured on the secondary servers act as a fallback mechanism for re-establishing connectivity to the primary. From 72553b3499a153b9ca4c3b702b3fa8c0c0f0fc9c Mon Sep 17 00:00:00 2001 From: Freddy Date: Fri, 21 Oct 2022 16:43:40 -0600 Subject: [PATCH 4/4] Update website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../mesh-gateway/wan-federation-via-mesh-gateways.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx index c35f5717b2..1f8ca6eb79 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx @@ -188,9 +188,9 @@ expected result: ### Upgrading the primary gateways Once federation is established, secondary datacenters will continuously request -updated mesh gateway addresses from the primary datacenter. These requests -themselves flow through the mesh gateways of the primary datacenter, since -secondary datacenters cannot dial the primary datacenter's Consul servers directly. +updated mesh gateway addresses from the primary datacenter. Consul routes the requests + through the primary datacenter's mesh gateways. This is because +secondary datacenters cannot directly dial the primary datacenter's Consul servers. If the primary gateways are upgraded, and their previous instances are decommissioned before the updates are propagated, then the primary datacenter will become unreachable.