diff --git a/images/cloud/reference/byoc-aws-existing-vpc-ui.png b/images/cloud/reference/byoc-aws-existing-vpc-ui.png index e58ea7e7f..26968b4f4 100644 Binary files a/images/cloud/reference/byoc-aws-existing-vpc-ui.png and b/images/cloud/reference/byoc-aws-existing-vpc-ui.png differ diff --git a/images/cloud/reference/byoc-gcp-existing-vpc-ui.png b/images/cloud/reference/byoc-gcp-existing-vpc-ui.png new file mode 100644 index 000000000..7c1373364 Binary files /dev/null and b/images/cloud/reference/byoc-gcp-existing-vpc-ui.png differ diff --git a/images/cloud/reference/byoc-new-infra-1.png b/images/cloud/reference/byoc-new-infra-1.png index 319dc3609..2c059ca7b 100644 Binary files a/images/cloud/reference/byoc-new-infra-1.png and b/images/cloud/reference/byoc-new-infra-1.png differ diff --git a/images/cloud/reference/byoc-new-infra-2.png b/images/cloud/reference/byoc-new-infra-2.png index dc8ced673..1226ccc51 100644 Binary files a/images/cloud/reference/byoc-new-infra-2.png and b/images/cloud/reference/byoc-new-infra-2.png differ diff --git a/images/cloud/reference/byoc-onboarding-1.png b/images/cloud/reference/byoc-onboarding-1.png index d8f62a97e..c097142d8 100644 Binary files a/images/cloud/reference/byoc-onboarding-1.png and b/images/cloud/reference/byoc-onboarding-1.png differ diff --git a/images/cloud/reference/byoc-onboarding-2.png b/images/cloud/reference/byoc-onboarding-2.png index d83bf8fd8..00892aeb4 100644 Binary files a/images/cloud/reference/byoc-onboarding-2.png and b/images/cloud/reference/byoc-onboarding-2.png differ diff --git a/images/cloud/reference/byoc-onboarding-3.png b/images/cloud/reference/byoc-onboarding-3.png index fee65b961..1d9b66762 100644 Binary files a/images/cloud/reference/byoc-onboarding-3.png and b/images/cloud/reference/byoc-onboarding-3.png differ diff --git a/products/bring-your-own-cloud/navigation.json b/products/bring-your-own-cloud/navigation.json index ea341780e..e96679131 100644 --- a/products/bring-your-own-cloud/navigation.json +++ b/products/bring-your-own-cloud/navigation.json @@ -36,8 +36,7 @@ "products/bring-your-own-cloud/onboarding/network-gcp" ] }, - "products/bring-your-own-cloud/onboarding/new-region", - "products/bring-your-own-cloud/onboarding/azure-private-preview" + "products/bring-your-own-cloud/onboarding/new-region" ] }, { diff --git a/products/bring-your-own-cloud/onboarding/azure-private-preview.mdx b/products/bring-your-own-cloud/onboarding/azure-private-preview.mdx deleted file mode 100644 index 276de69e3..000000000 --- a/products/bring-your-own-cloud/onboarding/azure-private-preview.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: 'Azure Private Preview' -slug: /cloud/reference/byoc/onboarding/azure-private-preview -sidebarTitle: 'Azure (Private Preview)' -keywords: ['BYOC', 'cloud', 'bring your own cloud', 'azure'] -description: 'Onboard ClickHouse BYOC on Azure using the Terraform module and cross-tenant authentication' -doc_type: 'reference' ---- - -import PrivatePreviewBadge from "/snippets/components/PrivatePreviewBadge/PrivatePreviewBadge.jsx"; - - - -BYOC on Azure is in **private preview**. To participate, [contact the ClickHouse team](https://clickhouse.com/cloud/bring-your-own-cloud). - - -## Overview {#overview} - -BYOC on Azure lets you run ClickHouse in your own Azure subscription. Onboarding uses a Terraform module that provisions the cross-tenant authentication required for ClickHouse Cloud's provisioner to create and manage Azure resources in your tenant and subscription. - -Other aspects of the deployment—such as [architecture](/products/bring-your-own-cloud/overview/architecture), [network security](/products/bring-your-own-cloud/reference/network-security), [features](/products/cloud/guides/infrastructure/deployment-options/byoc/overview#features), and [connectivity](/products/bring-your-own-cloud/configuration/connect)—are broadly similar to the AWS and GCP BYOC offerings; refer to those pages for more details. - -## Prerequisites {#prerequisites} - -- An Azure **subscription** and **tenant** where you want to host the BYOC deployment -- The **subscription ID** and **tenant ID** to share with the ClickHouse team - -## Onboarding {#onboarding} - - - -### 1. Apply the Terraform module {#apply-terraform-module} - -To start BYOC Azure onboarding, apply the [Terraform module for Azure](https://github.com/ClickHouse/terraform-byoc-onboarding/tree/main/modules/azure) provided by ClickHouse in your **target tenant and subscription**. - -Use the module's documentation for required variables and apply steps. After applying, the module will have set up the necessary identity and permissions in your Azure environment. - - -### 2. Provide IDs to ClickHouse {#provide-ids} - -Share the following with the ClickHouse team: - -- **Target subscription ID** — The Azure subscription where BYOC resources will be created -- **Target tenant ID** — The Azure AD (Entra) tenant that owns that subscription -- **Region** — The Azure regions where you want to deploy your ClickHouse services. -- **VNet CIDR range** — The IP address range you would like used for the BYOC VNet. - -The ClickHouse team will use these to create the BYOC infrastructure and complete the onboarding - - - -### How cross-tenant authentication works {#cross-tenant-auth} - -Following [Azure guidance for cross-tenant authentication](https://learn.microsoft.com/en-us/entra/identity-platform/single-and-multi-tenant-apps), the Terraform module: - -1. **Provisions a multi-tenant application** as an **Enterprise Application** (service principal) in your target tenant -2. **Assigns the required permissions** to that application, scoped to your target subscription - -This allows the ClickHouse Cloud Control Plane to create and manage Azure resources (such as resource groups, AKS, storage, and networking) within your subscription, without storing your Azure credentials in ClickHouse. - -For more detail on multi-tenant apps and cross-tenant scenarios in Azure, see: - -- [Single and multi-tenant apps in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/single-and-multi-tenant-apps) -- [Authorize cross-tenant access (Azure SignalR example)](https://learn.microsoft.com/en-us/azure/azure-signalr/signalr-howto-authorize-cross-tenant) diff --git a/products/bring-your-own-cloud/onboarding/customization-aws.mdx b/products/bring-your-own-cloud/onboarding/customization-aws.mdx index 66947dda5..64f8c192b 100644 --- a/products/bring-your-own-cloud/onboarding/customization-aws.mdx +++ b/products/bring-your-own-cloud/onboarding/customization-aws.mdx @@ -68,13 +68,13 @@ module "clickhouse_onboarding" { ### Set up BYOC infrastructure {#set-up-byoc-infrastructure} -In the ClickHouse Cloud console, navigate to the [BYOC setup page](https://console.clickhouse.cloud/byocOnboarding) and configure the following: +In the ClickHouse Cloud console, configure the following when setting up new infrastructure: -1. Under **VPC Configuration**, select **Use existing VPC**. +1. Under **VPC configuration**, select **Use existing VPC**. 2. Enter your **VPC ID** (e.g., `vpc-0bb751a5b888ad123`). 3. Enter the **Private subnet IDs** for the 3 subnets you configured earlier. 4. Optionally, enter **Public subnet IDs** if your setup requires public-facing load balancers. -5. Click **Setup Infrastructure** to begin provisioning. +5. Click **Set up Infrastructure** to begin provisioning. ClickHouse Cloud BYOC setup UI with Use existing VPC selected @@ -92,9 +92,11 @@ For organizations with advanced security requirements or strict compliance polic Customer-managed IAM roles are in private preview. If you require this capability, contact ClickHouse Support to discuss your specific requirements and timeline. When available, this feature will allow you to: -* Provide pre-configured IAM roles for ClickHouse Cloud to use -* Remove write permissions to IAM related permissions for `ClickHouseManagementRole` used for cross-account access -* Maintain full control over role permissions and trust relationships + +- Provide pre-configured IAM roles for ClickHouse Cloud to use +- Remove write permissions to IAM related permissions for `ClickHouseManagementRole` used for cross-account access +- Maintain full control over role permissions and trust relationships + For information about the IAM roles that ClickHouse Cloud creates by default, see the [BYOC Privilege Reference](/products/bring-your-own-cloud/reference/privilege). diff --git a/products/bring-your-own-cloud/onboarding/customization-gcp.mdx b/products/bring-your-own-cloud/onboarding/customization-gcp.mdx index c071c9039..057207bfe 100644 --- a/products/bring-your-own-cloud/onboarding/customization-gcp.mdx +++ b/products/bring-your-own-cloud/onboarding/customization-gcp.mdx @@ -33,16 +33,15 @@ Ensure a [Cloud NAT gateway](https://cloud.google.com/nat/docs/overview) is depl Ensure your VPC has working DNS resolution and doesn't block, interfere with, or overwrite standard DNS names. ClickHouse BYOC relies on DNS to resolve Tailscale control servers and ClickHouse service endpoints. If DNS is unavailable or misconfigured, BYOC services may fail to connect or operate properly. -### Contact ClickHouse support {#contact-clickhouse-support} +### Set up BYOC infrastructure {#set-up-byoc-infrastructure} -After completing the above configuration steps, create a support ticket with the following information: +In the ClickHouse Cloud console, configure the following when setting up new infrastructure: -* Your GCP project ID -* The GCP region where you want to deploy the service -* Your VPC network name -* The subnet name you've allocated for ClickHouse -* (Optional) The secondary IPv4 range names dedicated for ClickHouse. This is only required if the private subnet has multiple secondary IPv4 ranges and not all of them are intended for ClickHouse use +1. Under **VPC configuration**, select **Use existing VPC**. +2. Enter your **VPC network name**. +3. Enter the **Subnet name** you allocated for ClickHouse. +4. Click **Set up Infrastructure** to begin provisioning. -Our team will review your configuration and complete the provisioning from our side. +ClickHouse Cloud BYOC setup UI with Use existing VPC selected for GCP diff --git a/products/bring-your-own-cloud/onboarding/new-region.mdx b/products/bring-your-own-cloud/onboarding/new-region.mdx index 875b0883e..8367b64ba 100644 --- a/products/bring-your-own-cloud/onboarding/new-region.mdx +++ b/products/bring-your-own-cloud/onboarding/new-region.mdx @@ -9,7 +9,7 @@ doc_type: 'reference' import { Image } from "/snippets/components/Image.jsx"; -After completing the initial onboarding, you may wish to deploy additional BYOC infrastructure in a different region or in another AWS account or GCP project. +After completing the initial onboarding, you may wish to deploy additional BYOC infrastructure in a different region or in another AWS account, GCP project, or Azure subscription. To add a new BYOC deployment: @@ -17,6 +17,6 @@ To add a new BYOC deployment: BYOC infra page -2. Select "Add new account" or "Add new infrastructure" and follow the guided interface to complete the setup process. +1. Select "Add new infrastructure" and follow the guided interface to complete the setup process. BYOC infra page diff --git a/products/bring-your-own-cloud/onboarding/standard.mdx b/products/bring-your-own-cloud/onboarding/standard.mdx index fcf7e9418..ab3bead44 100644 --- a/products/bring-your-own-cloud/onboarding/standard.mdx +++ b/products/bring-your-own-cloud/onboarding/standard.mdx @@ -11,11 +11,11 @@ import { Image } from "/snippets/components/Image.jsx"; ## What is standard onboarding? {#what-is-standard-onboarding} -**Standard onboarding** is the default, guided workflow for deploying ClickHouse in your own cloud account using BYOC. In this approach, ClickHouse Cloud provisions all of the core cloud resources required for your deployment—such as the VPC, subnets, security groups, Kubernetes (EKS/GKE) cluster, and supporting IAM roles/service accounts—within your AWS account/GCP project. This ensures consistent, secure configuration, and minimizes the manual steps required from your team. +**Standard onboarding** is the default, guided workflow for deploying ClickHouse in your own cloud account using BYOC. In this approach, ClickHouse Cloud provisions all of the core cloud resources required for your deployment—such as the VPC/VNet, subnets, security groups, Kubernetes (EKS/GKE/AKS) cluster, and supporting IAM roles/service accounts/service principals—within your AWS account, GCP project, or Azure subscription. This ensures consistent, secure configuration, and minimizes the manual steps required from your team. -With standard onboarding, you simply provide a dedicated AWS account/GCP project, and run an initial stack (via CloudFormation or Terraform) to create the minimum IAM permissions and trust required for ClickHouse Cloud to orchestrate further setup. All subsequent steps—including infrastructure provisioning and service launch—are managed through the ClickHouse Cloud web console. +With standard onboarding, you simply provide a dedicated AWS account, GCP project, or Azure subscription, and run an initial stack (via CloudFormation or Terraform) to create the minimum permissions and trust required for ClickHouse Cloud to orchestrate further setup. All subsequent steps—including infrastructure provisioning and service launch—are managed through the ClickHouse Cloud web console. -Customers are strongly recommended to prepare a **dedicated** AWS account or GCP project for hosting the ClickHouse BYOC deployment to ensure better isolation in terms of permissions and resources. ClickHouse will deploy a dedicated set of cloud resources (VPC, Kubernetes cluster, IAM roles, S3 buckets, etc.) in your account. +Customers are strongly recommended to prepare a **dedicated** AWS account, GCP project, or Azure subscription for hosting the ClickHouse BYOC deployment to ensure better isolation in terms of permissions and resources. ClickHouse will deploy a dedicated set of cloud resources (VPC/VNet, Kubernetes cluster, IAM roles/service accounts/service principals, object storage buckets, etc.) in your account. If you need a more customized setup (for example, deploying into an existing VPC), refer to the [Customized Onboarding](/products/bring-your-own-cloud/onboarding/customization-aws) documentation. @@ -29,9 +29,9 @@ To start the onboarding process, please [contact us](https://clickhouse.com/clou ## Onboarding {#onboarding-process} -### Prepare an AWS account/GCP project {#prepare-an-aws-account} +### Prepare an AWS account/GCP project/Azure subscription {#prepare-an-aws-account} -Prepare a fresh AWS account or GCP project under your organization. Visit our web console: https://console.clickhouse.cloud/byocOnboarding to continue the setup. +Prepare a fresh AWS account, GCP project, or Azure subscription under your organization. @@ -40,20 +40,22 @@ Prepare a fresh AWS account or GCP project under your organization. Visit our we BYOC choose CSP -### Account/Project setup {#account-setup} +### Account/project/subscription setup {#account-setup} -The initial BYOC setup can be performed using either a [CloudFormation template(AWS)](https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/cf-templates/byoc.yaml) or a [Terraform module(GCP)](https://github.com/ClickHouse/terraform-byoc-onboarding/tree/main/modules/gcp). It creates a high privileged IAM role, enabling BYOC controllers from ClickHouse Cloud to manage your infrastructure. +The initial BYOC setup can be performed using a [CloudFormation template (AWS)](https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/cf-templates/byoc.yaml), a [Terraform module (GCP)](https://github.com/ClickHouse/terraform-byoc-onboarding/tree/main/modules/gcp), or a [Terraform module (Azure)](https://github.com/ClickHouse/terraform-byoc-onboarding/tree/main/modules/azure). It creates a highly privileged identity (IAM role/service account/service principal), enabling BYOC controllers from ClickHouse Cloud to manage your infrastructure. BYOC initialize account -Storage buckets, VPC, Kubernetes cluster, and compute resources required for running ClickHouse aren't included in this initial setup. They will be provisioned in the next step. +Storage buckets, VPC/VNet, Kubernetes cluster, and compute resources required for running ClickHouse aren't included in this initial setup. They will be provisioned in the next step. + #### Alternative Terraform Module for AWS {#terraform-module-aws} If you prefer to use Terraform instead of CloudFormation for AWS deployments, we also provide a [Terraform module for AWS](https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/tf/byoc.tar.gz). Usage: + ```hcl module "clickhouse_onboarding" { source = "https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/tf/byoc.tar.gz" @@ -64,15 +66,15 @@ module "clickhouse_onboarding" { ### Set up BYOC infrastructure {#setup-byoc-infrastructure} -You will be prompted to set up the infrastructure, including S3 buckets, VPC, and the Kubernetes cluster, from the ClickHouse Cloud console. Certain configurations must be determined at this stage, as they can't be changed later. Specifically: +You will be prompted to set up the infrastructure, including object storage buckets, VPC/VNet, and the Kubernetes cluster, from the ClickHouse Cloud console. Certain configurations must be determined at this stage, as they can't be changed later. Specifically: - **Region**: All **public regions** listed in our [supported regions](/products/cloud/reference/supported-regions) documentation are available for BYOC deployments. Private regions aren't currently supported. -- **VPC CIDR range**: By default, we use `10.0.0.0/16` for the BYOC VPC CIDR range. If you plan to use VPC peering with another account, ensure the CIDR ranges don't overlap. Allocate a proper CIDR range for BYOC, with a minimum size of `/22` to accommodate necessary workloads. +- **VPC/VNet CIDR range**: By default, we use `10.0.0.0/16` for the BYOC VPC (AWS/GCP) or VNet (Azure) CIDR range. If you plan to use VPC/VNet peering with another account, ensure the CIDR ranges don't overlap. Allocate a proper CIDR range for BYOC, with a minimum size of `/23` to accommodate necessary workloads. - **Availability Zones**: If you plan to use VPC peering, aligning availability zones between the source and BYOC accounts can help reduce cross-AZ traffic costs. For example, in AWS, availability zone suffixes (`a`, `b`, `c`) may represent different physical zone IDs across accounts. See the [AWS guide](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/use-consistent-availability-zones-in-vpcs-across-different-aws-accounts.html) for details. -BYOC setup infra +BYOC set up infrastructure diff --git a/products/bring-your-own-cloud/overview/architecture.mdx b/products/bring-your-own-cloud/overview/architecture.mdx index 3d40677f5..372f2e157 100644 --- a/products/bring-your-own-cloud/overview/architecture.mdx +++ b/products/bring-your-own-cloud/overview/architecture.mdx @@ -17,17 +17,17 @@ The diagram below illustrates how ClickHouse Cloud organizations, cloud accounts - **ClickHouse Cloud organization:** The top-level entity in ClickHouse Cloud that manages users, billing, and non-BYOC ClickHouse services. Users within an organization can access both standard Cloud services and BYOC services. - **ClickHouse BYOC organization:** A separate organization dedicated to managing BYOC deployments. It shares users with the Cloud organization but is linked to one or more cloud accounts where BYOC infrastructure is deployed. -- **Cloud account / project:** The customer-owned AWS account or GCP project where BYOC infrastructure is provisioned. Each account or project can host BYOC deployments in one or more regions. A dedicated account or project per BYOC deployment is recommended for isolation. -- **BYOC infrastructure:** The set of cloud resources deployed within a specific region of a cloud account, including a VPC, Kubernetes cluster (EKS/GKE), storage buckets, IAM roles, and supporting services. A single cloud account can contain multiple BYOC infrastructures across different regions. +- **Cloud account/project/subscription:** The customer-owned AWS account, GCP project, or Azure subscription where BYOC infrastructure is provisioned. Each account/project/subscription can host BYOC deployments in one or more regions. A dedicated account/project/subscription per BYOC deployment is recommended for isolation. +- **BYOC infrastructure:** The set of cloud resources deployed within a specific region of a cloud account, including a VPC/VNet, Kubernetes cluster (EKS/GKE/AKS), object storage buckets, IAM roles/service accounts/service principals, and supporting services. A single cloud account can contain multiple BYOC infrastructures across different regions. - **ClickHouse Service:** An individual ClickHouse cluster running within a BYOC infrastructure. Multiple services can run within the same BYOC infrastructure. -Mixing of AWS accounts and GCP projects under the same organization is only possible for customers who are not set up through a [cloud service provider marketplace](/products/cloud/reference/billing/marketplace/overview). +Mixing of AWS accounts, GCP projects and Azure subscriptions under the same organization is only possible for customers who aren't set up through a [cloud service provider marketplace](/products/cloud/reference/billing/marketplace/overview). ## Glossary {#glossary} -- **ClickHouse VPC:** The VPC owned by ClickHouse Cloud. +- **ClickHouse VPC:** The VPC owned by ClickHouse Cloud. - **Customer BYOC VPC:** The VPC, owned by the customer's cloud account, is provisioned and managed by ClickHouse Cloud and dedicated to a ClickHouse Cloud BYOC deployment. - **Customer VPC:** Other VPCs owned by the customer cloud account used for applications that need to connect to the Customer BYOC VPC. @@ -45,10 +45,10 @@ In your **Customer BYOC VPC**, ClickHouse provisions a Kubernetes cluster (for e The main cloud resources ClickHouse Cloud will deploy in your account are: -* **VPC:** A Virtual Private Cloud dedicated to your ClickHouse deployment. This can be managed either by ClickHouse or by you, the customer, and is typically peered with your application VPCs. -* **IAM roles and policies:** Roles and permissions necessary for Kubernetes, ClickHouse services, and the monitoring stack. These can be provisioned by ClickHouse or supplied by the customer. -* **Storage buckets:** Used for storing data parts, backups, and (optionally) long-term metrics and log archives. -* **Kubernetes cluster:** This can be Amazon EKS, Google GKE, or Azure AKS, depending on your cloud provider, and hosts the ClickHouse servers and supporting services shown in the architecture diagram. +- **VPC:** A Virtual Private Cloud dedicated to your ClickHouse deployment. This can be managed either by ClickHouse or by you, the customer, and is typically peered with your application VPCs. +- **IAM roles and policies:** Roles and permissions necessary for Kubernetes, ClickHouse services, and the monitoring stack. These can be provisioned by ClickHouse or supplied by the customer. +- **Storage buckets:** Used for storing data parts, backups, and (optionally) long-term metrics and log archives. +- **Kubernetes cluster:** This can be Amazon EKS, Google GKE, or Azure AKS depending on your cloud provider. It hosts the ClickHouse servers and supporting services shown in the architecture diagram. By default, ClickHouse Cloud provisions a new, dedicated VPC and sets up the necessary IAM roles to ensure secure operation of Kubernetes services. For organizations with advanced networking or security needs, there is also the option to manage the VPC and IAM roles independently. This approach allows for greater customization of network configurations and more precise control over permissions. However, choosing to self-manage these resources will increase your operational responsibilities. @@ -88,6 +88,7 @@ Tailscale provides a secure, zero-trust private network connection between Click - **Infrastructure management**: Management services can coordinate with your BYOC infrastructure for automated operations The Tailscale connection is **outbound-only** from your BYOC VPC—no inbound connections are required, reducing your security exposure. All access is: + - **Approved and audited**: Engineers must request access through an internal approval system - **Time-bound**: Access automatically expires after a set period - **Restricted**: Engineers can only access system tables and infrastructure components, never customer data @@ -107,7 +108,8 @@ Together, these two components enable ClickHouse Cloud to: All customer data remains within your cloud account and is never accessed or transmitted through these management channels. **Additional recommendations and considerations:** -- Ensure that network CIDR ranges for your BYOC VPC doesn't overlap with any existing VPCs you plan to peer with. + +- Ensure that network CIDR ranges for your BYOC VPC don't overlap with any existing VPCs you plan to peer with. - Tag your resources clearly to simplify management and support. - Plan for adequate subnet sizing and distribution across availability zones for high availability. - Consult the [security playbook](/products/cloud/guides/security/audit-logging/byoc-security-playbook) to understand shared responsibility and best practices when ClickHouse Cloud operates within your environment. diff --git a/products/bring-your-own-cloud/reference/network-security.mdx b/products/bring-your-own-cloud/reference/network-security.mdx index b90203b39..844ecec0d 100644 --- a/products/bring-your-own-cloud/reference/network-security.mdx +++ b/products/bring-your-own-cloud/reference/network-security.mdx @@ -1,7 +1,7 @@ --- title: 'BYOC Network Security' slug: /cloud/reference/byoc/reference/network_security -sidebarTitle: 'Network Security' +sidebarTitle: 'Network security' keywords: ['BYOC', 'cloud', 'bring your own cloud', 'network security'] description: 'Deploy ClickHouse on your own cloud infrastructure' doc_type: 'reference' @@ -16,7 +16,7 @@ The ClickHouse Cloud control plane maintains several types of connections to ope | Purpose | Connection type | Notes | |---------|-----------------|-------| | **Daily operations — Kubernetes API server** | Public with IP filtering (default) or Tailscale | Management services talk to the EKS API server over the public network, restricted by IP allow lists. After initial deployment, you can optionally switch this to Tailscale for private access. | -| **Daily operations — AWS APIs** | ClickHouse VPC → AWS | Management services call AWS APIs (e.g., EKS, EC2) from ClickHouse Cloud’s own VPC to AWS. This does not involve your VPC or Tailscale. | +| **Daily operations — AWS APIs** | ClickHouse VPC → AWS | Management services call AWS APIs (e.g., EKS, EC2) from ClickHouse Cloud’s own VPC to AWS. This doesn't involve your VPC or Tailscale. | | **Troubleshooting — ClickHouse service** | Tailscale | ClickHouse engineers access the ClickHouse service (e.g., system tables) for diagnostics via Tailscale. | | **Troubleshooting — Kubernetes API server** | Tailscale | ClickHouse engineers access the EKS API server for cluster diagnostics via Tailscale. | @@ -76,11 +76,13 @@ The Tailscale connection establishment follows these steps: ### Security features {#tailscale-security} **Outbound-only connections**: + - Tailscale agents in your EKS cluster initiate outbound connections to the Tailscale coordination/relay servers - **No inbound connections are required** — no security group rules need to allow inbound traffic to Tailscale agents - This reduces the attack surface and simplifies network security configuration **Access control**: + - Engineers must request access through an internal approval workflow before Tailscale can route them to a customer endpoint - Access is time-bound and automatically expires - All access is audited and logged @@ -92,6 +94,7 @@ For the full data access policy — what engineers can see, certificate-based au By default, ClickHouse management services access your BYOC Kubernetes cluster via the EKS API server's public IP address, which is restricted to ClickHouse's NAT gateway IP addresses only. **Optional Private Endpoint Configuration**: + - You can configure the EKS API server to use only a private endpoint - In this case, management services access the API server via Tailscale (similar to human troubleshooting access) - Public access is kept as a backup mechanism for emergency investigation and support needs @@ -99,6 +102,7 @@ By default, ClickHouse management services access your BYOC Kubernetes cluster v ### Network Traffic Flow {#tailscale-traffic-flow} **Tailscale Connection Flow**: + 1. Tailscale agent in EKS cluster → Tailscale coordination server (outbound) 2. Tailscale agent on engineer's machine → Tailscale coordination server (outbound) 3. Direct or relayed connection established between agents @@ -106,6 +110,7 @@ By default, ClickHouse management services access your BYOC Kubernetes cluster v 5. Nginx pod in EKS terminates TLS and routes to internal services **No Customer Data Transmission**: + - Tailscale connections are used only for management and troubleshooting - Query traffic and customer data never flow through Tailscale - All customer data remains within your VPC @@ -123,7 +128,7 @@ This section covers different network traffic to and from the customer BYOC VPC: **Istio ingress is deployed behind an AWS NLB to accept ClickHouse client traffic.** -*Inbound, Public or Private* +_Inbound, Public or Private_ The Istio ingress gateway terminates TLS. The certificate, provisioned by CertManager with Let's Encrypt, is stored as a secret within the EKS cluster. Traffic between Istio and ClickHouse is [encrypted by AWS](https://docs.aws.amazon.com/whitepapers/latest/logical-separation/encrypting-data-at-rest-and--in-transit.html#:~:text=All%20network%20traffic%20between%20AWS,supported%20Amazon%20EC2%20instance%20types) since they reside in the same VPC. @@ -131,13 +136,13 @@ By default, ingress is publicly accessible with IP allow list filtering. Custome ### Troubleshooting access {#troubleshooting-access} -*Inbound, Private* +_Inbound, Private_ ClickHouse Cloud engineers require troubleshooting access via Tailscale. They're provisioned with just-in-time certificate-based authentication for BYOC deployments. See [ClickHouse data access](/products/bring-your-own-cloud/reference/clickhouse-data-access) for the full access policy. ### Billing scraper {#billing-scraper} -*Outbound, Private* +_Outbound, Private_ The Billing scraper collects billing data from ClickHouse and sends it to an S3 bucket owned by ClickHouse Cloud. @@ -145,7 +150,7 @@ It runs as a sidecar alongside the ClickHouse server container, periodically scr ### Alerts {#alerts} -*Outbound, Public* +_Outbound, Public_ AlertManager is configured to send alerts to ClickHouse Cloud when the customer's ClickHouse cluster is unhealthy. @@ -153,6 +158,6 @@ Metrics and logs are stored within the customer's BYOC VPC. Logs are currently s ### Service state {#service-state} -*Outbound, Public* +_Outbound, Public_ State Exporter sends ClickHouse service state information to an SQS owned by ClickHouse Cloud. diff --git a/products/cloud/guides/index.mdx b/products/cloud/guides/index.mdx index de8a69714..4ed06fe35 100644 --- a/products/cloud/guides/index.mdx +++ b/products/cloud/guides/index.mdx @@ -22,7 +22,6 @@ keywords: ['cloud guides', 'documentation', 'how-to', 'cloud features', 'tutoria | [AWS customized setup](/products/bring-your-own-cloud/onboarding/customization-aws) | Deploy ClickHouse BYOC into your existing AWS VPC | | [AWS PrivateLink](/products/cloud/guides/security/connectivity/private-networking/aws-privatelink) | This document describes how to connect to ClickHouse Cloud using AWS PrivateLink. | | [Azure Private Link](/products/cloud/guides/security/connectivity/private-networking/azure-privatelink) | How to set up Azure Private Link | -| [Azure Private Preview](/products/bring-your-own-cloud/onboarding/azure-private-preview) | Onboard ClickHouse BYOC on Azure using the Terraform module and cross-tenant authentication | | [Billable AWS services](/products/bring-your-own-cloud/reference/billable-aws-services) | AWS services provisioned by ClickHouse BYOC, classified as mandatory or optional, with notes on which ones contribute to your AWS bill | | [BYOC AWS private networking setup](/products/bring-your-own-cloud/onboarding/network-aws) | Set up VPC Peering or PrivateLink for BYOC on AWS | | [BYOC cost model (AWS)](/products/bring-your-own-cloud/reference/cost-model-aws) | How ClickHouse Cloud charges and AWS infrastructure charges combine into total cost of ownership for a BYOC deployment |