AWS 사용자 지정 설정

기존 AWS VPC에 ClickHouse BYOC를 배포

​

AWS용 고객 관리형 VPC(BYO-VPC)

ClickHouse Cloud가 새 VPC를 프로비저닝하는 대신 기존 VPC를 사용해 ClickHouse BYOC를 배포하려면 아래 단계를 따르십시오. 이 방식은 네트워크 구성에 대한 제어 범위를 넓혀 주며, ClickHouse BYOC를 기존 네트워크 인프라에 통합할 수 있도록 합니다.

1. 기존 VPC 구성

   1. VPC에 clickhouse-byoc="true" 태그를 추가합니다.
   2. ClickHouse Cloud에서 사용할 수 있도록 서로 다른 3개의 가용 영역에 걸쳐 정확히 3개의 프라이빗 서브넷을 할당합니다.
   3. 각 서브넷이 최소 /25 CIDR 범위(예: 10.0.0.0/25)를 사용하는지 확인합니다. /25는 가용 영역당 약 10개의 ClickHouse 서버 노드를 지원합니다. 대부분의 배포에는 /24를 권장하며, 확장이 예상되는 배포에는 더 큰 서브넷을 권장합니다. 파드 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 레지스트리에 미러링되어 있지 않으며, 해당 업스트림 레지스트리에서 가져옵니다.

   아웃바운드 경로가 없는 VPC는 프로비저닝을 완료할 수 없습니다. 공개된 단일 엔드포인트 목록은 없으며, 네트워크 정책상 명시적인 목록이 필요한 경우 지원팀에 문의하여 설정을 검토받으십시오.

   DNS 확인 VPC에서 DNS 확인이 정상적으로 작동하고, 표준 DNS 이름을 차단하거나 간섭하거나 덮어쓰지 않는지 확인합니다. ClickHouse BYOC는 DNS를 사용해 Tailscale 컨트롤 서버와 ClickHouse 서비스 엔드포인트를 확인합니다. DNS를 사용할 수 없거나 잘못 구성된 경우, BYOC 서비스가 연결에 실패하거나 제대로 작동하지 않을 수 있습니다.

4. AWS 계정 구성

   초기 BYOC 설정에서는 ClickHouse Cloud의 BYOC 컨트롤러가 인프라를 관리할 수 있도록 권한 있는 IAM 역할(ClickHouseManagementRole)을 생성합니다. 이는 CloudFormation 템플릿 또는 Terraform 모듈(아래 참조)을 사용해 수행할 수 있습니다.

   IAM 역할 이름은 반드시 준수해야 합니다. ClickHouse가 사전에 다른 이름에 명시적으로 동의한 경우를 제외하고, 역할은 기본 이름인 ClickHouseManagementRole을 그대로 유지해야 합니다. 즉, 조직의 명명 규칙을 충족하기 위한 프리픽스, 서픽스 추가 또는 이름 변경은 허용되지 않습니다(Terraform role_name 입력은 ClickHouse와 협의한 경우에만 변경해야 합니다). 이름이 변경된 역할은 성공적으로 적용되지만 ClickHouse가 예상한 역할을 assume할 수 없으므로 프로비저닝이 실패합니다. 또한 ClickHouse의 명시적 승인 없이 제공된 템플릿이나 모듈의 어떤 항목도 변경하지 마십시오. 지원되는 사용자 지정은 매개변수로 제공됩니다.

   BYO-VPC 구성으로 배포하는 경우, ClickHouse Cloud가 고객 관리형 VPC를 수정할 권한을 받지 않도록 IncludeVPCWritePermissions 매개변수를 false로 설정하십시오.

   ClickHouse 실행에 필요한 스토리지 버킷, Kubernetes 클러스터, 컴퓨트 리소스는 이 초기 설정에 포함되지 않습니다. 이러한 항목은 이후 단계에서 프로비저닝됩니다. VPC는 직접 제어하더라도, ClickHouse Cloud는 AWS 계정에서 Kubernetes 클러스터, 서비스 계정용 IAM 역할, S3 버킷 및 기타 필수 리소스를 생성하고 관리할 수 있는 IAM 권한이 여전히 필요합니다.

   ​

   Terraform 모듈

   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>"
     include_vpc_write_permissions = false
   }
   

   <version>을 모듈의 릴리스 페이지에 있는 최신 태그로 대체하십시오. 항상 최신 릴리스를 사용하십시오.

   모듈은 clickhouse_management_role_arn을 출력합니다. 표준 흐름에서는 별도의 조치가 필요하지 않으며 온보딩은 ClickHouse Cloud 콘솔에서 계속 진행됩니다. 다만 기본값과 다른 설정을 사용하는 경우(예: 조율된 사용자 지정 역할 이름) ClickHouse에서 이를 요청할 수 있으므로 준비해 두십시오.

   external_id 값은 ClickHouse Cloud 콘솔에서 생성되며 동일한 AWS 계정의 모든 BYOC 인프라에서 공유됩니다. 레거시 emptyid 플레이스홀더를 포함한 자세한 내용은 AWS 외부 ID를 참조하십시오.

   이 모듈은 이전에 https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/tf/byoc.tar.gz에서 tarball 형태로 배포되었습니다. 해당 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)

AWS Resource Access Manager(RAM)를 사용하면 허브 계정에서 공유한 서브넷 위에서 스포크 계정으로 BYOC를 실행할 수 있으며, 이를 통해 네트워킹을 중앙에서 관리할 수 있습니다. 설정 방법은 위와 동일하지만, RAM 공유의 동작 방식에서 비롯되는 두 가지 차이가 있습니다.

• 태그는 스포크 계정에서 적용하십시오. RAM으로 공유된 리소스는 계정별로 태그를 따로 보기 때문에, 허브 계정에서 적용한 태그는 스포크 계정에 표시되지 않습니다. 스포크 계정에서 VPC에는 clickhouse-byoc="true"를, 각 공유 서브넷에는 kubernetes.io/role/internal-elb=1과 clickhouse-byoc="true"를 함께 적용하십시오. 그렇지 않으면 사전 점검 유효성 검사에서 태그 누락이 보고되어 Provisioning이 실패합니다.
• 라우팅은 허브 계정이 담당합니다. 공유 서브넷의 라우트 테이블은 여전히 허브 계정이 소유하므로, NAT 및 egress 라우팅과 VPC 수준 리소스인 S3 gateway endpoint에 대한 책임도 허브 계정에 있습니다. 공유 서브넷이 위의 아웃바운드 연결 요구 사항을 여전히 충족하는지 확인하십시오.

그 외의 사항은 동일합니다. 3개의 가용 영역에 걸친 3개의 프라이빗 서브넷, 서브넷당 최소 /25 CIDR, 그리고 BYOC 인프라가 실행되는 스포크 계정의 ClickHouseManagementRole 설정이 필요합니다.

​

고객 관리형 IAM 역할

고급 보안 요구 사항이나 엄격한 컴플라이언스 정책이 있는 조직에서는 ClickHouse Cloud가 IAM 역할을 생성하도록 하는 대신 자체 IAM 역할을 제공할 수 있습니다. 이 방식은 IAM 권한을 완전히 제어할 수 있게 해 주며, 조직의 보안 정책을 강제 적용할 수 있도록 합니다.

고객 관리형 IAM 역할은 비공개 프리뷰 상태입니다. 아래 단계를 진행하기 전에 조직에서 이 기능을 사용할 수 있도록 ClickHouse 지원팀에 문의하십시오.

고객 관리형 IAM 역할을 사용하면 다음이 가능합니다.

• ClickHouse Cloud가 원래 생성했을 인프라별 IAM 역할을 미리 생성합니다
• 교차 계정 액세스에 사용되는 ClickHouseManagementRole에서 IAM 쓰기 권한을 제거합니다
• 역할 권한과 신뢰 관계를 완전히 제어합니다

아래 두 모듈은 ClickHouse Cloud 콘솔에서 생성된 external_id를 사용합니다. 동일한 AWS 계정의 모든 BYOC 인프라는 동일한 external ID를 공유합니다. 기존 emptyid placeholder를 포함한 자세한 내용은 AWS external 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>은 module의 releases page에서 최신 태그로 바꾸십시오. 항상 최신 release를 사용하십시오.

2. 인프라별 IAM 역할 생성

   각 BYOC 인프라가 Provisioning되기 전에 terraform-byoc-onboarding per-infra module을 사용하여 필요한 IAM 역할(EKS 파드 아이덴티티 역할, 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>은 module의 releases page에서 최신 태그로 바꾸십시오. 항상 최신 release를 사용하십시오.

3. 인프라별 역할을 최신 상태로 유지

   ClickHouse는 새로운 플랫폼 기능에 필요한 역할과 권한을 주기적으로 추가합니다. ClickHouse에서 업데이트를 안내하면 최신 release의 per-infra module을 다시 적용하십시오. 오래된 버전을 사용하면 BYOC 인프라의 Provisioning 및 upgrade가 실패할 수 있습니다.

ClickHouse Cloud가 기본적으로 생성하는 IAM 역할에 대한 자세한 내용은 BYOC Privilege Reference를 참조하십시오.