From dd3eb5ee7d361cfe01fbd2769ad09780baf8d3d7 Mon Sep 17 00:00:00 2001 From: Shiqiang Duan Date: Sun, 12 Jul 2026 21:07:01 +0800 Subject: [PATCH 1/3] docs(byoc): document AWS VPC Lattice option for Kubernetes API private connection --- .../byoc/05_configuration.md | 19 +++++++++++++++++-- .../byoc/08_reference/03_network_security.md | 4 ++-- 2 files changed, 19 insertions(+), 4 deletions(-) diff --git a/docs/cloud/guides/infrastructure/01_deployment_options/byoc/05_configuration.md b/docs/cloud/guides/infrastructure/01_deployment_options/byoc/05_configuration.md index 262f46f8847..20faf6e4675 100644 --- a/docs/cloud/guides/infrastructure/01_deployment_options/byoc/05_configuration.md +++ b/docs/cloud/guides/infrastructure/01_deployment_options/byoc/05_configuration.md @@ -54,13 +54,28 @@ For step-by-step setup instructions, see the [Private Networking Setup guide](/c ## Kubernetes API Private Connection {#k8s-api-private-connection} -By default, the Kubernetes API server endpoint for your BYOC cluster is accessible from the public internet, but access is restricted with IP filtering to allow only ClickHouse NAT Gateway IPs. For stronger security, you can restrict the Kubernetes API server so that it is accessible exclusively through private network connections using Tailscale. +By default, the Kubernetes API server endpoint for your BYOC cluster is accessible from the public internet, but access is restricted with IP filtering to allow only ClickHouse NAT Gateway IPs. For stronger security, you can restrict the Kubernetes API server so that it is accessible exclusively through private network connections. + +Two private connection options are available: + +### Tailscale (default) {#k8s-api-private-connection-tailscale} + +When a private API endpoint is enabled, ClickHouse management services connect to the Kubernetes API server through the same Tailscale zero-trust network used for troubleshooting access. See [Tailscale Private Network](/cloud/reference/byoc/reference/network_security#tailscale-private-network) for details on how this connection works. :::note If you rely solely on Tailscale for private connectivity, there is a risk that ClickHouse Support will lose access to your environment if the Tailscale agent becomes unavailable. This could delay troubleshooting or support response times. ::: -**Contact ClickHouse Support** to request configuration of a private API endpoint. +### AWS VPC Lattice {#k8s-api-private-connection-vpc-lattice} + +For AWS deployments, the Kubernetes API server can instead be reached privately over [AWS VPC Lattice](https://aws.amazon.com/vpc/lattice/), with no third-party components involved: + +- ClickHouse Cloud automatically provisions a VPC Lattice Resource Gateway and a Resource Configuration targeting the EKS API server endpoint inside your BYOC VPC, and shares the Resource Configuration with the ClickHouse Cloud management account via AWS Resource Access Manager (RAM). +- Traffic between ClickHouse management services and your Kubernetes API server stays entirely on the AWS private network. +- The RAM share is created from your account and scoped to a single BYOC cluster; deleting it immediately revokes the private access path. +- Because access does not depend on an agent running inside your Kubernetes cluster, ClickHouse Support retains access for troubleshooting even if in-cluster components are unavailable. + +**Contact ClickHouse Support** to request configuration of a private API endpoint, or to enable VPC Lattice connectivity for an AWS deployment. ## Node Groups {#node-groups} diff --git a/docs/cloud/guides/infrastructure/01_deployment_options/byoc/08_reference/03_network_security.md b/docs/cloud/guides/infrastructure/01_deployment_options/byoc/08_reference/03_network_security.md index d9f27ecbd0f..80f2c617e08 100644 --- a/docs/cloud/guides/infrastructure/01_deployment_options/byoc/08_reference/03_network_security.md +++ b/docs/cloud/guides/infrastructure/01_deployment_options/byoc/08_reference/03_network_security.md @@ -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 — Kubernetes API server** | Public with IP filtering (default), or private via Tailscale or AWS VPC Lattice | 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 private access via Tailscale or, on AWS, VPC Lattice. | | **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. | @@ -97,7 +97,7 @@ By default, ClickHouse management services access your BYOC Kubernetes cluster v **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) +- In this case, management services access the API server via Tailscale (similar to human troubleshooting access) or, on AWS, via VPC Lattice (see [Kubernetes API Private Connection](/cloud/reference/byoc/configurations#k8s-api-private-connection)) - Public access is kept as a backup mechanism for emergency investigation and support needs ### Network Traffic Flow {#tailscale-traffic-flow} From 2e2bfc32b2165e161ac01c6e426a43ab17c73e53 Mon Sep 17 00:00:00 2001 From: Shiqiang Duan Date: Sun, 12 Jul 2026 21:19:10 +0800 Subject: [PATCH 2/3] chore(vale): allow 'VPC Lattice' in heading capitalization exceptions --- styles/ClickHouse/Headings.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/styles/ClickHouse/Headings.yml b/styles/ClickHouse/Headings.yml index f8fec5d3fde..70bed2ea2b2 100644 --- a/styles/ClickHouse/Headings.yml +++ b/styles/ClickHouse/Headings.yml @@ -168,6 +168,7 @@ exceptions: - VLDB - VS - VPC + - "VPC Lattice" - Vitess - Visual - Windows From fcacaffaf6a6bbc9304cf72b72258344dd427bf1 Mon Sep 17 00:00:00 2001 From: Shiqiang Duan Date: Mon, 13 Jul 2026 12:20:49 +0800 Subject: [PATCH 3/3] docs(byoc): mark VPC Lattice K8s API connectivity as private preview --- .../01_deployment_options/byoc/05_configuration.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/cloud/guides/infrastructure/01_deployment_options/byoc/05_configuration.md b/docs/cloud/guides/infrastructure/01_deployment_options/byoc/05_configuration.md index 20faf6e4675..7650c059b15 100644 --- a/docs/cloud/guides/infrastructure/01_deployment_options/byoc/05_configuration.md +++ b/docs/cloud/guides/infrastructure/01_deployment_options/byoc/05_configuration.md @@ -68,6 +68,10 @@ If you rely solely on Tailscale for private connectivity, there is a risk that C ### AWS VPC Lattice {#k8s-api-private-connection-vpc-lattice} +:::info +VPC Lattice connectivity is currently in private preview. Contact ClickHouse Support to enable it for your deployment. +::: + For AWS deployments, the Kubernetes API server can instead be reached privately over [AWS VPC Lattice](https://aws.amazon.com/vpc/lattice/), with no third-party components involved: - ClickHouse Cloud automatically provisions a VPC Lattice Resource Gateway and a Resource Configuration targeting the EKS API server endpoint inside your BYOC VPC, and shares the Resource Configuration with the ClickHouse Cloud management account via AWS Resource Access Manager (RAM). @@ -75,7 +79,7 @@ For AWS deployments, the Kubernetes API server can instead be reached privately - The RAM share is created from your account and scoped to a single BYOC cluster; deleting it immediately revokes the private access path. - Because access does not depend on an agent running inside your Kubernetes cluster, ClickHouse Support retains access for troubleshooting even if in-cluster components are unavailable. -**Contact ClickHouse Support** to request configuration of a private API endpoint, or to enable VPC Lattice connectivity for an AWS deployment. +**Contact ClickHouse Support** to request configuration of a private API endpoint. ## Node Groups {#node-groups}