feat(doc): update BYOC PrivateLink setup docs and screenshots (AWS & GCP)

docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup/01_aws.md

@@ -8,21 +8,32 @@
 ---
 
 import Image from '@theme/IdealImage';
+import byoc_private_load_balancer from '@site/static/images/cloud/reference/byoc-private-load-balancer.png';
 import byoc_vpcpeering from '@site/static/images/cloud/reference/byoc-vpcpeering-1.png';
 import byoc_vpcpeering2 from '@site/static/images/cloud/reference/byoc-vpcpeering-2.png';
 import byoc_vpcpeering3 from '@site/static/images/cloud/reference/byoc-vpcpeering-3.png';
 import byoc_vpcpeering4 from '@site/static/images/cloud/reference/byoc-vpcpeering-4.png';
-import byoc_privatelink_1 from '@site/static/images/cloud/reference/byoc-privatelink-1.png';
+import byoc_privatelink from '@site/static/images/cloud/reference/byoc-privatelink.png';
+import byoc_privatelink_aws_cross_region from '@site/static/images/cloud/reference/byoc-privatelink-aws-cross-region.png';
+import aws_private_link_pecreate from '@site/static/images/cloud/security/aws-privatelink-pe-create.png';
+import aws_private_link_endpoint_settings from '@site/static/images/cloud/security/aws-privatelink-endpoint-settings.png';
+import aws_private_link_select_vpc from '@site/static/images/cloud/security/aws-privatelink-select-vpc-and-subnets.png';
+import aws_private_link_vpc_endpoint_id from '@site/static/images/cloud/security/aws-privatelink-vpc-endpoint-id.png';
 import byoc_privatelink_2 from '@site/static/images/cloud/reference/byoc-privatelink-2.png';
+import aws_private_link_pe_filters from '@site/static/images/cloud/security/aws-privatelink-pe-filters.png';
+import aws_private_link_ped_nsname from '@site/static/images/cloud/security/aws-privatelink-pe-dns-name.png';
 
 ClickHouse BYOC on AWS supports two private connection options including VPC Peering and AWS PrivateLink.
 
 ## 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={byoc_private_load_balancer} size="md" alt="BYOC Enable Private Load Balancer" border />
 
 ## Set up VPC peering {#aws-vpc-peering}
 
@@ -31,6 +42,7 @@
 <VerticalStepper headerLevel="h3">
 
 ### 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
@@ -41,12 +53,15 @@
 <Image img={byoc_vpcpeering} size="lg" alt="BYOC Create Peering Connection" border />
 
 ### 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={byoc_vpcpeering2} size="lg" alt="BYOC Accept Peering Connection" border />
 
 ### 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.
@@ -57,7 +72,9 @@
 <Image img={byoc_vpcpeering3} size="lg" alt="BYOC Add route table" border />
 
 ### 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.
@@ -72,103 +89,99 @@
 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.
 </VerticalStepper>
 
 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.
 
 <VerticalStepper headerLevel="h3">
 
-### Request PrivateLink Setup {#step-1-request-privatelink-setup}
-
-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.
-
-ClickHouse Support will enable the necessary infrastructure components, including **the private load balancer** and **PrivateLink service endpoint**.
-
-### Create an Endpoint in Your VPC {#step-2-create-endpoint}
+### Enable private link in ClickHouse console {#step-1-enable-private-link}
 
-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={byoc_privatelink_1} 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"
-
-:::important
-**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)
-
-These settings are required for the PrivateLink DNS to function correctly.
+:::note
+Make sure the **private load balancer** is turned on as a prerequisite.
 :::
 
-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={byoc_privatelink} size="md" alt="BYOC PrivateLink Enable" border />
 
-<Image img={byoc_privatelink_2} size="lg" alt="BYOC PrivateLink Approve" border />
+### Obtain endpoint "Service name" {#step-2-obtain-endpoint-service-name}
 
-### Add Endpoint ID to Service Allowlist {#step-3-add-endpoint-id-allowlist}
+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={aws_private_link_pecreate} size="md" alt="Private Endpoints" border />
 
-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.
+### Create endpoint in your network {#step-3-create-endpoint}
 
-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`)
+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={aws_private_link_endpoint_settings} 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={byoc_privatelink_aws_cross_region} size="md" alt="AWS PrivateLink Cross Region Endpoint Settings" border/>
+5. Select your VPC and subnets (one per availability zone is recommended).
+   <Image img={aws_private_link_select_vpc} 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
 
-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
+     via VPC Settings → DNS resolution and DNS hostnames.
 
-### Connect to ClickHouse via PrivateLink {#step-4-connect-via-privatelink}
+     This ensures that connections using the `vpce` subdomain automatically route through the PrivateLink endpoint without additional DNS configuration.
 
-After the Endpoint ID is added to the allowlist, you can connect to your ClickHouse service using the PrivateLink endpoint.
+7. (Optional) Assign Security groups/Tags.
+   :::note
+   Make sure that ports `443`, `8443`, `9440`, `3306` are allowed in the security group.
+   :::
+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={aws_private_link_vpc_endpoint_id} size="md" alt="VPC Endpoint ID" border />
 
-The PrivateLink endpoint format is similar to the public endpoint, but includes a `vpce` subdomain. For example:
+### Approve the endpoint connection {#step-4-approve-endpoint-connection}
 
-- **Public endpoint**: `h5ju65kv87.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`
-- **PrivateLink endpoint**: `h5ju65kv87.vpce.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`
+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={byoc_privatelink_2} size="md" alt="BYOC PrivateLink Approve" border />
 
-DNS resolution in your VPC will automatically route traffic through the PrivateLink endpoint when you use the `vpce` subdomain format.
+### Add "Endpoint ID" to ClickHouse service allow list {#step-5-add-endpoint-id-to-services-allow-list}
 
-</VerticalStepper>
-
-### PrivateLink Access Control {#privatelink-access-control}
-
-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
+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.
 :::
+<Image img={aws_private_link_pe_filters} size="md" alt="Private Endpoints Filter" border/>
+
+### Access an instance using PrivateLink {#step-6-connect-via-privatelink}
 
-### PrivateLink DNS {#privatelink-dns}
+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={aws_private_link_ped_nsname} size="md" alt="Private Endpoint DNS Name" border />
 
-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:
+   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
 
-- "Private DNS names" is enabled on your VPC endpoint
-- Your VPC has "DNS Hostnames" enabled
+   :::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.
+   :::
 
-This ensures that connections using the `vpce` subdomain automatically route through the PrivateLink endpoint without additional DNS configuration.
+</VerticalStepper>