From 359d8adeb10ae75586d856b008493307f9dd6278 Mon Sep 17 00:00:00 2001
From: Jamil <jamilbk@users.noreply.github.com>
Date: Wed, 24 Jan 2024 11:13:10 -0800
Subject: [PATCH] docs(gateway): Document egress connectivity requirements for
 Gateways (#3312)

Had a customer troubleshooting session today where it would have been
helpful to provide connectivity info that gateways require to function.
---
 .../apps/web/lib/web/live/sites/new_token.ex  | 15 +++++++++-----
 website/src/app/kb/deploy/gateways/readme.mdx | 20 ++++++++++++++++++-
 2 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/elixir/apps/web/lib/web/live/sites/new_token.ex b/elixir/apps/web/lib/web/live/sites/new_token.ex
index 2fdb1348c..4230880e8 100644
--- a/elixir/apps/web/lib/web/live/sites/new_token.ex
+++ b/elixir/apps/web/lib/web/live/sites/new_token.ex
@@ -41,11 +41,16 @@ defmodule Web.Sites.NewToken do
         Deploy a new Gateway
       </:title>
       <:help>
-        Gateways require outbound access to <code
-          class="text-sm bg-neutral-600 text-white px-1 py-0.5 rounded"
-          phx-no-format
-        >api.firezone.dev:443</code> only. <strong>No inbound firewall rules</strong>
-        are required or recommended.
+        Gateways require egress connectivity to the control plane API and relay servers.
+        <strong>No ingress firewall rules</strong>
+        are required or recommended. See our
+        <.link
+          href="https://www.firezone.dev/kb/deploy/gateways#firewall-considerations?utm_source=product"
+          class={link_style()}
+        >
+          deploy guide
+        </.link>
+        for more information.
       </:help>
       <:help>
         <.link
diff --git a/website/src/app/kb/deploy/gateways/readme.mdx b/website/src/app/kb/deploy/gateways/readme.mdx
index 9b2ad833a..c6baf993f 100644
--- a/website/src/app/kb/deploy/gateways/readme.mdx
+++ b/website/src/app/kb/deploy/gateways/readme.mdx
@@ -13,6 +13,24 @@ within the same site as the gateway.
 - Docker Engine (for docker-based installs)
 - Systemd (for systemd-based installs)
 
+## Firewall considerations
+
+Gateways implement the industry-standard
+[STUN](https://datatracker.ietf.org/doc/html/rfc8489) and
+[TURN](https://www.rfc-editor.org/rfc/rfc8155.html) protocols to securely
+perform NAT traversal and firewall hole-punching. No ingress firewall ports are
+required for Gateways to function.
+
+If the network in which your Gateway is deployed performs egress filtering,
+you'll need to make sure the following outbound traffic is allowed:
+
+| Host             | (IP Address)         | Port(s)         | Protocol(s)     | Purpose                    |
+| ---------------- | -------------------- | --------------- | --------------- | -------------------------- |
+| api.firezone.dev | `34.102.202.25`      | `443`           | HTTPS/WebSocket | Control Plane API (IPv4)   |
+| api.firezone.dev | `2600:1901:0:620b::` | `443`           | HTTPS/WebSocket | Control Plane API (IPv6)   |
+| N/A              | Varies               | `3478`          | STUN            | STUN protocol signaling    |
+| N/A              | Varies               | `49152 - 65535` | TURN            | TURN protocol channel data |
+
 ## Resource considerations
 
 Gateways, like the rest of Firezone's data plane stack, are written in Rust and
@@ -28,7 +46,7 @@ optimizations, both of which are currently being worked on.
 
 ## Deploy a single gateway
 
-Deployed a single gateway can be accomplished in the admin portal.
+Deploying a single gateway can be accomplished in the admin portal.
 
 Go to `Sites` -> `<site>` -> `Deploy a Gateway` and follow the prompts to deploy
 for your preferred environment. This will deploy a single gateway.