From ba0dfb5ab8d11914dc17ae455c6a1c28d3b48d37 Mon Sep 17 00:00:00 2001
From: Bobby Iliev <bobby@bobbyiliev.com>
Date: Wed, 29 Jan 2025 11:15:50 +0200
Subject: [PATCH 1/2] doc: add ports aliugment note in Kafka privatelink guide

---
 .../layouts/shortcodes/network-security/privatelink-kafka.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/doc/user/layouts/shortcodes/network-security/privatelink-kafka.md b/doc/user/layouts/shortcodes/network-security/privatelink-kafka.md
index 48c48d57286c6..dd7b69b348f9b 100644
--- a/doc/user/layouts/shortcodes/network-security/privatelink-kafka.md
+++ b/doc/user/layouts/shortcodes/network-security/privatelink-kafka.md
@@ -151,4 +151,7 @@ CREATE CONNECTION kafka_connection TO KAFKA (
 );
 ```
 
-The `(PORT <port_number>)` value must match the port that you used when creating the **TCP listener** in the Network Load Balancer. Be sure to specify the correct availability zone for each broker.
+There are a few important things to note:
+
+* The `(PORT <port_number>)` value must exactly match the port assigned to the corresponding broker in the **TCP listener** of the Network Load Balancer. Misalignment between ports and broker addresses will result in connectivity issues.
+* For same-region connections, be sure to specify the correct availability zone for each broker as well.

From c9c657fe0a38393f7260d55367e153aef0318043 Mon Sep 17 00:00:00 2001
From: morsapaes <marta.paes.moreira@gmail.com>
Date: Tue, 4 Feb 2025 13:46:35 +0100
Subject: [PATCH 2/2] Minor updates

---
 .../content/ingest-data/postgres/amazon-rds.md |  4 ++--
 .../network-security/privatelink-kafka.md      | 18 ++++++++++++++----
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/doc/user/content/ingest-data/postgres/amazon-rds.md b/doc/user/content/ingest-data/postgres/amazon-rds.md
index 95745e58a8c58..1774f221f2656 100644
--- a/doc/user/content/ingest-data/postgres/amazon-rds.md
+++ b/doc/user/content/ingest-data/postgres/amazon-rds.md
@@ -379,7 +379,7 @@ start by selecting the relevant option.
    command to create an **in-region** or **cross-region** AWS PrivateLink
    connection.
 
-    **In-region connections**
+    ↕️ **In-region connections**
 
     To connect to an AWS PrivateLink endpoint service in the **same region** as your
     Materialize environment:
@@ -402,7 +402,7 @@ start by selecting the relevant option.
       subnet, look for **Availability Zone ID** (e.g., `use1-az6`),
       not **Availability Zone** (e.g., `us-east-1d`).
 
-    **Cross-region connections**
+    ↔️ **Cross-region connections**
 
     To connect to an AWS PrivateLink endpoint service in a **different region** to
     the one where your Materialize environment is deployed:
diff --git a/doc/user/layouts/shortcodes/network-security/privatelink-kafka.md b/doc/user/layouts/shortcodes/network-security/privatelink-kafka.md
index dd7b69b348f9b..bb515bd1e2566 100644
--- a/doc/user/layouts/shortcodes/network-security/privatelink-kafka.md
+++ b/doc/user/layouts/shortcodes/network-security/privatelink-kafka.md
@@ -134,11 +134,14 @@ If no validation error is returned, move to the next step.
 
 ## Create a source connection
 
-In Materialize, create a source connection that uses the AWS PrivateLink connection you just configured:
+In Materialize, create a source connection that uses the AWS PrivateLink
+connection you just configured:
 
 ```mzsql
 CREATE CONNECTION kafka_connection TO KAFKA (
     BROKERS (
+        -- The port **must exactly match** the port assigned to the broker in
+        -- the TCP listerner of the NLB.
         'b-1.hostname-1:9096' USING AWS PRIVATELINK privatelink_svc (PORT 9001, AVAILABILITY ZONE 'use1-az2'),
         'b-2.hostname-2:9096' USING AWS PRIVATELINK privatelink_svc (PORT 9002, AVAILABILITY ZONE 'use1-az1'),
         'b-3.hostname-3:9096' USING AWS PRIVATELINK privatelink_svc (PORT 9003, AVAILABILITY ZONE 'use1-az4')
@@ -151,7 +154,14 @@ CREATE CONNECTION kafka_connection TO KAFKA (
 );
 ```
 
-There are a few important things to note:
+### Troubleshooting
 
-* The `(PORT <port_number>)` value must exactly match the port assigned to the corresponding broker in the **TCP listener** of the Network Load Balancer. Misalignment between ports and broker addresses will result in connectivity issues.
-* For same-region connections, be sure to specify the correct availability zone for each broker as well.
+If you run into connectivity issues during source creation, make sure that:
+
+* The `(PORT <port_number>)` value **exactly matches** the port assigned to the
+  corresponding broker in the **TCP listener** of the Network Load Balancer.
+  Misalignment between ports and broker addresses is the most common cause for
+  connectivity issues.
+
+* For **in-region connections**, the correct availability zone is specified for
+  each broker.