구성 요소
ClickHouse Connector는 세 개의 데몬을 실행하며, 모두clicklink 바이너리에 내장되어 있습니다:
- 실행기(executor) 는 커넥터 엔드포인트로 향하는 아웃바운드 명령 채널을 유지하며, ClickHouse Cloud가 사용자의 클러스터에서 관리하는 서비스에 대해 전송하는 수명 주기 명령어를 적용합니다. 해당 명령어에는 생성, 스케일링, 중지 및 시작, 재시작, 백업 및 백업 삭제, 삭제, 그리고 사용자가 승인한 플랫폼 업데이트가 포함됩니다. 모든 작업은 Kubernetes API 호출입니다. ClickHouse에 연결을 열지 않으며, 버킷이나 IAM에 대한 자격 증명도 보유하지 않습니다. 관리형 모드에서만 실행됩니다.
- 스크레이퍼(scraper) 는 허용 목록에 등록된 ClickHouse 시스템 테이블을 고정된 인터벌로 읽어 그 결과를 로컬에 버퍼링합니다. 이후 인프라 메타데이터 및 상태 정보와 함께 커넥터 엔드포인트로 전송합니다.
- Troubleshooter 는 커넥터 엔드포인트로 향하는 아웃바운드 명령 채널을 유지하며, 활성화된 지원 세션 동안 읽기 전용 진단을 실행합니다. 세션이 활성화되어 있지 않을 때는 아무것도 실행하지 않습니다.
clicklink-connector Helm 차트가 사용자가 선택한 네임스페이스(기본값 clicklink)에 데몬을 배포합니다. 실행기는 단일 레플리카 배포로, 명령 상태를 영구 볼륨에 보관합니다. Linux VM에서는 데몬이 권한 없는 clicklink 시스템 사용자 권한으로 clicklink-scraper, clicklink-troubleshooter, clicklink-executor systemd unit으로 실행됩니다.
연결
커넥터가 맺는 모든 연결은 아웃바운드입니다. 전체 목록은 다음과 같습니다:
모든 API 요청에는 메서드, 경로, 타임스탬프, 본문 해시에 대한 HMAC-SHA256 서명이 담긴
Authorization 헤더가 포함됩니다. TLS 채널 내부에서도 요청을 재전송하거나 변조할 수 없습니다.
인바운드의 경우 각 데몬은 로컬 health 포트를 하나씩 노출합니다. 스크레이퍼는 8082, troubleshooter는 8084, 실행기는 8086입니다. 해당 포트는 /livez, /readyz, /healthz를 제공하고 /metrics에서 데몬의 Prometheus 메트릭을 제공하며, 별도의 메트릭 포트는 없습니다. 실행기의 로컬 명령 API는 루프백에만 바인딩되며 이를 노출하는 Service는 없습니다. 그 외 유일한 리스너는 선택적 session gateway입니다. 지원 세션을 참조하십시오. ClickHouse Cloud는 이들 중 어느 것에도 연결하지 않습니다.
인증서 수명 주기
커넥터는 스스로 발급받아 관리하는 클라이언트 인증서로 엔드포인트에 인증합니다. 세 데몬 모두 동일한 인증서를 제시합니다.- 등록.
clicklink clctl init은 로컬에서 private key와 인증서 서명 요청(CSR)을 생성합니다. CSR에는 조직 ID가 common name으로, 엔드포인트 호스트가 유일한 DNS SAN으로 담깁니다. private key는 사용자 환경 밖으로 나가지 않습니다. - 최초 발급.
init은 HMAC으로 인증하여/v1/pcm/cert/sign등록 서명 엔드포인트에 CSR을 제출합니다. 해당 조직에 만료되지 않은 인증서가 이미 있으면 엔드포인트는 409로 요청을 거부합니다. 이 경우 CLI는 기존 인증서로 진행하는 방법과--force로 대체하는 방법을 안내합니다. - 자동 갱신. 세 데몬 모두 12시간마다 인증서 수명을 확인합니다. 남은 기간이 10일에 도달하면
/v1/pcm/cert/renew(mTLS 및 HMAC)를 통해 30일짜리 갱신 인증서를 요청합니다. Kubernetes에서는 정확한 이름을 지정한 RBAC 권한 부여를 통해 갱신된 인증서가clicklink-mtls시크릿에 다시 기록되고, VM에서는 각 데몬이/etc/clicklink/tls에 기록합니다. 갱신에는 운영자의 별도 조치가 필요하지 않습니다.
api.tls.ca_file(VM) 또는 api.tls.caFile(Helm)이 설정되어 있으면, 등록 번들의 CA 체인이 해당 루트 인증서에 추가됩니다.
데이터 흐름
환경 외부로 전송되는 항목
- 허용 목록에 포함된 시스템 테이블의 메트릭. 스크레이퍼의 기본 대상은
metric_log,asynchronous_metric_log,tables,warnings,server_settings입니다. 허용 목록은 명시적으로 구성되며, 스크레이퍼는 목록에 없는 항목을 읽지 않습니다. - 인프라 메타데이터. API를 통해 동기화되는 서비스, 인프라 및 백업 인벤토리입니다. 관리형 서비스의 경우 해당 서비스의 상태, 현재 및 예상 레플리카 수, 실행 중인 서버 버전과 구성 버전이 포함됩니다.
- 상태 및 자체 메트릭. 구성 요소 상태와 커넥터 자체의 운영 메트릭입니다. 실행기의 하트비트는 명령 채널의 연결 여부도 보고합니다. 여기에는 마지막 플랫폼 업데이트의 결과, 플랫폼 구성 요소 버전, 마지막으로 적용한 번들의 다이제스트가 포함됩니다. VM 설치 환경에서는 Kubernetes 액세스 번들이
ok,expiring,expired중 어느 상태인지 또는 존재하지 않는지를 추가로 전송합니다. - 명령 실행 결과. 실행기가 수행하는 각 수명 주기 명령에 대해, 수렴하는 동안의 진행 상황과 성공 여부, 실패 시 오류 텍스트를 전송합니다.
- 제출한 서비스 정의.
clicklink clctl instances create는 환경 ID, 클라우드 및 리전, 서비스 이름, 버킷 이름과 IAM 역할 ARN, 멱등성 키를 전송합니다. 또한 default 사용자 비밀번호의 두 가지 해시(SHA-256 및 이중 SHA-1)를 전송합니다. - 지원 세션 출력. 활성화한 세션 중 실행된 읽기 전용 진단 결과이며, 마스킹 후 제공됩니다.
기본적으로 외부로 절대 전송되지 않는 항목
- 스크레이프 경로의 원본 쿼리 텍스트.
system.query_log는 기본 스크레이프 대상에서 제외됩니다. 이 테이블의 쿼리 컬럼에는 리터럴 값이 포함될 수 있고, 그 안에 PII나 시크릿이 담길 수 있기 때문입니다. 이를 다시 추가하는 것은 배포별 재정의입니다. 기본 세션 테이블 허용 목록에는 실행 중인 쿼리의 텍스트를 보여주는system.processes가 포함되어 있습니다. 이를 정리하는 방법은 지원 세션을 참조하십시오. - 테이블 데이터와 백업. 사용자 계정 내의 버킷에 그대로 남아 있습니다. 실행기는 해당 버킷에 대한 자격 증명을 보유하지 않으므로 읽을 수 없습니다.
- 자격 증명.
init은 설정 파일에 자격 증명을 기록하지 않습니다. ClickHouse는 커넥터 사용자 비밀번호의 bcrypt 해시만 저장하며, 시크릿은 Kubernetes 시크릿 또는 호스트의 root 전용 읽기 파일에 보관됩니다. 관리형 서비스의 default 사용자 비밀번호는 사용자 측에서 생성되어 한 번만 표시되며, 전송되는 것은 해시뿐입니다. 스크레이프 경로와 동기화 경로 어디에서도 자격 증명을 전송하지 않습니다. - 마스킹되지 않은 troubleshooter 출력. Troubleshooter가 반환하는 모든 내용은 외부로 나가기 전에 민감 정보 마스킹 패턴(기본 제공 패턴 및 사용자가 정의한 패턴)을 거칩니다. 지원 세션을 참조하십시오.
신뢰 경계
- 사용자 환경이 곧 경계입니다. ClickHouse Cloud는 커넥터가 전송하는 것, 즉 스크레이프, 하트비트 및 상태, 명령 실행 결과, 활성 지원 세션이 반환하는 내용만 수신합니다. 내부로 연결을 먼저 시도하는 일은 결코 없습니다.
- 세션 게이트웨이는 사용자 소유입니다. Ingress를 통한 노출을 직접 선택하지 않는 한, 환경 내부에서만 접근할 수 있습니다(Kubernetes에서는
kubectl port-forward를 통해, VM에서는 로컬로). ClickHouse Cloud는 여기에 연결하지 않습니다. - ClickHouse 액세스는 읽기 전용입니다.
pcm_scraper및pcm_troubleshooter사용자는 테이블별SELECT권한 부여, 스크레이퍼의READ ON REMOTE(clusterAllReplicas()에 필요), 그리고 스크레이퍼 전용SYSTEM FLUSH LOGS권한 부여만 보유합니다.INSERT, DDL, 사용자 관리 권한 부여은 존재하지 않습니다. 실행기에는 ClickHouse 사용자가 없습니다. 정확한 목록은 권한 모델을 참조하십시오. - 스크레이퍼와 Troubleshooter는 클러스터를 변경할 수 없습니다. 이들의 RBAC는 커넥터 및 서비스 네임스페이스의 Role에서 비롯됩니다. 해당 Role은 워크로드 리소스에 대한 읽기 전용 동사와 커넥터 자체 시크릿에 대한 정확한 이름 기반 액세스만 부여합니다.
exec,delete,patch권한은 없습니다. - 실행기는
pcm-executor로서 서비스 네임스페이스의 클러스터 상태를 변경합니다. 서비스 접두사(기본값ns-)가 붙은 네임스페이스를 생성 및 삭제하고, 파드를 삭제하여 재시작합니다. 해당 네임스페이스 내부에서는 ClickHouseCluster, Backup, ScalingOverride 객체와 서비스에 필요한 시크릿, ServiceAccount, Service를 작성합니다. 또한 스크레이퍼에 읽기 액세스를 부여하는 Role 및 RoleBinding도 작성합니다. ValidatingAdmissionPolicy는 해당 ServiceAccount가 접두사 범위 밖에서 수행하는 모든 쓰기를 거부합니다. 예외는 모두 홈 네임스페이스 내에 있으며, 자체 토큰 갱신,clicklink-instance-registryConfigMap, 그리고 Kubernetes에서는 mTLS 시크릿의 갱신된 클라이언트 인증서입니다. 이 정책은 평가할 수 없을 때 거부(fail closed)로 동작합니다. admission은 읽기에는 적용되지 않으므로, 해당 리소스 계열에 대한 읽기는 접두사로 제한되지 않습니다. - 실행기는 사용자가 승인한 업데이트 중에만
pcm-platform으로서 플랫폼 네임스페이스를 변경합니다.clicklink clctl platform approve는 해당 아이덴티티의 토큰을 2시간 동안 발급하며, 갱신되지 않습니다. 이 토큰으로 실행기가 작성할 수 있는 대상은 배포, Service, ConfigMap, 시크릿, Job, PodDisruptionBudget뿐입니다. 네임스페이스, CRD, ServiceAccount, RBAC, 웹훅 및 admission 구성, PriorityClass, StorageClass는 승인 과정에서 사용자의 자격 증명으로 적용됩니다. 플랫폼 업데이트를 참조하십시오. - 실행기는 사용자의 버킷이나 IAM에 대한 자격 증명을 보유하지 않습니다.
clicklink clctl executor prepare는 서비스의 데이터 및 Backup 버킷과 IAM 역할을 생성합니다.clicklink clctl executor teardown은 이를 제거합니다. 두 명령 모두 사용자의 자격 증명으로 실행됩니다. 해당 역할은 그 서비스의 파드만 신뢰하므로 실행기도 ClickHouse도 이를 위임받을 수 없습니다. 실행기의 유일한 클라우드 호출 대상은 Amazon ECR과 STS입니다. 플랫폼 동기화나 생성 작업이 차트를 가져올 때 레지스트리에 로그인합니다. 플랫폼 업데이트 중에는 읽기 전용 pull 역할로 image를 확인합니다. - 네트워크 정책. Kubernetes에서는 차트가 각 데몬에 대해 기본 거부(default-deny) NetworkPolicy를 렌더링합니다. egress는 DNS, 커넥터 엔드포인트용으로 사용자가 나열한 CIDR, Kubernetes API 서버 CIDR로만 허용됩니다. 스크레이퍼 및 Troubleshooter 정책은 실행기가 관리하는 네임스페이스(실행기가 부여하는 레이블로 선택됨)나 사용자가 이름으로 나열한 네임스페이스의 ClickHouse 서비스에 대한 접근도 허용합니다. 실행기 정책에는 ClickHouse 규칙이 없습니다. 플랫폼 번들의 차트가 Amazon ECR에 있다면 ECR 및 STS 범위(또는 레지스트리 미러)를
allowEgressCIDRs에 추가하십시오. 그렇지 않으면 정책을 강제하는 CNI 환경에서 동기화가 차트를 가져올 수 없습니다. 정책을 강제하는 CNI가 없으면 정책은 효력이 없습니다. 구성을 참조하십시오. - VM의 호스트 강화. 유닛은
ProtectSystem=strict,NoNewPrivileges, 읽기 전용 구성 경로, FIPS 모드가 활성화된 상태에서 로그인이 불가능한 시스템 사용자로 실행됩니다.