Migration: update BYOC PrivateLink setup for AWS and GCP

products/bring-your-own-cloud/onboarding/network-aws.mdx

@@ -13,10 +13,13 @@ ClickHouse BYOC on AWS supports two private connection options including VPC Pee
 
 ## Prerequisites {#common-prerequisites}
 
-Common steps required by both VPC peering and Privatelink.
+Common steps required by both VPC peering and PrivateLink.
 
 ### Enable private load balancer for ClickHouse BYOC {#step-enable-private-load-balancer-for-clickhouse-byoc}
-Contact ClickHouse Support to enable Private Load Balancer.
+
+In the ClickHouse Cloud console, enable the **Private load balancer** for your BYOC infrastructure.
+
+<Image img="/images/cloud/reference/byoc-private-load-balancer.png" size="md" alt="BYOC Enable Private Load Balancer" border />
 
 ## Set up VPC peering {#aws-vpc-peering}
 
@@ -25,6 +28,7 @@ To create or delete VPC peering for ClickHouse BYOC, follow the steps:
 <Steps>
 <Step>
 ### Create a peering connection {#step-1-create-a-peering-connection}
+
 1. Navigate to the VPC Dashboard in ClickHouse BYOC account.
 2. Select Peering Connections.
 3. Click Create Peering Connection
@@ -36,13 +40,16 @@ To create or delete VPC peering for ClickHouse BYOC, follow the steps:
 </Step>
 <Step>
 ### Accept the peering connection request {#step-2-accept-the-peering-connection-request}
+
 Go to the peering account, in the (VPC -> Peering connections -> Actions -> Accept request) page customer can approve this VPC peering request.
 
 <Image img="/images/cloud/reference/byoc-vpcpeering-2.png" size="lg" alt="BYOC Accept Peering Connection" border />
 </Step>
 <Step>
 ### Add destination to ClickHouse VPC route tables {#step-3-add-destination-to-clickhouse-vpc-route-tables}
+
 In ClickHouse BYOC account,
+
 1. Select Route Tables in the VPC Dashboard.
 2. Search for the ClickHouse VPC ID. Edit each route table attached to the private subnets.
 3. Click the Edit button under the Routes tab.
@@ -54,7 +61,9 @@ In ClickHouse BYOC account,
 </Step>
 <Step>
 ### Add destination to the target VPC route tables {#step-4-add-destination-to-the-target-vpc-route-tables}
+
 In the peering AWS account,
+
 1. Select Route Tables in the VPC Dashboard.
 2. Search for the target VPC ID.
 3. Click the Edit button under the Routes tab.
@@ -70,107 +79,105 @@ In the peering AWS account,
 In the ClickHouse BYOC account, you need to update the Security Group settings to allow traffic from your peered VPC. Please contact ClickHouse Support to request the addition of inbound rules that include the CIDR ranges of your peered VPC.
 
 ---
+
 The ClickHouse service should now be accessible from the peered VPC.
 </Step>
 </Steps>
 
 To access ClickHouse privately, a private load balancer and endpoint are provisioned for secure connectivity from the user's peered VPC. The private endpoint follows the public endpoint format with a `-private` suffix. For example:
+
 - **Public endpoint**: `h5ju65kv87.mhp0y4dmph.us-west-2.aws.byoc.clickhouse.cloud`
 - **Private endpoint**: `h5ju65kv87-private.mhp0y4dmph.us-west-2.aws.byoc.clickhouse.cloud`
 
 Optional, after verifying that peering is working, you can request the removal of the public load balancer for ClickHouse BYOC.
 
 ## Set up PrivateLink {#setup-privatelink}
 
-AWS PrivateLink provides secure, private connectivity to your ClickHouse BYOC services without requiring VPC peering or internet gateways. Traffic flows entirely within the AWS network, never traversing the public internet.
+AWS PrivateLink provides a secure and private connection to your ClickHouse BYOC services without the need for VPC peering or internet gateways. All traffic flows within the AWS network, ensuring that it never traverses the public internet.
 
 <Steps>
 <Step>
-### Request PrivateLink Setup {#step-1-request-privatelink-setup}
+### Enable private link in ClickHouse console {#step-1-enable-private-link}
 
-Contact [ClickHouse Support](https://clickhouse.com/cloud/bring-your-own-cloud) to request PrivateLink setup for your BYOC deployment. No specific information is required at this stage—simply indicate that you want to set up PrivateLink connectivity.
+<Note>
+Make sure the **private load balancer** is turned on as a prerequisite.
+</Note>
 
-ClickHouse Support will enable the necessary infrastructure components, including **the private load balancer** and **PrivateLink service endpoint**.
+<Image img="/images/cloud/reference/byoc-privatelink.png" size="md" alt="BYOC PrivateLink Enable" border />
 </Step>
 <Step>
-### Create an Endpoint in Your VPC {#step-2-create-endpoint}
-
-After ClickHouse Support has enabled PrivateLink on their side, you need to create a VPC endpoint in your client application VPC to connect to the ClickHouse PrivateLink service.
-
-1. **Obtain the Endpoint Service Name**:
-   - ClickHouse Support will provide you with the Endpoint Service name
-   - You can also find it in the AWS VPC console under "Endpoint Services" (filter by service name or look for ClickHouse services)
-
-<Image img="/images/cloud/reference/byoc-privatelink-1.png" size="lg" alt="BYOC PrivateLink Service Endpoint" border />
-
-2. **Create the VPC Endpoint**:
-   - Navigate to the AWS VPC Console → Endpoints → Create Endpoint
-   - Select "Find service by name" and enter the Endpoint Service name provided by ClickHouse Support
-   - Choose your VPC and select subnets (one per availability zone is recommended)
-   - **Important**: Enable "Private DNS names" for the endpoint—this is required for DNS resolution to work correctly
-   - Select or create a security group for the endpoint
-   - Click "Create Endpoint"
-
-<Warning>
-**DNS Requirements**:
-- Enable "Private DNS names" when creating the VPC endpoint
-- Ensure your VPC has "DNS Hostnames" enabled (VPC Settings → DNS resolution and DNS hostnames)
+### Obtain endpoint "Service name" {#step-2-obtain-endpoint-service-name}
 
-These settings are required for the PrivateLink DNS to function correctly.
-</Warning>
-
-3. **Approve the Endpoint Connection**:
-   - After creating the endpoint, you need to approve the connection request
-   - In the VPC Console, go to "Endpoint Connections"
-   - Find the connection request from ClickHouse and click "Accept" to approve it
-
-<Image img="/images/cloud/reference/byoc-privatelink-2.png" size="lg" alt="BYOC PrivateLink Approve" border />
+1. In the ClickHouse Cloud console, navigate to the service's Settings page that you would like to connect to via PrivateLink.
+2. Click "Set up private endpoint".
+3. In the opened flyout, copy the `Service name` value — you'll use it in the next step. (It may take a while for the value to be generated after enabling PrivateLink.)
+   <Image img="/images/cloud/security/aws-privatelink-pe-create.png" size="md" alt="Private Endpoints" border />
 </Step>
 <Step>
-### Add Endpoint ID to Service Allowlist {#step-3-add-endpoint-id-allowlist}
-
-Once your VPC endpoint is created and the connection is approved, you need to add the Endpoint ID to the allowlist for each ClickHouse service you want to access via PrivateLink.
-
-1. **Obtain your Endpoint ID**:
-   - In the AWS VPC Console, go to Endpoints
-   - Select your newly created endpoint
-   - Copy the Endpoint ID (it will look like `vpce-xxxxxxxxxxxxxxxxx`)
-
-2. **Contact ClickHouse Support**:
-   - Provide the Endpoint IDs to ClickHouse Support
-   - Specify which ClickHouse services should allow access from this endpoint
-   - ClickHouse Support will add the Endpoint ID to the service allowlist
+### Create endpoint in your network {#step-3-create-endpoint}
+
+1. Open your **own AWS console** (i.e. the AWS account where your client application is) → VPC → Endpoints → Create endpoints.
+2. Select "Endpoint services that use NLBs and GWLBs" and use `Service name` obtained from the last step.
+3. Click "Verify service".
+   <Image img="/images/cloud/security/aws-privatelink-endpoint-settings.png" size="md" alt="AWS PrivateLink Endpoint Settings" border/>
+4. (Optional) If you want to establish a cross-regional connection via PrivateLink, enable the "Cross region endpoint" checkbox and specify the service region. The service region is where your BYOC infrastructure is created. Meanwhile,
+   1. Open your **BYOC AWS console** (i.e. the AWS account where your BYOC infrastructure is created) → VPC → Endpoint services → `clickhouse-cloud-infra-xxx` → Supported regions.
+   2. Add the region where your client application is running to the supported regions list. By default, only the region of this BYOC infrastructure is supported. You can add multiple regions if you want to connect from different regions, and ClickHouse won't change or reset these values.
+      <Image img="/images/cloud/reference/byoc-privatelink-aws-cross-region.png" size="md" alt="AWS PrivateLink Cross Region Endpoint Settings" border/>
+5. Select your VPC and subnets (one per availability zone is recommended).
+   <Image img="/images/cloud/security/aws-privatelink-select-vpc-and-subnets.png" size="md" alt="Select VPC and subnets" border />
+6. **Important**: Enable "Private DNS names" for the endpoint — this is required for Private DNS to function correctly.
+   Private DNS for BYOC endpoints (using the `*.vpce.{subdomain}` format) leverages AWS PrivateLink's built-in "Private DNS names" feature. No Route53 records are required — DNS resolution happens automatically when:
+   - "Private DNS names" is enabled and
+   - "DNS Hostnames" is enabled
+
+     via VPC Settings → DNS resolution and DNS hostnames.
+
+     This ensures that connections using the `vpce` subdomain automatically route through the PrivateLink endpoint without additional DNS configuration.
+
+7. (Optional) Assign Security groups/Tags.
+   <Note>
+   Make sure that ports `443`, `8443`, `9440`, `3306` are allowed in the security group.
+   </Note>
+8. Click "Create endpoint", wait a moment for the endpoint to be created.
+9. After creating the endpoint, copy the `Endpoint ID` value — you'll use it in the next step.
+   <Image img="/images/cloud/security/aws-privatelink-vpc-endpoint-id.png" size="md" alt="VPC Endpoint ID" border />
 </Step>
 <Step>
-### Connect to ClickHouse via PrivateLink {#step-4-connect-via-privatelink}
+### Approve the endpoint connection {#step-4-approve-endpoint-connection}
 
-After the Endpoint ID is added to the allowlist, you can connect to your ClickHouse service using the PrivateLink endpoint.
-
-The PrivateLink endpoint format is similar to the public endpoint, but includes a `vpce` subdomain. For example:
-
-- **Public endpoint**: `h5ju65kv87.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`
-- **PrivateLink endpoint**: `h5ju65kv87.vpce.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`
-
-DNS resolution in your VPC will automatically route traffic through the PrivateLink endpoint when you use the `vpce` subdomain format.
+1. Open your **BYOC VPC console** again → Endpoint services → `clickhouse-cloud-infra-xxx` → Endpoint connections.
+2. Find the connection request created from your own VPC and click "Accept endpoint connection request" to approve it.
+   <Image img="/images/cloud/reference/byoc-privatelink-2.png" size="md" alt="BYOC PrivateLink Approve" border />
 </Step>
-</Steps>
-
-### PrivateLink Access Control {#privatelink-access-control}
-
-Access to ClickHouse services via PrivateLink is controlled at two levels:
+<Step>
+### Add "Endpoint ID" to ClickHouse service allow list {#step-5-add-endpoint-id-to-services-allow-list}
 
-1. **Istio Authorization Policy**: ClickHouse Cloud's service-level authorization policies
-2. **VPC Endpoint Security Group**: The security group attached to your VPC endpoint controls which resources in your VPC can use the endpoint
+1. In the ClickHouse Cloud console, navigate to the service's Settings page that you would like to connect to via PrivateLink.
+2. Click "Set up private endpoint".
+3. In the opened flyout, enter the `Endpoint ID` obtained from the last step with an optional description.
+4. Click "Create endpoint".
 
 <Note>
-The private load balancer's "Enforce inbound rules on PrivateLink traffic" feature is disabled, so access is controlled by Istio authorization policies and your VPC endpoint's security group only.
+If you want to allow access from an existing PrivateLink connection, use the existing endpoint dropdown menu.
+The dropdown will show the existing PrivateLink connections to the services within the same infrastructure.
 </Note>
+<Image img="/images/cloud/security/aws-privatelink-pe-filters.png" size="md" alt="Private Endpoints Filter" border/>
+</Step>
+<Step>
+### Access an instance using PrivateLink {#step-6-connect-via-privatelink}
 
-### PrivateLink DNS {#privatelink-dns}
-
-PrivateLink DNS for BYOC endpoints (using the `*.vpce.{subdomain}` format) leverages AWS PrivateLink's built-in "Private DNS names" feature. No Route53 records are required—DNS resolution happens automatically when:
+1. In the ClickHouse Cloud console, navigate to service's Settings page.
+2. Click "Set up private endpoint".
+3. In the opened flyout, copy the `DNS name`.
+   <Image img="/images/cloud/security/aws-privatelink-pe-dns-name.png" size="md" alt="Private Endpoint DNS Name" border />
 
-- "Private DNS names" is enabled on your VPC endpoint
-- Your VPC has "DNS Hostnames" enabled
+   Access to ClickHouse services via PrivateLink is controlled at two levels:
+   1. **Istio Authorization Policy**: ClickHouse Cloud's service-level authorization policies
+   2. **VPC Endpoint Security Group**: The security group attached to your VPC endpoint controls which resources in your VPC can use the endpoint
 
-This ensures that connections using the `vpce` subdomain automatically route through the PrivateLink endpoint without additional DNS configuration.
+   <Note>
+   The private load balancer's "Enforce inbound rules on PrivateLink traffic" feature is disabled, so access is controlled by Istio authorization policies and your VPC endpoint's security group only.
+   </Note>
+</Step>
+</Steps>