Skip to content

docs(byoc): document the Connection via selector in the Connect dialog #6490

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

Draft
yiyang-shao wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs(byoc): document the Connection via selector in the Connect dialog #6490

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
20 changes: 20 additions & 0 deletions docs/cloud/guides/infrastructure/01_deployment_options/byoc/04_connectivity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,22 @@ import byoc_connect_1 from '@site/static/images/cloud/reference/byoc-connect-1.p

This page describes the different ways to connect to your ClickHouse services in BYOC. You can choose from public load balancers, private load balancers, or PrivateLink/Private Service Connect endpoints based on your security and networking requirements.

## Selecting a connection path in the console {#connection-via}

Connection details for every BYOC service are available in the ClickHouse Cloud console: open the service and click **Connect**.

When a service exposes more than one network path, the **Connect** dialog shows a **Connection via** dropdown. Use it to choose how you reach the service:

- **Public load balancer** — the internet-facing endpoint.
- **Private load balancer** — the internal endpoint, reached over VPC peering or connected networks. Listed only when a [private load balancer](#private-load-balancer) is enabled for your infrastructure.
- **PrivateLink** (AWS) / **Private Service Connect** (GCP) / **Private Link** (Azure) — the cloud provider's private-endpoint hostname. Listed only when [PrivateLink or Private Service Connect](#privatelink-or-private-service-connect) is enabled.

Selecting a path updates the hostname in every connection example in the dialog — the HTTPS (`curl`) command, the native client, JDBC, MySQL, and the language-client snippets (Python, Node.js, Java, Go, and C#) — so you can copy a ready-to-use command for the exact path you need without editing the hostname by hand.

The dropdown lists only the paths enabled for your infrastructure. A service that exposes only the public load balancer shows that endpoint directly, without a dropdown.

{/* TODO: add a screenshot of the Connect dialog with the "Connection via" dropdown expanded once the feature is live in production. */}

## Public Load Balancer {#public-load-balancer}

A public load balancer provides internet-facing access to your ClickHouse services. This is the default configuration when using a ClickHouse-managed dedicated VPC.
Expand Down Expand Up @@ -64,6 +80,8 @@ To connect using the private endpoint:
- **Public endpoint**: `sb9jmrq2ne.asf3kcggao.ap-southeast-1.aws.clickhouse-byoc.com`
- **Private endpoint**: `sb9jmrq2ne-private.asf3kcggao.ap-southeast-1.aws.clickhouse-byoc.com`

Rather than deriving the `-private` hostname by hand, select **Private load balancer** from the **Connection via** dropdown in the **Connect** dialog to copy the endpoint and ready-made connection commands directly.

### IP Filtering {#private-ip-filtering}

Although private load balancers restrict access to internal networks only, you may still set up IP filtering for even finer-grained control over which sources within your private network can connect. IP filtering for private load balancers uses the same configuration mechanism as with public load balancers: define your allowed IP addresses or CIDR ranges, and ClickHouse Cloud will apply these rules appropriately to each endpoint type. The platform automatically distinguishes between public and private CIDR ranges and assigns them to the corresponding load balancer endpoints. See the [IP Access List documentation](https://clickhouse.com/docs/cloud/security/setting-ip-filters).
Expand Down Expand Up @@ -97,6 +115,8 @@ The PrivateLink endpoint format is similar to the public endpoint, but includes
- **Public endpoint**: `h5ju65kv87.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`
- **PrivateLink endpoint**: `h5ju65kv87.vpce.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`

Once the endpoint is set up and allowlisted, select **PrivateLink** (or **Private Service Connect** on GCP, **Private Link** on Azure) from the **Connection via** dropdown in the **Connect** dialog to copy the private-endpoint connection details directly.

### Endpoint ID Allowlist {#endpoint-id-allowlist}

In order to use PrivateLink or Private Service Connect, the Endpoint ID of your client connection must be explicitly allowed for each ClickHouse service. Please contact ClickHouse Support and provide your Endpoint IDs so they can be added to the service allowlist.
Expand Down
Loading