Skip to content

docs: PrivateLink troubleshooting for NLB security group enforcement #36623

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
materializekatrina wants to merge 1 commit into
base: main
Choose a base branch
from
+9 −3
Open

docs: PrivateLink troubleshooting for NLB security group enforcement #36623

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion doc/user/layouts/shortcodes/network-security/privatelink-kafka.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,12 @@ and retrieve the AWS principal needed to configure the AWS PrivateLink service.

**Remarks**:

a. Network Load Balancers do not have associated security groups. Therefore, the security groups for your targets must use IP addresses to allow traffic.
a. Network Load Balancers do not have associated security groups by default. Therefore, the security groups for your targets must use IP addresses to allow traffic.
Copy link
Copy Markdown
Contributor

@kay-kim kay-kim May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Double-checking ... this is pre-change content ... but since we're here:
The "Therefore, " sentence , is this the same or different as point b) below?

Will also ask Justin.


b. You can't use the security groups for the clients as a source in the security groups for the targets. Therefore, the security groups for your targets must use the IP addresses of the clients to allow traffic. For more details, check the [AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-register-targets.html).

c. If you have associated a [security group with your Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-security-groups.html) and enabled **Enforce inbound rules on PrivateLink traffic**, the NLB's inbound rules will be applied to traffic arriving from Materialize's VPC endpoint. In that case, the source IPs are private IPs from Materialize's VPC — **not** the IPs of any client (e.g., `kcat` or a Kafka client running from a workstation or bastion host) that you might use to verify connectivity to the brokers directly. Inbound rules that only permit your own test traffic will silently block Materialize, even when your own connectivity tests succeed. To resolve this, either disable **Enforce inbound rules on PrivateLink traffic**, or add inbound rules to the NLB's security group that permit the relevant ports (each broker's listener port and the health check port) from a source that covers Materialize's VPC endpoint traffic.
Copy link
Copy Markdown
Contributor

@kay-kim kay-kim May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So ... we seem to be modifying content shown on
https://preview.materialize.com/materialize/36623/ingest-data/network-security/privatelink/

Did we want to update the content in https://preview.materialize.com/materialize/36623/ingest-data/postgres/amazon-rds/#b-optional-configure-network-security page and such?

Copy link
Copy Markdown
Contributor

@kay-kim kay-kim May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, maybe make it leaner? And perhaps list the disabling to be the second bullet point(?) since it seems kind of permissive for all inbound traffic and not just materialize's traffic.

If you have associated a security group with your Network Load Balancer and
enabled **Enforce inbound rules on PrivateLink traffic**, the security group's
inbound rules also apply to traffic from Materialize's VPC endpoint. Any traffic
not explicitly permitted, including Materialize's, will be silently blocked.

To resolve this either:
- Add inbound rules to the NLB's security group that permit the listener port
  and the health check port from a source covering Materialize's VPC endpoint
  traffic, or
- Disable **Enforce inbound rules on PrivateLink traffic**.


1. Create a VPC [endpoint service](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html) and associate it with the **Network Load Balancer** that you’ve just created.

Note the **service name** that is generated for the endpoint service.
Expand Down
4 changes: 3 additions & 1 deletion doc/user/layouts/shortcodes/network-security/privatelink-mysql.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,12 @@

**Remarks**:

a. Network Load Balancers do not have associated security groups. Therefore, the security groups for your targets must use IP addresses to allow traffic.
a. Network Load Balancers do not have associated security groups by default. Therefore, the security groups for your targets must use IP addresses to allow traffic.

b. You can't use the security groups for the clients as a source in the security groups for the targets. Therefore, the security groups for your targets must use the IP addresses of the clients to allow traffic. For more details, check the [AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-register-targets.html).

c. If you have associated a [security group with your Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-security-groups.html) and enabled **Enforce inbound rules on PrivateLink traffic**, the NLB's inbound rules will be applied to traffic arriving from Materialize's VPC endpoint. In that case, the source IPs are private IPs from Materialize's VPC — **not** the IPs of any client (e.g., `mysql` running from a workstation or bastion host) that you might use to verify connectivity to the database directly. Inbound rules that only permit your own test traffic will silently block Materialize, even when your own connectivity tests succeed. To resolve this, either disable **Enforce inbound rules on PrivateLink traffic**, or add inbound rules to the NLB's security group that permit the relevant ports (the listener port and the health check port) from a source that covers Materialize's VPC endpoint traffic.

1. #### Create a Network Load Balancer (NLB)
Create a [Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-network-load-balancer.html) that is **enabled for the same subnets** that the RDS instance is in.

Expand Down
4 changes: 3 additions & 1 deletion doc/user/layouts/shortcodes/network-security/privatelink-postgres.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,12 @@

**Remarks**:

a. Network Load Balancers do not have associated security groups. Therefore, the security groups for your targets must use IP addresses to allow traffic.
a. Network Load Balancers do not have associated security groups by default. Therefore, the security groups for your targets must use IP addresses to allow traffic.

b. You can't use the security groups for the clients as a source in the security groups for the targets. Therefore, the security groups for your targets must use the IP addresses of the clients to allow traffic. For more details, check the [AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-register-targets.html).

c. If you have associated a [security group with your Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-security-groups.html) and enabled **Enforce inbound rules on PrivateLink traffic**, the NLB's inbound rules will be applied to traffic arriving from Materialize's VPC endpoint. In that case, the source IPs are private IPs from Materialize's VPC — **not** the IPs of any client (e.g., `psql` running from a workstation or bastion host) that you might use to verify connectivity to the database directly. Inbound rules that only permit your own test traffic will silently block Materialize, even when your own connectivity tests succeed. To resolve this, either disable **Enforce inbound rules on PrivateLink traffic**, or add inbound rules to the NLB's security group that permit the relevant ports (the listener port and the health check port) from a source that covers Materialize's VPC endpoint traffic.

1. #### Create a Network Load Balancer (NLB)
Create a [Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-network-load-balancer.html) that is **enabled for the same subnets** that the RDS or Aurora instance is in.

Expand Down
Loading