> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 아키텍처
> ClickHouse Connector 구성 요소, 연결, 인증서 수명 주기 및 데이터 흐름
export const Image = ({img, alt, size = "lg", background}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
return ;
};
## 구성 요소
ClickHouse Connector는 `clicklink` 바이너리에 내장된 두 개의 데몬을 실행합니다.
* **스크레이퍼**는 정해진 간격으로 허용 목록에 있는 ClickHouse 시스템 테이블을 읽고, 결과를 로컬에 버퍼링한 뒤 인프라 메타데이터 및 상태 정보와 함께 커넥터 엔드포인트로 전송합니다.
* **문제 해결 도구**는 커넥터 엔드포인트로 연결되는 아웃바운드 명령 채널을 유지하고, 활성 [지원 세션](/docs/ko/products/bring-your-own-cloud/connector/support-sessions) 중에 읽기 전용 진단을 실행합니다. 세션 외에는 아무 작업도 수행하지 않습니다.
Kubernetes에서는 선택한 네임스페이스(기본값: `clicklink`)에서 `clicklink-connector` Helm 차트로 배포된 워크로드로 두 구성 요소가 모두 실행됩니다. Linux VM에서는 권한이 없는 `clicklink` 시스템 사용자로 `clicklink-scraper` 및 `clicklink-troubleshooter` systemd 유닛을 실행합니다.
## 연결
커넥터에서 이루어지는 모든 연결은 아웃바운드입니다. 전체 목록은 다음과 같습니다.
| 대상 | 방향 | 프로토콜 | 인증 | 용도 |
| ---------------------------------------------------- | ------------ | -------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 커넥터 엔드포인트(API) | 아웃바운드 | HTTPS | mTLS 클라이언트 인증서 및 HMAC 서명 요청 | 메트릭, 커넥터 자체 메트릭 및 상태를 전송하고, 인스턴스, 인프라, 백업 메타데이터를 동기화하며 클라이언트 인증서를 갱신합니다. |
| 커넥터 엔드포인트(명령 채널) | 아웃바운드 | TLS를 통한 WebSocket | mTLS 클라이언트 인증서 및 HMAC 서명 핸드셰이크 | 문제 해결 도구 명령 채널입니다. 지원 세션이 활성화된 동안에만 명령을 전송합니다. |
| 등록 엔드포인트 | 아웃바운드 | HTTPS | 일회용 등록 토큰(교환) 또는 HMAC(최초 인증서 서명), mTLS 없음 | 설정 중 토큰을 교환하고 최초 인증서를 발급합니다. |
| ClickHouse 클러스터 | 아웃바운드, 환경 내부 | ClickHouse 네이티브 프로토콜 | bcrypt 해시로 저장된 전용 읽기 전용 사용자 `pcm_scraper` 및 `pcm_troubleshooter` | 스크레이프 및 세션 진단을 위한 시스템 테이블 읽기와 스크레이퍼의 로그 테이블 플러시를 수행합니다. |
| Kubernetes API server(프로비저닝된 모든 배포, 두 설치 대상 모두) | 아웃바운드, 환경 내부 | HTTPS | 네임스페이스 범위 역할에 바인딩된 ServiceAccount | 문제 해결 도구를 위한 읽기 전용 워크로드 뷰를 제공합니다. Kubernetes 설치에서는 두 데몬 모두 자동으로 갱신된 클라이언트 인증서를 mTLS 시크릿에 다시 저장합니다. |
| IdP(Identity Provider)의 JWKS 엔드포인트(게이트웨이가 활성화된 경우에만) | 아웃바운드 | HTTPS | 없음(공개 서명 키) | 세션 게이트웨이에 제공된 OIDC ID 토큰을 검증합니다. |
모든 API 요청에는 메서드, 경로, 타임스탬프 및 본문 해시를 기반으로 계산한 HMAC-SHA256 서명이 포함된 `Authorization` 헤더가 포함됩니다. 따라서 TLS 채널 내부에서도 요청을 재생하거나 전송 중 변조할 수 없습니다.
인바운드 연결에서 커넥터는 로컬 상태 점검 및 메트릭 포트와 [지원 세션](/docs/ko/products/bring-your-own-cloud/connector/support-sessions) 페이지에 설명된 선택적 세션 게이트웨이만 노출합니다. ClickHouse의 컨트롤 플레인은 이들 중 어느 곳에도 연결하지 않습니다.
## 인증서 수명 주기
커넥터는 자체적으로 발급받아 관리하는 클라이언트 인증서로 엔드포인트를 인증합니다.
* **등록.** `clicklink clctl init`는 로컬에서 private key와 인증서 서명 요청을 생성합니다. 인증서 서명 요청에는 조직 ID가 공통 이름으로, 엔드포인트 host가 유일한 DNS SAN으로 포함됩니다. private key는 환경 외부로 절대 유출되지 않습니다.
* **최초 발급.** CSR은 HMAC으로 인증된 상태에서 `/v1/pcm/cert/sign` 등록 서명 엔드포인트로 제출됩니다. 조직에 아직 만료되지 않은 인증서가 있으면 엔드포인트는 409 응답으로 요청을 거부하며, CLI는 기존 인증서로 완료하는 방법 또는 `--force`를 사용하여 의도적으로 대체하는 방법을 출력합니다.
* **자동 갱신.** 각 데몬은 12시간마다 인증서 lifetime을 확인하며, 남은 기간이 10일이 되면 `/v1/pcm/cert/renew`(mTLS 및 HMAC)를 통해 갱신된 유효 기간 30일의 인증서를 요청합니다. Kubernetes에서는 각 데몬이 정확한 이름의 RBAC 권한을 통해 갱신된 인증서를 `clicklink-mtls` 시크릿에 다시 기록합니다. VM에서는 데몬 사용자가 TLS directory에 쓸 수 있습니다. 갱신을 위해 별도의 작업은 필요하지 않습니다.
커넥터는 system trust store를 기준으로 엔드포인트의 server certificate를 검증합니다. 엔드포인트가 사설 CA를 사용하는 경우에는 등록 시 제공되는 CA bundle을 사용합니다.
## 데이터 흐름
### 환경 외부로 전송되는 항목
* **허용 목록에 포함된 시스템 테이블의 메트릭.** 스크레이퍼의 기본 대상은 `metric_log`, `asynchronous_metric_log`, `tables`, `warnings`, `server_settings`입니다. 허용 목록은 명시적으로 구성되며, 스크레이퍼는 목록에 없는 항목을 읽지 않습니다.
* **인프라 메타데이터.** API를 통해 동기화되는 인스턴스, 인프라 및 백업 인벤토리입니다.
* **상태 및 자체 메트릭.** 구성 요소 상태와 커넥터 자체의 운영 메트릭입니다.
* **지원 세션 출력.** 활성화한 세션 중 실행된 읽기 전용 진단 결과이며, 마스킹 후 제공됩니다.
### 기본적으로 외부로 나가지 않는 항목
* **스크레이프 경로의 원본 쿼리 텍스트.** `system.query_log`는 쿼리 컬럼에 리터럴 값, PII 또는 시크릿이 포함될 수 있으므로 기본 스크레이프 대상에서 의도적으로 제외됩니다. 이를 다시 추가하는 것은 이러한 점을 인지한 상태에서 수행하는 배포별 재정의입니다. 지원 세션 중에는 기본 테이블 허용 목록에 실행 중인 쿼리 텍스트를 표시하는 `system.processes`가 포함됩니다. 이를 트리밍하는 방법은 [지원 세션](/docs/ko/products/bring-your-own-cloud/connector/support-sessions)을 참조하십시오.
* **자격 증명.** 설정 파일에는 자격 증명이 포함되지 않으며, ClickHouse는 커넥터 사용자의 비밀번호에 대한 bcrypt 해시만 저장합니다. 시크릿은 Kubernetes 시크릿 또는 호스트에서 root만 읽을 수 있는 파일에 유지됩니다. 스크레이프나 동기화 경로를 통해 전송되는 자격 증명은 없습니다.
* **마스킹되지 않은 문제 해결 도구 출력.** 문제 해결 도구가 반환하는 모든 항목은 외부로 나가기 전에 내장 패턴과 자체 패턴을 포함한 마스킹 패턴을 거칩니다. [지원 세션](/docs/ko/products/bring-your-own-cloud/connector/support-sessions)을 참조하십시오.
## 신뢰 경계
* **환경이 경계입니다.** ClickHouse Cloud는 스크레이퍼가 전송하는 정보와 활성 지원 세션이 반환하는 정보만 수신합니다. 내부로 연결을 시작하지 않습니다.
* **세션 게이트웨이는 사용자 환경에 있습니다.** 인그레스(Ingress)를 통해 노출하도록 선택하지 않는 한, Kubernetes에서는 `kubectl port-forward`를 통해, VM에서는 로컬에서만 환경 내부에서 접근할 수 있습니다. ClickHouse의 컨트롤 플레인은 여기에 연결하지 않습니다.
* **ClickHouse 접근은 읽기 전용입니다.** `pcm_scraper` 및 `pcm_troubleshooter` 사용자는 테이블별 `SELECT` 권한과 로그 테이블을 디스크로 플러시하는 스크레이퍼 전용 시스템 권한 1개만 보유합니다. `INSERT`, DDL 또는 사용자 관리 권한은 없습니다. 정확한 목록은 [권한 모델](/docs/ko/products/bring-your-own-cloud/connector/reference/privilege-model)에서 확인할 수 있습니다.
* **Kubernetes 접근은 네임스페이스 범위로 제한됩니다.** 모든 RBAC는 커넥터 및 인스턴스 네임스페이스의 역할을 통해 부여되며, 워크로드 리소스에는 읽기 전용 동사만 허용되고 커넥터 자체 시크릿에는 정확한 이름으로만 접근할 수 있습니다. `exec`, `delete`, `patch` 권한은 없습니다.
* **네트워크 정책.** Kubernetes에서 차트는 지정한 CIDR을 제외한 모든 커넥터 이그레스를 차단하는 NetworkPolicy를 렌더링할 수 있습니다. 정책 적용 여부는 클러스터에서 이를 강제하는 CNI를 실행하는지에 따라 달라지며, 그렇지 않으면 정책은 적용되지 않습니다. [구성](/docs/ko/products/bring-your-own-cloud/connector/configuration)을 참조하십시오.
* **VM의 호스트 강화.** 유닛은 로그인할 수 없는 시스템 사용자로 실행되며, `ProtectSystem=strict`, `NoNewPrivileges`, 읽기 전용 구성 경로 및 활성화된 FIPS 모드를 사용합니다.
커넥터의 정확한 권한 및 RBAC 규칙은 [권한 모델](/docs/ko/products/bring-your-own-cloud/connector/reference/privilege-model) 참고 문서를 참조하십시오. 대신 ClickHouse가 클러스터를 운영하는 경우에는 신뢰 모델이 다릅니다. [BYOC 아키텍처](/docs/ko/products/bring-your-own-cloud/overview/architecture) 및 [BYOC 권한](/docs/ko/products/bring-your-own-cloud/reference/privilege) 페이지를 참조하십시오.