표준 온보딩

초기 BYOC 설정은 CloudFormation 템플릿(AWS), Terraform 모듈(GCP) 또는 Terraform 모듈(Azure)을 사용하여 수행할 수 있습니다. 이 과정에서 높은 권한을 가진 아이덴티티(IAM role/service account/service principal)가 생성되며, ClickHouse Cloud의 BYOC 컨트롤러가 인프라를 관리할 수 있게 됩니다.

AWS용 Terraform 모듈

AWS 배포에서 CloudFormation 대신 Terraform을 사용하려면 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을 출력합니다. 표준 절차에서는 별도로 처리할 필요가 없으며 온보딩은 ClickHouse Cloud 콘솔에서 계속 진행됩니다. 다만 기본 설정과 다른 구성을 사용하는 경우(예: 조율된 사용자 지정 역할 이름) ClickHouse에서 이를 요청하므로 보관해 두십시오.

AWS 외부 ID

AWS에서는 설정 중 생성된 IAM 역할이 혼동된 대리인 공격을 방지하기 위해 외부 ID(sts:ExternalId)를 통해 ClickHouse Cloud를 신뢰하도록 구성됩니다. 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 범위가 겹치지 않도록 하십시오. 최소 크기는 Cloud마다 다릅니다:

  • AWS: /23
  • Azure: /23
  • GCP: /20

  이는 권장 사항이 아닌 최소 기준입니다. 레플리카마다 IP 주소를 사용하므로 규모가 큰 배포에는 더 큰 범위가 필요합니다.

• 가용 영역: VPC 피어링을 사용할 계획이라면 소스 계정과 BYOC 계정의 가용 영역을 일치시키면 AZ 간 트래픽 비용을 줄이는 데 도움이 될 수 있습니다. 예를 들어 AWS에서는 가용 영역 접미사(a, b, c)가 계정마다 서로 다른 물리적 영역 ID를 나타낼 수 있습니다. 자세한 내용은 AWS 가이드를 참조하십시오.

사전 유효성 검사

Set up Infrastructure를 클릭하면 ClickHouse Cloud는 리소스를 생성하기 전에 계정을 대상으로 일련의 읽기 전용 사전 점검을 실행합니다. 모든 점검을 통과하면 프로비저닝이 계속 진행됩니다. 점검에 실패하면 설정이 일시 중지되고 콘솔에 문제가 무엇인지 정확히 표시되므로, 리소스가 생성되기 전에 문제를 해결할 수 있습니다.

이 check는 다음을 확인합니다:

• 권한 — 관리 아이덴티티(IAM role / service account / service principal)에 ClickHouse Cloud가 배포를 프로비저닝하고 운영하는 데 필요한 권한이 부여되어 있습니다.
• 활성화된 서비스 (GCP) — 필요한 Google Cloud API(Compute Engine, Kubernetes Engine, Cloud Storage, Network Connectivity, IAM)가 프로젝트에서 활성화되어 있습니다.
• 네트워크 (AWS 자체 VPC 사용) — VPC와 서브넷이 서브넷 크기, 필수 태그, 가용 영역 분산, 아웃바운드 연결, 사용 가능한 IP 주소에 관한 네트워크 요구 사항을 충족합니다.
• 쿼터 및 보호 장치 (AWS) — 계정에 충분한 서비스 쿼터(VPC, NAT gateway, Elastic IP, EKS 클러스터, vCPUs)가 있으며, organization policy(SCP)로 인해 필수 작업이 차단되지 않습니다.

검사에 실패하면 각 항목이 매핑된 작업 및 실패 사유와 함께 나열됩니다(예: iam:CreateRole · explicitDeny). 성공한 항목을 모두 확인하려면 Show passed checks를 펼치십시오.

이러한 실패를 해결하려면 최신 ClickHouse CloudFormation 또는 Terraform 스택을 다시 실행하거나, 보고된 actions를 관리용 아이덴티티(IAM role / service account / service principal)에 부여한 후 다음 중 하나를 선택하십시오:

• 다시 확인 — 사전 점검을 다시 실행합니다. 보고된 문제를 수정한 후 프로비저닝을 시작하기 전에 설정이 준비되었는지 확인할 때 사용하십시오.
• 그래도 진행 — 실패한 점검에도 불구하고 프로비저닝을 계속합니다. 보고된 실패가 거짓 양성이라고 확신하는 경우에만 사용하십시오. 그렇지 않으면 프로비저닝 도중 실패할 가능성이 높습니다.

자주 발생하는 오류는 아래 표를 참고하여 해결하십시오.