AWS 自定义配置

将 ClickHouse BYOC 部署到您现有的 AWS VPC 中

​

适用于 AWS 的客户管理的 VPC (BYO-VPC)

如果您希望使用现有 VPC 部署 ClickHouse BYOC，而不是由 ClickHouse Cloud 预配新的 VPC，请按照以下步骤操作。这样做可以让您更好地掌控网络配置，并将 ClickHouse BYOC 集成到现有的网络基础设施中。

1. 配置现有 VPC

   1. 为 VPC 添加标签 clickhouse-byoc="true"。
   2. 在 3 个不同的可用区中，恰好分配 3 个私有子网供 ClickHouse Cloud 使用。
   3. 确保每个子网的最小 CIDR 范围为 /25 (例如 10.0.0.0/25)。每个 /25 在每个可用区大约支持 10 个 ClickHouse server 节点；大多数部署建议使用 /24，预计会扩展的部署则应使用更大的子网。Pod IP 地址从子网本身分配，因此每个副本都会占用子网地址。
   4. 为每个子网添加标签 kubernetes.io/role/internal-elb=1 和 clickhouse-byoc="true"，以启用正确的负载均衡器配置。
2. 配置 S3 Gateway Endpoint

   如果您的 VPC 尚未配置 S3 Gateway Endpoint，则需要创建一个，以便在 VPC 与 Amazon S3 之间启用安全的私有通信。此端点可让您的 ClickHouse 服务在不经过公共互联网的情况下访问 S3。示例配置请参见下方截图。

3. 确保网络连通性

   出站互联网访问 您的 VPC 至少必须允许出站互联网访问，可通过直接访问或经由 NAT gateway 实现。有两项内容依赖于此：

   • Tailscale。 ClickHouse BYOC 组件会向 Tailscale 控制平面注册，该控制平面为私有管理操作提供安全的零信任网络，且无需开放入站公网访问。初始注册和设置需要公共互联网连通性。
   • 容器镜像。 部署运行的部分镜像并未镜像到 BYOC registry 中 (包括社区镜像) ，而是从其上游 registry 拉取。

   没有出站路径的 VPC 将无法完成预配。目前没有统一公布的端点清单；如果您的网络策略要求提供明确的清单，请联系支持团队以审阅您的设置。

   DNS 解析 确保您的 VPC 具备正常工作的 DNS 解析能力，且不会阻止、干扰或覆盖标准 DNS 名称。ClickHouse BYOC 依赖 DNS 来解析 Tailscale 控制服务器和 ClickHouse 服务端点。如果 DNS 不可用或配置不正确，BYOC 服务可能无法正常连接或运行。

4. 配置 AWS 账户

   初始 BYOC 设置会创建一个高权限 IAM 角色 (ClickHouseManagementRole)，使来自 ClickHouse Cloud 的 BYOC 控制器能够管理您的基础设施。这可以通过 CloudFormation 模板 或 Terraform 模块 (见下文) 完成。

   IAM 角色名称是硬性要求。 该角色必须保留其默认名称 ClickHouseManagementRole — 不得添加前缀、后缀，也不得为符合组织命名规范而重命名 — 除非 ClickHouse 事先明确同意使用其他名称 (Terraform 的 role_name 输入只能在与 ClickHouse 协调后更改) 。重命名的角色可以成功应用，但预配随后会失败，因为 ClickHouse 无法担任预期的角色。更一般地说，未经 ClickHouse 明确批准，请勿更改所提供模板或模块中的任何内容；支持的自定义项会以参数形式公开。

   部署 BYO-VPC 设置时，请将 IncludeVPCWritePermissions 参数设置为 false，以确保 ClickHouse Cloud 不会获得修改您客户管理的 VPC 的权限。

   运行 ClickHouse 所需的存储桶、Kubernetes 集群和计算资源不包含在此初始设置中。它们将在后续步骤中预配。虽然 VPC 由您自行控制，但 ClickHouse Cloud 仍需要 IAM 权限来创建和管理 Kubernetes 集群、服务账号的 IAM 角色、S3 bucket 以及您 AWS 账户中的其他必要资源。

   ​

   Terraform 模块

   如果您希望使用 Terraform 而不是 CloudFormation，请使用 terraform-byoc-onboarding 模块：

   module "clickhouse_onboarding" {
     source                        = "github.com/ClickHouse/terraform-byoc-onboarding.git//modules/aws?ref=<version>"
     external_id                   = "<external-id-provided-by-clickhouse>"
     include_vpc_write_permissions = false
   }
   

   将 <version> 替换为模块发行页面中的最新标签 — 始终使用最新发行版。

   该模块会输出 clickhouse_management_role_arn。在标准流程中，您无需对此执行任何操作 — 后续引导将在 ClickHouse Cloud 控制台中继续进行 — 但请保留好该值：如果您的设置偏离默认配置 (例如需要协调使用自定义角色名称) ，ClickHouse 将要求您提供该值。

   external_id 值由 ClickHouse Cloud 控制台生成，同一 AWS 账户中的所有 BYOC 基础设施共用该值。有关详细信息 (包括旧版 emptyid 占位符) ，请参阅 AWS 外部 ID。

   该模块此前以 tarball 形式发布在 https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/tf/byoc.tar.gz。该 URL 仍然可用，但已弃用 — 请使用上方的 GitHub 模块。

5. 设置 BYOC 基础设施

   点击 Set up Infrastructure 后，ClickHouse Cloud 会在预配前自动运行预检验证。如果您自定义的 VPC 或账户不符合要求，设置将暂停，并显示需要修复的具体问题。

   在 ClickHouse Cloud 控制台中，设置新基础设施时请配置以下内容：

   1. 在 VPC configuration 下，选择 Use existing VPC。
   2. 输入您的 VPC ID (例如 vpc-0bb751a5b888ad123) 。
   3. 输入您之前配置的 3 个子网对应的 Private subnet IDs。
   4. 如果您的配置需要面向公网的负载均衡器，可选填 Public subnet IDs。
   5. 点击 Set up Infrastructure 开始预配。

   新区域的设置最多可能需要 40 分钟。

​

来自其他账户的共享子网 (AWS RAM)

你可以在 spoke 账户中运行 BYOC，使用通过 AWS Resource Access Manager (RAM) 从 hub 账户共享而来的子网，从而实现网络的集中管理。配置方式与上文相同，只有两处差异，均源于 RAM 共享机制本身的特性：

• 在 spoke 账户中打标签。 RAM 共享的资源采用按账户隔离的标签视图，因此在 hub 账户中打的标签对 spoke 账户不可见。请在 spoke 账户中为 VPC 打上 clickhouse-byoc="true"，并为每个共享子网同时打上 kubernetes.io/role/internal-elb=1 和 clickhouse-byoc="true"。否则预检验证会报告标签缺失，预配将失败。
• 路由仍由 hub 账户负责。 共享子网的路由表仍归 hub 账户所有，因此 NAT 与出站流量路由由 hub 账户负责，S3 gateway 端点也是如此，因为它属于 VPC 级别的资源。请确认共享子网仍满足上文的出站连接要求。

其余均保持不变：跨三个可用区的三个私有子网、每个子网最小 /25 的 CIDR，以及在运行 BYOC 基础设施的 spoke 账户中配置 ClickHouseManagementRole。

​

客户管理的 IAM 角色

对于有高级安全要求或严格合规策略的组织，您可以提供自己的 IAM 角色，而不是由 ClickHouse Cloud 代为创建。这样一来，您就能完全掌控 IAM 权限，并可强制实施组织的安全策略。

客户管理的 IAM 角色目前处于私有预览阶段。在执行以下步骤之前，请先联系 ClickHouse 支持团队，为您的组织启用此能力。

使用客户管理的 IAM 角色时，您可以：

• 预先创建原本会由 ClickHouse Cloud 创建的各基础设施 IAM 角色
• 从用于跨账户访问的 ClickHouseManagementRole 中移除 IAM 写入权限
• 完全掌控角色权限和信任关系

以下两个模块都使用由 ClickHouse Cloud 控制台生成的 external_id；同一 AWS 账户中的所有 BYOC 基础设施共享同一个外部 ID。有关详细信息 (包括旧版 emptyid 占位符) ，请参阅 AWS 外部 ID。

1. 配置不含 IAM 写入权限的管理角色

   执行初始 BYOC 设置时，请在管理角色上禁用 IAM 写入权限。若使用 CloudFormation 模板，请将 IncludeIAMWritePermissions 参数设置为 false。若使用 Terraform 模块：

   module "clickhouse_onboarding" {
     source                        = "github.com/ClickHouse/terraform-byoc-onboarding.git//modules/aws?ref=<version>"
     external_id                   = "<external-id-provided-by-clickhouse>"
     include_iam_write_permissions = false
   }
   

   将 <version> 替换为该模块发行版页面中的最新标签——请始终使用最新发行版。

2. 创建各基础设施 IAM 角色

   在预配每个 BYOC 基础设施之前，使用 terraform-byoc-onboarding 的 per-infra 模块创建所需的 IAM 角色 (EKS pod identity 角色、ClickHouse S3 访问角色，以及数据平面管理角色) ：

   module "clickhouse_per_infra_iam" {
     source = "github.com/ClickHouse/terraform-byoc-onboarding.git//modules/aws-per-infra-iam?ref=<version>"
   
     spoken_name = "<spoken-name-provided-by-clickhouse>"
     region      = "<aws-region-of-the-infrastructure>"
     external_id = "<external-id-provided-by-clickhouse>"
   }
   

   将 <version> 替换为该模块发行版页面中的最新标签——请始终使用最新发行版。

3. 使各基础设施角色保持最新

   ClickHouse 会定期添加新平台能力所需的角色和权限。当 ClickHouse 通知您更新时，请使用最新发行版重新应用 per-infra 模块——如果运行过期版本，可能会导致您的 BYOC 基础设施预配和升级失败。

有关 ClickHouse Cloud 默认创建的 IAM 角色的信息，请参阅 BYOC Privilege Reference。