标准引导流程

初始 BYOC 设置可通过 CloudFormation 模板 (AWS)、Terraform 模块 (GCP) 或 Terraform 模块 (Azure) 完成。该设置会创建一个具有高权限的身份 (IAM role/服务账号/服务主体) ，使 ClickHouse Cloud 中的 BYOC 控制器能够管理您的基础设施。

AWS 的 Terraform 模块

如果您希望在 AWS 部署中使用 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>"
}

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

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

AWS 外部 ID

在 AWS 上，设置期间创建的 IAM 角色会通过外部 ID (sts:ExternalId) 信任 ClickHouse Cloud，以防范混淆代理攻击。开始 Onboarding 时，ClickHouse Cloud 控制台会为您的 AWS 账户生成外部 ID，并在 CloudFormation 链接中预填该值；如果您使用 Terraform，请将同一值作为 external_id 传入。同一 AWS 账户中的所有 BYOC 基础设施共享同一个外部 ID。

系统将提示您通过 ClickHouse Cloud 控制台设置基础设施，包括对象存储桶、VPC/VNet 和 Kubernetes 集群。某些配置必须在此阶段确定，之后将无法更改。具体如下：

• 区域：我们支持的区域文档中列出的所有公有区域均可用于 BYOC 部署。目前尚不支持私有区域。

• VPC/VNet CIDR 范围：默认情况下，BYOC VPC (AWS/GCP) 或 VNet (Azure) 的 CIDR 范围为 10.0.0.0/16。如果计划与其他账户建立 VPC/VNet 对等连接，请确保 CIDR 范围不重叠。最小范围因云平台而异：

  • AWS：/23
  • Azure：/23
  • GCP：/20

  这些是最低要求，而非建议值：每个副本都会占用 IP 地址，因此规模较大的部署需要更大的范围。

• 可用区：如果计划使用 VPC 对等连接，将源账户与 BYOC 账户的可用区对齐有助于降低跨可用区流量成本。例如，在 AWS 中，可用区后缀 (a、b、c) 在不同账户中可能对应不同的物理可用区 ID。有关详细信息，请参阅 AWS 指南。

预检验证

当您点击 Set up Infrastructure 时，ClickHouse Cloud 会在创建任何资源之前，针对您的账户运行一组只读的预检检查。如果全部通过，预配将继续进行。如果某项检查未通过，设置将暂停，控制台会明确显示问题所在，以便您在创建任何资源之前予以修复。

这些检查会确认：

• 权限 — 管理身份 (IAM role / 服务账号 / 服务主体) 拥有 ClickHouse Cloud 预配和运行部署所需的权限。
• 已启用的服务 (GCP) — 您的项目已启用所需的 Google Cloud API (Compute Engine、Kubernetes Engine、Cloud Storage、Network Connectivity、IAM)。
• 网络 (AWS 自带 VPC) — 您的 VPC 和子网符合网络要求：包括子网大小、所需标签、可用区分布、出站连接和可用 IP 地址。
• 配额和防护措施 (AWS) — 您的账户拥有充足的服务配额 (VPC、NAT gateways、Elastic IPs、EKS clusters、vCPUs)，且没有任何组织策略 (SCP) 阻止执行所需操作。

当检查未通过时，每一项都会列出其对应的操作及失败原因 (例如 iam:CreateRole · explicitDeny) 。展开 Show passed checks 即可查看所有通过的检查项。

要解决这些失败，请重新运行最新的 ClickHouse CloudFormation 或 Terraform 堆栈 — 或将报告中列出的 actions 授予管理身份 (IAM role / 服务账号 / 服务主体) — 然后选择以下方式之一：

• 重新验证 — 重新运行预检。修复已报告的问题后，使用此选项确认设置已准备就绪，可进行预配。
• 仍要继续 — 即使检查失败也继续预配。仅当您确信报告的失败是误报时才使用此选项；否则预配很可能会中途失败。

请参照下表排查常见故障。