diff --git a/docs/cloud/guides/index.md b/docs/cloud/guides/index.md index 7731b881f65..a77567a4801 100644 --- a/docs/cloud/guides/index.md +++ b/docs/cloud/guides/index.md @@ -22,7 +22,9 @@ keywords: ['cloud guides', 'documentation', 'how-to', 'cloud features', 'tutoria | [AWS PrivateLink](/manage/security/aws-privatelink) | This document describes how to connect to ClickHouse Cloud using AWS PrivateLink. | | [Azure Private Link](/cloud/security/azure-privatelink) | How to set up Azure Private Link | | [Azure Private Preview](/cloud/reference/byoc/onboarding/azure-private-preview) | Onboard ClickHouse BYOC on Azure using the Terraform module and cross-tenant authentication | +| [BYOC AWS private networking setup](/cloud/reference/byoc/onboarding/network-aws) | Set up VPC Peering or PrivateLink for BYOC on AWS | | [BYOC FAQ](/cloud/reference/byoc/reference/faq) | Deploy ClickHouse on your own cloud infrastructure | +| [BYOC GCP private networking setup](/cloud/reference/byoc/onboarding/network-gcp) | Set up VPC Peering or Private Service Connect for BYOC on GCP | | [BYOC Network Security](/cloud/reference/byoc/reference/network_security) | Deploy ClickHouse on your own cloud infrastructure | | [BYOC observability](/cloud/reference/byoc/observability) | Monitor and observe your BYOC ClickHouse deployment using built-in dashboards and Prometheus metrics | | [BYOC operations and maintenance](/cloud/reference/byoc/operations) | Deploy ClickHouse on your own cloud infrastructure | diff --git a/docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup.md b/docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup/01_aws.md similarity index 80% rename from docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup.md rename to docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup/01_aws.md index cf92c7f2d2b..5384ebc6ca5 100644 --- a/docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup.md +++ b/docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup/01_aws.md @@ -1,9 +1,9 @@ --- -title: 'Private networking setup' -slug: /cloud/reference/byoc/onboarding/network -sidebar_label: 'Private networking setup' -keywords: ['BYOC', 'cloud', 'bring your own cloud', 'vpc peering', 'privatelink'] -description: 'Deploy ClickHouse on your own cloud infrastructure' +title: 'BYOC AWS private networking setup' +slug: /cloud/reference/byoc/onboarding/network-aws +sidebar_label: 'AWS private networking setup' +keywords: ['BYOC', 'cloud', 'bring your own cloud', 'vpc peering', 'aws', 'privatelink'] +description: 'Set up VPC Peering or PrivateLink for BYOC on AWS' doc_type: 'reference' --- @@ -15,20 +15,22 @@ import byoc_vpcpeering4 from '@site/static/images/cloud/reference/byoc-vpcpeerin import byoc_privatelink_1 from '@site/static/images/cloud/reference/byoc-privatelink-1.png'; import byoc_privatelink_2 from '@site/static/images/cloud/reference/byoc-privatelink-2.png'; -ClickHouse BYOC supports various private networking options to enhance security and enable direct connectivity for your services. This guide walks you through the recommended approaches for securely connecting ClickHouse Cloud deployments in your own AWS or GCP account to other networks or services, such as your internal applications or analytics tools. We cover options such as VPC Peering, AWS PrivateLink, and GCP Private Service Connect, and outline the main steps and considerations for each. +ClickHouse BYOC on AWS supports two private connection options including VPC Peering and AWS PrivateLink. -If you require a private network connection to your ClickHouse BYOC deployment, follow the steps in this guide or consult ClickHouse Support for assistance with more advanced scenarios. +## Prerequisites {#common-prerequisites} -## Setup VPC Peering (AWS) {#aws-vpc-peering} +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. + +## Set up VPC peering {#aws-vpc-peering} To create or delete VPC peering for ClickHouse BYOC, follow the steps: -### Enable private load balancer for ClickHouse BYOC {#step-1-enable-private-load-balancer-for-clickhouse-byoc} -Contact ClickHouse Support to enable Private Load Balancer. - -### Create a peering connection {#step-2-create-a-peering-connection} +### 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 @@ -38,12 +40,12 @@ Contact ClickHouse Support to enable Private Load Balancer. BYOC Create Peering Connection -### Accept the peering connection request {#step-3-accept-the-peering-connection-request} +### 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. BYOC Accept Peering Connection -### Add destination to ClickHouse VPC route tables {#step-4-add-destination-to-clickhouse-vpc-route-tables} +### 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. @@ -54,7 +56,7 @@ In ClickHouse BYOC account, BYOC Add route table -### Add destination to the target VPC route tables {#step-5-add-destination-to-the-target-vpc-route-tables} +### 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. @@ -65,7 +67,7 @@ In the peering AWS account, BYOC Add route table -### Edit security group to allow peered VPC access {#step-6-edit-security-group-to-allow-peered-vpc-access} +### Edit security group to allow peered VPC access {#step-5-edit-security-group-to-allow-peered-vpc-access} 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. @@ -79,7 +81,7 @@ To access ClickHouse privately, a private load balancer and endpoint are provisi Optional, after verifying that peering is working, you can request the removal of the public load balancer for ClickHouse BYOC. -## Setup PrivateLink (AWS) {#setup-privatelink} +## 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. @@ -110,7 +112,7 @@ After ClickHouse Support has enabled PrivateLink on their side, you need to crea - Click "Create Endpoint" :::important -**DNS Requirements**: +**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) @@ -119,7 +121,7 @@ These settings are required for the PrivateLink DNS to function correctly. 3. **Approve the Endpoint Connection**: - After creating the endpoint, you need to approve the connection request - - In the VPC Console, go to "Endpoint Connections" + - In the VPC Console, go to "Endpoint Connections" - Find the connection request from ClickHouse and click "Accept" to approve it BYOC PrivateLink Approve @@ -170,7 +172,3 @@ PrivateLink DNS for BYOC endpoints (using the `*.vpce.{subdomain}` format) lever - Your VPC has "DNS Hostnames" enabled This ensures that connections using the `vpce` subdomain automatically route through the PrivateLink endpoint without additional DNS configuration. - -## VPC Peering (GCP) and Private Service Connect (GCP) {#setup-gcp} - -GCP VPC Peering and Private Service Connect provides similar private connectivity for GCP-based BYOC deployments. This feature is currently in development. If you need VPC Peering or Private Service Connect for your GCP BYOC deployment, please [contact ClickHouse Support](https://clickhouse.com/cloud/bring-your-own-cloud) to discuss availability and setup requirements. diff --git a/docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup/02_gcp.md b/docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup/02_gcp.md new file mode 100644 index 00000000000..6b81d5203d8 --- /dev/null +++ b/docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup/02_gcp.md @@ -0,0 +1,141 @@ +--- +title: 'BYOC GCP private networking setup' +slug: /cloud/reference/byoc/onboarding/network-gcp +sidebar_label: 'GCP private networking setup' +keywords: ['BYOC', 'cloud', 'bring your own cloud', 'vpc peering', 'gcp', 'private service connect'] +description: 'Set up VPC Peering or Private Service Connect for BYOC on GCP' +doc_type: 'reference' +--- + +import Image from '@theme/IdealImage'; +import byoc_vpcpeering from '@site/static/images/cloud/reference/byoc-vpcpeering-gcp-1.png'; +import byoc_vpcpeering2 from '@site/static/images/cloud/reference/byoc-vpcpeering-gcp-2.png'; +import byoc_vpcpeering3 from '@site/static/images/cloud/reference/byoc-vpcpeering-gcp-3.png'; +import byoc_privatelink_1 from '@site/static/images/cloud/reference/byoc-privatelink-gcp-1.png'; +import byoc_privatelink_2 from '@site/static/images/cloud/reference/byoc-privatelink-gcp-2.png'; +import byoc_privatelink_3 from '@site/static/images/cloud/reference/byoc-privatelink-gcp-3.png'; +import byoc_privatelink_4 from '@site/static/images/cloud/reference/byoc-privatelink-gcp-4.png'; +import byoc_privatelink_5 from '@site/static/images/cloud/reference/byoc-privatelink-gcp-5.png'; +import byoc_privatelink_6 from '@site/static/images/cloud/reference/byoc-privatelink-gcp-6.png'; + +ClickHouse BYOC on GCP supports two private connection options including VPC Peering and Private Service Connect. Traffic flows entirely within the GCP network, never traversing the public internet. + +## Prerequisites {#common-prerequisites} + +Common steps required by both VPC peering and Private Service Connect. + +### Enable private load balancer for ClickHouse BYOC {#step-enable-private-load-balancer-for-clickhouse-byoc} +Contact ClickHouse Support to enable Private Load Balancer. + +## Set up VPC peering {#gcp-vpc-peering} + +Please familiarize yourself with [GCP VPC peering feature](https://docs.cloud.google.com/vpc/docs/vpc-peering) and note the limitations of VPC peering (for example subnet IP ranges can't overlap across peered VPC networks). ClickHouse BYOC utilizes a private load balancer to allow network connectivity through the peering to ClickHouse services. + +To create or delete VPC peering for ClickHouse BYOC, follow the steps: + +:::note +The example steps are for a simple scenario, for advanced scenarios such as peering with on-premises connectivity, some adjustments may be required. +::: + + + +### Create a peering connection {#step-1-create-a-peering-connection} + +In this example, we are setting up peering between the BYOC VPC network and another existing VPC network. + +1. Navigate to the "VPC Network" in ClickHouse BYOC Google Cloud Project. +2. Select "VPC network peering". +3. Click "Create connection". +4. Input the necessary fields as per your requirements. Below is a screenshot for creating a peering within same GCP project. + +BYOC Create Peering Connection + +GCP VPC peering requires 2 connections between the 2 networks to work (i.e. a connection from BYOC network to the existing VPC network and a connection from the existing VPC network to the BYOC network). So you need to similarly create 1 more connection in reverse direction, below is a screenshot for the second peering connection creation: + +BYOC Accept Peering Connection + +After both connections are created, the status of the 2 connections should become "Active" after refreshing the Google Cloud Console webpage: + +BYOC Accept Peering Connection + +The ClickHouse service should now be accessible from the peered VPC. + +### Access ClickHouse service via peering connection {#step-2-access-ch-service-via-peering} + +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-east1.gcp.byoc.clickhouse.cloud` +- **Private endpoint**: `h5ju65kv87-private.mhp0y4dmph.us-east1.gcp.byoc.clickhouse.cloud` + + + +## Set up PSC (Private Service Connect) {#gcp-psc} + +GCP PSC (Private Service Connect) provides secure, private connectivity to your ClickHouse BYOC services without requiring VPC peering or internet gateways. + + + +### Request PSC service setup {#step-1-request-psc-setup} + +Contact [ClickHouse Support](https://clickhouse.com/cloud/bring-your-own-cloud) to request PSC service setup for your BYOC deployment. No specific information is required at this stage—simply indicate that you want to set up PSC connectivity. + +ClickHouse Support will enable the necessary infrastructure components, including **the private load balancer** and **PSC Service**. + +### Obtain GCP PSC service name and DNS name {#step-2-obtain-gcp-service-attachment-and-dns-name-for-private-service-connect} + +ClickHouse Support will provide you with the PSC Service name. You can also obtain it in the ClickHouse Cloud console, under "Organization" -> "Infrastructure", click into the infra name to see the details. + +BYOC PSC Endpoint +BYOC PSC Endpoint + +You can also find the PSC service name in the GCP Private Service Connect console under "Published services" (filter by service name or look for ClickHouse services) + +BYOC PSC Endpoint +BYOC PSC Endpoint + +### Create a PSC endpoint in your network {#step-3-create-endpoint} + +After ClickHouse Support has enabled PSC service on their side, you need to create a PSC endpoint in your client application network to connect to the ClickHouse PSC service. + +1. **Create the PSC Endpoint**: +- Navigate to the GCP Console -> Network Services → Private Service Connect → Connect Endpoint +- Select "Published service" for "Target" and input the PSC service name obtained at last step to "Target details" +- Input a valid endpoint name +- Choose your network and select subnets (This is the network where your client application will be connecting from) +- Choose or create a new IP address for the endpoint, the IP address needs to be used by step [Set private DNS name for endpoint](#step-4-set-private-dns-name-for-endpoint) +- Click "Add Endpoint", wait a moment for the endpoint to be created. +- The endpoint status should become "Accepted", contact ClickHouse support if it's not auto-accepted. + +BYOC PSC endpoint creation + +2. **Obtain PSC Connection ID**: +- Click into the endpoint detail and obtain the "PSC Connection ID" to be used by step [Add endpoint's PSC Connection ID to service allowlist](#step-5-add-endpoint-id-allowlist) + +BYOC PSC endpoint detail + +### Set private DNS name for endpoint {#step-4-set-private-dns-name-for-endpoint} + +:::note +There are various ways to configure DNS. Please set up DNS according to your specific use case. +::: + +You need to point all subdomains (wildcard) of the "DNS name", taken from [Obtain GCP PSC service name and DNS name](#step-2-obtain-gcp-service-attachment-and-dns-name-for-private-service-connect) step, to GCP PSC endpoint IP address. This ensures that services/components within your VPC/Network can resolve it properly. + +### Add endpoint's PSC Connection ID to service allowlist {#step-5-add-endpoint-id-allowlist} + +Once your PSC endpoint is created and the status is "Accepted", you need to add the Endpoint's PSC Connection ID to the allowlist for **each ClickHouse service** you want to access via PSC. + +**Contact ClickHouse Support**: +- Provide the Endpoint's PSC Connection IDs to ClickHouse Support +- Specify which ClickHouse services should allow access from this endpoint +- ClickHouse Support will add the Endpoint Connection IDs to the service allowlist + +### Connect to ClickHouse via PSC {#step-6-connect-via-psc-endpoint} + +After the Endpoint Connection IDs is added to the allowlist, you can connect to your ClickHouse service using the PSC endpoint. + +The PSC endpoint format is similar to the public endpoint, but includes a `p` subdomain. For example: + +- **Public endpoint**: `h5ju65kv87.mhp0y4dmph.us-east1.gcp.clickhouse-byoc.com` +- **PSC endpoint**: `h5ju65kv87.p.mhp0y4dmph.us-east1.gcp.clickhouse-byoc.com` + + diff --git a/docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup/index.md b/docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup/index.md new file mode 100644 index 00000000000..4b4bbf16230 --- /dev/null +++ b/docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup/index.md @@ -0,0 +1,15 @@ +--- +title: 'Private networking setup' +slug: /cloud/reference/byoc/onboarding/network +sidebar_label: 'Private networking setup' +hide_title: true +description: 'Table of contents page for the ClickHouse Cloud BYOC Private Networking Setup section' +doc_type: 'landing-page' +keywords: ['BYOC', 'cloud', 'bring your own cloud', 'vpc peering', 'privatelink', 'private service connect'] +--- + +# Private networking setup + +ClickHouse BYOC supports various private networking options to enhance security and enable direct connectivity for your services. This guide walks you through the recommended approaches for securely connecting ClickHouse Cloud deployments in your own AWS or GCP account to other networks or services, such as your internal applications or analytics tools. We cover options such as VPC Peering, AWS PrivateLink, and GCP Private Service Connect, and outline the main steps and considerations for each. + +If you require a private network connection to your ClickHouse BYOC deployment, follow the steps in the guides or consult ClickHouse Support for assistance with more advanced scenarios. diff --git a/static/images/cloud/reference/byoc-privatelink-gcp-1.png b/static/images/cloud/reference/byoc-privatelink-gcp-1.png new file mode 100644 index 00000000000..ddd3c3eac0e Binary files /dev/null and b/static/images/cloud/reference/byoc-privatelink-gcp-1.png differ diff --git a/static/images/cloud/reference/byoc-privatelink-gcp-2.png b/static/images/cloud/reference/byoc-privatelink-gcp-2.png new file mode 100644 index 00000000000..bb69bf715bd Binary files /dev/null and b/static/images/cloud/reference/byoc-privatelink-gcp-2.png differ diff --git a/static/images/cloud/reference/byoc-privatelink-gcp-3.png b/static/images/cloud/reference/byoc-privatelink-gcp-3.png new file mode 100644 index 00000000000..a7a49a992c7 Binary files /dev/null and b/static/images/cloud/reference/byoc-privatelink-gcp-3.png differ diff --git a/static/images/cloud/reference/byoc-privatelink-gcp-4.png b/static/images/cloud/reference/byoc-privatelink-gcp-4.png new file mode 100644 index 00000000000..214aa02bf0b Binary files /dev/null and b/static/images/cloud/reference/byoc-privatelink-gcp-4.png differ diff --git a/static/images/cloud/reference/byoc-privatelink-gcp-5.png b/static/images/cloud/reference/byoc-privatelink-gcp-5.png new file mode 100644 index 00000000000..3b61a8a068e Binary files /dev/null and b/static/images/cloud/reference/byoc-privatelink-gcp-5.png differ diff --git a/static/images/cloud/reference/byoc-privatelink-gcp-6.png b/static/images/cloud/reference/byoc-privatelink-gcp-6.png new file mode 100644 index 00000000000..01c4dd1adf8 Binary files /dev/null and b/static/images/cloud/reference/byoc-privatelink-gcp-6.png differ diff --git a/static/images/cloud/reference/byoc-vpcpeering-gcp-1.png b/static/images/cloud/reference/byoc-vpcpeering-gcp-1.png new file mode 100644 index 00000000000..7fc6717afaf Binary files /dev/null and b/static/images/cloud/reference/byoc-vpcpeering-gcp-1.png differ diff --git a/static/images/cloud/reference/byoc-vpcpeering-gcp-2.png b/static/images/cloud/reference/byoc-vpcpeering-gcp-2.png new file mode 100644 index 00000000000..b22027a0454 Binary files /dev/null and b/static/images/cloud/reference/byoc-vpcpeering-gcp-2.png differ diff --git a/static/images/cloud/reference/byoc-vpcpeering-gcp-3.png b/static/images/cloud/reference/byoc-vpcpeering-gcp-3.png new file mode 100644 index 00000000000..efdfc450bff Binary files /dev/null and b/static/images/cloud/reference/byoc-vpcpeering-gcp-3.png differ