커넥터의 역할
ClickHouse Connector는 사용자 환경에 배포하는 구성 요소입니다. 이를 통해 ClickHouse Cloud는 사용자가 운영하는 Kubernetes 클러스터의 ClickHouse 서비스를 관리, 모니터링, 지원할 수 있습니다. 커넥터는 아웃바운드 연결만 수행하며, 해당 서비스로 범위가 한정된 아이덴티티로 동작합니다. 커넥터는 단일 바이너리clicklink로 제공되며, 여기에는 데몬과 이를 설치·운영하는 clicklink clctl 도구가 포함되어 있습니다.
커넥터는 세 가지 구성 요소로 이루어져 있습니다.
- 실행기는 ClickHouse에 관리를 요청한 서비스의 수명 주기를 실행합니다. 사용자가 제출한 정의로부터 각 서비스를 생성한 뒤, ClickHouse Cloud에서 전달된 scale, stop, start, restart, backup, delete 명령어를 적용합니다. 실행기를 구동하는 것을 관리형 모드라고 합니다.
- 스크레이퍼는 허용 목록에 등록된 ClickHouse 시스템 테이블에서 메트릭을 수집하고, 인프라 메타데이터와 상태 정보를 함께 모아 ClickHouse Cloud로 전송합니다.
- Troubleshooter는 사용자가 활성화하고 언제든 종료할 수 있는 지원 세션 동안 ClickHouse 지원 엔지니어가 읽기 전용 진단을 실행할 수 있게 합니다.
init을 실행하면 관리형 모드를 활성화할지 묻고 기본값으로 ‘예’가 선택되어 있습니다. 스크립트에서는 반드시 --managed를 전달해야 합니다. 관리형 모드가 없어도 커넥터는 사용자가 직접 운영하는 클러스터를 관측하고 지원합니다. 관리형 모드 없이 실행하기를 참조하십시오.
커넥터가 수행하는 모든 연결은 아웃바운드입니다. ClickHouse Cloud가 사용자 환경으로 연결을 먼저 시도하는 일은 없습니다. 아키텍처 페이지에서 각 연결과 해당 연결의 프로토콜, 인증 방식을 확인할 수 있습니다.
언제 사용해야 하는가
다음 제약 조건 하에서 ClickHouse Cloud가 사용자의 클라우드 계정 내에서 ClickHouse 서비스를 운영하도록 하려면 커넥터를 배포하십시오:- 모든 액세스 경로는 사용자의 경계 내부에서 시작되며, 인바운드 연결은 존재하지 않습니다.
- 클러스터에 대한 쓰기는 ClickHouse가 관리하는 서비스의 네임스페이스와, 실행기 자체의 홈 네임스페이스에 있는 실행기의 토큰, 레지스트리, 갱신된 인증서로 제한됩니다. 이러한 서비스가 의존하는 플랫폼 구성 요소는 사용자가 각 업데이트를 승인한 후에만 변경됩니다.
- 데이터는 사용자가 직접 생성하고 삭제하는 버킷과 IAM role 뒤에 보관됩니다. 실행기는 사용자의 버킷이나 IAM role에 대한 자격 증명을 보유하지 않습니다.
- 지원 액세스는 시간이 제한되며, 사용자가 직접 활성화하고 언제든지 취소할 수 있습니다. 모든 지원 세션 명령은 사용자가 소유한 감사 로그에 기록됩니다.
작동 방식
ClickHouse는 온보딩 과정에서 사용자 환경을 등록하고 엔드포인트와 일회용 등록 토큰을 제공합니다.clicklink clctl init --enroll은 한 번만 실행하면 됩니다. Kubernetes에 설치하는 경우 kubeconfig 액세스 권한이 있는 워크스테이션에서, Linux VM에 설치하는 경우 해당 호스트에서 실행합니다. 이 명령어는 토큰을 사용 처리하고, mTLS 클라이언트 인증서를 발급받으며, 데몬을 배포 및 시작하고 그 상태까지 확인합니다.
관리형 모드를 활성화하면 실행기가 배포되고 해당 Kubernetes 액세스 권한이 적용됩니다. 이 권한은 pcm-executor ServiceAccount 형태로 부여됩니다. admission 정책은 실행기의 쓰기 작업을 서비스 네임스페이스(기본 접두사 ns-)로 제한합니다. 예외는 자체 토큰 갱신, 레지스트리 ConfigMap 하나, 그리고 Kubernetes에서는 홈 네임스페이스에 저장되는 갱신된 클라이언트 인증서입니다.
서비스를 생성하려면 두 개의 명령어가 필요합니다. clicklink clctl executor prepare는 사용자의 AWS 자격 증명으로 해당 서비스의 버킷과 IAM role을 생성하고 default 사용자의 비밀번호를 한 번 표시합니다. clicklink clctl instances create는 엔드포인트를 통해 서비스 정의를 ClickHouse Cloud에 제출합니다. 이후 ClickHouse Cloud는 실행기의 아웃바운드 명령 채널을 통해 서비스를 제어합니다. 스케일링, 중지 및 시작, 재시작, 백업, 버전 업그레이드, 구성 변경이 여기에 포함됩니다. 전체 절차는 관리형 서비스를 참조하십시오.
두 가지 작업은 여전히 사용자 몫입니다. 클러스터 내 플랫폼 구성 요소의 업데이트는 사용자의 승인을 기다립니다. 플랫폼 업데이트를 참조하십시오. 서비스를 삭제하면 해당 Kubernetes 리소스만 제거되며, 버킷과 IAM role은 clicklink clctl executor teardown을 실행할 때까지 그대로 남아 있습니다.
스크레이퍼는 허용 목록에 등록된 시스템 테이블을 일정한 인터벌로 읽어 메트릭, 메타데이터, 상태 정보를 mTLS를 통해 엔드포인트로 전송합니다. troubleshooter는 아웃바운드 명령 채널을 열어 두지만, 지원 세션을 활성화하기 전까지 해당 채널로는 아무것도 전달되지 않습니다. mTLS 인증서는 스스로 갱신됩니다.
관리형 모드 없이 실행하기
clicklink clctl init 실행 시 --no-managed를 전달하거나 관련 질문에 아니오로 답하면 스크레이퍼와 Troubleshooter만 설치됩니다. 이때 커넥터는 사용자가 직접 운영하는 ClickHouse 클러스터를 관측하고 지원하며, ClickHouse는 서비스를 생성, 변경, 삭제할 수 없습니다. 이 경우에도 커넥터는 자체 배포를 수행하고 읽기 전용 ClickHouse 사용자와 ServiceAccount를 프로비저닝합니다. 자세한 내용은 권한 모델을 참조하십시오. 관리형 모드가 지원하지 않는 대상에도 동일한 구성이 적용됩니다. 관리형 모드는 S3 저장소를 사용하는 Amazon EKS에서 실행되며, 관측성 및 지원 기능은 규격을 준수하는 모든 Kubernetes 클러스터 또는 Linux 호스트에서 실행됩니다.
요구 사항 한눈에 보기
- 배포 대상. 관리형 모드에는 S3 저장소를 갖춘 Amazon EKS 클러스터가 필요합니다. 관측성과 지원 기능만 사용한다면 표준을 준수하는 모든 Kubernetes 클러스터(Helm 차트로 설치) 또는 amd64나 arm64 기반의 모든 systemd Linux 호스트에서 실행할 수 있습니다.
- ClickHouse의 등록. ClickHouse가 관리형 모드를 위해 사용자 환경을 등록하고, 온보딩 과정에서 엔드포인트와 일회용 등록 토큰을 제공합니다.
- 443 포트의 아웃바운드 네트워크 액세스. 엔드포인트와 해당 등록 엔드포인트, 그리고 설치 시점에는
releases.clicklink.clickhouse.com및 ECR Public에 대한 액세스가 필요합니다. 모든 단계마다 air-gapped 환경 및 미러링 대안이 마련되어 있습니다. 온보딩을 참조하십시오. 관리형 모드에서는 클러스터 노드가 사용자 환경이 등록된 레지스트리에서 ClickHouse image도 가져옵니다. 실행기는 ECR에서 플랫폼 차트를 가져올 때 Amazon ECR과 STS에 접근합니다. - 설정 중 클러스터 관리자 권한. 관리형 모드를 활성화하면 실행기의 액세스 권한이 한 번 적용됩니다. 여기에는 ServiceAccount, 여기에 바인딩된 클러스터 역할, 그리고 쓰기 작업을 서비스 네임스페이스로 제한하는 admission 정책이 포함됩니다. 플랫폼 업데이트 승인 역시 클러스터 관리자 권한으로 실행됩니다. 두 설치 대상 모두에서 troubleshooter의 access bundles는 Kubernetes ServiceAccount에 고정됩니다. 온보딩을 참조하십시오.
prepare와teardown을 위한 AWS 자격 증명, 그리고platform approve를 위한 레지스트리 액세스. 서비스의 버킷과 IAM role을 생성하는 작업은 사용자의 자격 증명으로 실행되며, 서비스 삭제 후 이를 제거하는 작업도 마찬가지입니다. 두 작업 모두 workstation 또는 커넥터 호스트에서 실행됩니다. ClickHouse의 레지스트리에 직접 액세스하는 경우, 플랫폼 승인 및 동기화는 커넥터 EC2 VM의 인스턴스 프로필을 통해 읽기 전용 pull role을 assume합니다. workstation의 AWS 프로필이나 SSO 자격 증명은 이 자격을 대체하지 않습니다. 다른 ECR 차트 레지스트리는 주변 환경의 AWS 자격 증명을 사용합니다. 레지스트리 자격 증명을 참조하십시오. 실행기는 사용자의 버킷이나 IAM에 대한 자격 증명을 절대 보유하지 않습니다. 실행기의 클라우드 호출은 차트 가져오기와 플랫폼 image 확인을 위한 Amazon ECR 및 STS로만 이루어집니다.- 연결할 수 있는 ClickHouse native listener. 사용자가 직접 운영하는 클러스터에 필요하며, 해당 클러스터는 실행기 없이 동작하는 별도의 커넥터 배포가 관측합니다. 스크레이퍼와 troubleshooter는 native protocol로 각 클러스터와 통신하며, Kubernetes에서는 보안(9440) 또는 plaintext(9000) 여부를 자동으로 감지합니다.
- 설정 중 ClickHouse admin 액세스. 사용자가 직접 운영하는 클러스터에 필요합니다. 초기 프로비저닝 시 커넥터의 읽기 전용 사용자가 생성됩니다. admin password가 설정되어 있다면 한 번만 입력을 요청하며 저장하지 않습니다.
다음 단계
- 온보딩: Kubernetes 또는 Linux VM에 커넥터를 설치하고 등록합니다.
- 관리형 서비스: 관리형 모드를 활성화하고 서비스를 생성하며, 수명 주기, 상태, 삭제 과정을 따릅니다.
- 플랫폼 업데이트: 클러스터 내 플랫폼 구성 요소에 대한 변경 사항을 승인합니다.
- 아키텍처: 구성 요소, 각 연결, 인증서 수명 주기, 환경 외부로 전송되는 데이터를 설명합니다.
- 지원 세션: 지원 액세스를 활성화, 범위 지정, 감사, 취소하는 방법을 설명합니다.
- 구성 및 운영: 튜닝, 업그레이드 및 운영 2일 차 작업을 다룹니다.
- FAQ: 누가 서비스를 변경할 수 있는지, 데이터 이그레스 및 액세스 취소를 포함한 일반적인 질문을 다룹니다.