사전 요구 사항
- 커넥터 엔드포인트 및 등록 토큰: 온보딩 과정에서 ClickHouse가 제공합니다(1단계 참조).
- 설치 시
https://<subdomain>.<connector-domain>및https://<subdomain>.enroll.<connector-domain>,releases.clicklink.clickhouse.com, Amazon ECR Public에 대한 포트 443 아웃바운드 연결. 이들 중 하나라도 연결할 수 없으면 에어갭 및 미러 설치를 참조하십시오. - 커넥터가 실행되는 위치에서 연결 가능한 ClickHouse 네이티브 리스너: 보안 포트(9440) 또는 plaintext 포트(9000)를 사용하며, Kubernetes에서는 자동으로 감지됩니다.
- 프로비저닝을 위한 ClickHouse 관리자 액세스: 비밀번호 없는
default사용자, 비밀번호(프롬프트에서 입력하거나--ch-admin-password-stdin으로 제공), 또는 연산자가 관리하는 인스턴스가 필요합니다. 연산자 관리 인스턴스에서는 프로비저닝이 CR injection으로 전환되므로 비밀번호가 필요하지 않습니다. - 릴리스 아티팩트를 다운로드하는 모든 환경의 cosign. 설치 관리자는 항상 SHA-256 checksum을 검증하고, cosign이 설치된 경우 cosign 서명 검증도 수행합니다.
CLICKLINK_REQUIRE_COSIGN=1을 설정하면 cosign 없이는 진행하지 않습니다.
- 규격을 준수하는 Kubernetes 클러스터.
- 커넥터 네임스페이스를 생성하고 읽으며, 시크릿을 적용하고, ClickHouse 파드 내에서 exec를 실행하고(프로비저닝은 파드 내에서
clickhouse-client를 실행합니다), ServiceAccount, Role, RoleBinding을 생성하고, 차트를 설치할 수 있는 kubeconfig. - 기본 StorageClass 또는
--storage-class로 전달할 클래스. troubleshooter는 PersistentVolumeClaim에 상태를 유지합니다. - 이미지 pull 액세스: 클러스터 노드는 공개 ECR 이미지 또는 호스팅 중인 미러에서 이미지를 pull할 수 있어야 합니다.
- amd64 또는 arm64의 systemd Linux 호스트. Linux 빌드는 FIPS 모드에서 실행됩니다.
- 설치 관리자 및
init를 위한 root 액세스. - 사용 가능한 포트 8080, 8082, 8084(상태 확인), 9090, 9092, 9094(메트릭) 및 지원 세션 gateway를 활성화한 경우 8443.
- 프로비저닝을 위한 Kubernetes API server 관리자 액세스. 호스트의 kubeconfig,
--server및--ca-data, 또는 프롬프트를 통해 제공합니다. 액세스 bundle은 두 대상 모두에서 Kubernetes ServiceAccount에 연결됩니다.
--skip-provision은 Kubernetes 요구 사항을 우회하는 유일한 방법이며, 준비 단계에서만 사용할 수 있습니다. ClickHouse 사용자 프로비저닝을 건너뛰고 VM에서는 unit 활성화 및 검증도 건너뛰므로, 이것만으로는 실행 중인 커넥터가 생성되지 않습니다.설치 및 등록
1
커넥터 endpoint 및 등록 토큰 가져오기
ClickHouse는 온보딩 과정에서 connector endpoint와 일회용 등록 token을 제공합니다. endpoint 형식은 다음과 같습니다.토큰은 일회용이며 빠르게 만료되므로, 받은 직후 등록을 실행할 수 있도록 준비하십시오. 토큰은 시크릿으로 취급해야 합니다. CLI는 명령줄 인수, 디스크 또는 로그가 아닌 숨겨진 프롬프트(또는 stdin의 첫 번째 줄)에서 토큰을 읽습니다. 사용하기 전에 토큰이 만료되면 ClickHouse 계정 팀에 문의하여 새 토큰을 받으십시오.
2
CLI 설치 및 확인
하나의 명령으로 검증된 VM에 설치하는 경우 호스트에서 두 방식 모두
clicklink 바이너리를 설치할 수 있습니다. 플랫폼과 아키텍처(macOS 또는 Linux, amd64 또는 arm64)를 감지하고, 최신 릴리스를 다운로드한 후 SHA-256 체크섬 및 cosign이 설치된 경우 릴리스 서명을 검증하여 바이너리를 PATH에 설치합니다. Kubernetes에 설치하려면 클러스터에 kubeconfig를 통해 접근할 수 있는 워크스테이션에서 실행하십시오:--host 옵션과 함께 동일한 스크립트를 실행하십시오. 다운로드가 검증되면 clicklink 시스템 사용자, /etc/clicklink, /var/lib/clicklink, /var/log/clicklink 디렉터리 및 systemd 유닛도 생성하고, 기본 /etc/clicklink/redaction-patterns.yaml 파일을 생성합니다(기존 파일이 있으면 유지됨). 따라서 다음 단계는 바로 등록부터 시작합니다:--version vX.Y.Z를 사용해 특정 릴리스로 고정할 수 있으며, 어느 쪽을 다시 실행해도 안전합니다. 호스트 설치 방식은 기존 바이너리를 백업하고 현재 구성을 유지합니다. 실행 전에 스크립트를 검토하거나 릴리스 tarball을 직접 다운로드하여 검증하려면 수동 다운로드 및 검증을 참조하십시오.3
커넥터 등록 및 설치
등록은 단일 명령으로 완료됩니다. 이 명령은 토큰을 교환하고, ClickHouse 액세스를 프로비저닝하며, 서명된 클라이언트 인증서를 발급받고, 커넥터를 설치한 뒤 처음부터 끝까지 검증합니다.
- Kubernetes
- Linux VM
워크스테이션에서 다음 명령을 실행하십시오.표시되지 않는 프롬프트에 등록 토큰을 붙여 넣으십시오. 그러면 CLI에서 다음 정보를 입력하라는 메시지가 표시됩니다.ClickHouse 인스턴스마다
- 커넥터 네임스페이스(기본값:
clicklink) - ClickHouse 인스턴스가 실행 중인 네임스페이스
- 감지된 ClickHouse 서비스에서 채워진 인스턴스 연결 정보
- 클러스터에 기본 StorageClass가 없는 경우에만 StorageClass
- 지원 세션 구성 및 활성화한 경우 운영자 이메일 허용 목록
- SQL 프로비저닝에 필요한 경우에만 ClickHouse 관리자 비밀번호
handoff.yaml로 저장하고, Helm values 오버레이 clicklink-values.yaml을 준비하며, 네임스페이스를 생성하고, clicklink-hmac 및 clicklink-mtls Secret을 적용합니다. 또한 각 인스턴스에 읽기 전용 ClickHouse 사용자를 프로비저닝하며(Operator가 관리하는 인스턴스에서는 SQL 권한 부여 또는 CR 주입을 자동으로 선택), 개인 키와 CSR을 생성한 후 ClickHouse에서 클라이언트 인증서에 서명하도록 합니다. 이어서 내장 Helm 클라이언트로 clicklink-connector Helm 릴리스를 설치하고(helm 바이너리는 필요하지 않음), 상태를 검증합니다.무인 실행에서는 프롬프트에 응답하는 대신 플래그를 사용하십시오. 비터미널 실행에서 --enroll은 stdin의 첫 번째 줄에서 등록 토큰을 읽으므로 리디렉션된 비밀번호를 소비할 수 있습니다. 따라서 저장된 번들을 진입점으로 사용하십시오.--instance를 반복 지정하십시오. 지원 세션을 비활성화하려면 --operators 대신 --no-gateway를 전달하십시오. 두 플래그는 함께 사용할 수 없습니다.4
성공 확인
init는 성공을 보고하기 전에 설치를 검증합니다. Kubernetes에서는 활성화된 각 구성 요소의 /livez 엔드포인트를 최대 5분 동안 폴링하고, support-session gateway가 활성화된 경우에는 gateway가 인증되지 않은 프로브에 401로 응답해야 합니다. VM에서는 각 데몬의 /livez가 응답할 때까지 기다린 후 구성, 파일, 포트 충돌, 네트워크 연결성, ClickHouse 연결, systemd 유닛 상태, 구성 요소별 액세스, 디스크 및 redaction 패턴을 포함한 전체 Preflight 검사 모음을 실행합니다.Kubernetes에서 수동으로 확인하려면:Running 상태이고 준비 완료 상태여야 합니다.VM에서 직접 확인하려면 다음을 수행하십시오.0으로 종료하며, 하나라도 실패하면 실패한 검사를 출력하고 2로 종료합니다.5
정리
등록 번들 실행 중인 connector는 자격 증명의 자체 사본을 보유하므로 운영 작업은 파일에 전혀 의존하지 않습니다. 업그레이드나 구성 변경 시에도 파일이 필요하지 않으며, 나중에 다시
handoff.yaml(작업 디렉터리에 권한 모드 0600으로 저장됨)을 사용하면 설치 중 재실행하거나 복구할 때 두 번째 토큰이 필요하지 않습니다. 이 파일에는 커넥터의 API 시크릿이 평문으로 포함되어 있으므로 설치가 확인되면 삭제하십시오:init이 필요하면 ClickHouse 계정 팀에 새 등록 토큰을 요청한 후 init --enroll --force를 실행하십시오.에어갭 및 미러 설치
--enroll 대신 clicklink clctl init --handoff <bundle-file>를 실행하십시오. --handoff는 토큰 교환만 대체합니다. 인증서 서명은 여전히 등록 엔드포인트를 통해 수행되므로, init를 실행하는 위치에서 해당 엔드포인트에 연결할 수 있을 때만 이 옵션을 사용하십시오.
대역 외 인증서 서명. init를 실행하는 위치에서 등록 엔드포인트에 연결할 수 없으면 --no-auto-sign을 추가하십시오. init는 모든 항목을 준비하고 clicklink.csr을 작성합니다. 계정 팀을 통해 CSR을 ClickHouse에 전송한 후, 반환된 인증서와 체인을 사용해 설치를 완료하십시오. VM에서는 sudo clicklink clctl init --signed-cert client.crt --chain ca-chain.crt를 실행하고, Kubernetes에서는 준비 단계에서 출력되는 전체 완료 명령( --target helm 포함)을 사용하십시오. 전송되는 것은 CSR뿐이며 private key는 환경 외부로 절대 유출되지 않습니다.
Kubernetes에서 --chart는 --chart-repo로 해석되는 차트 이름, oci:// 참조, 직접 URL, 로컬 아카이브 또는 디렉터리를 허용합니다. --chart-version은 기본적으로 CLI 자체 버전을 사용하므로 바이너리와 차트가 함께 배포됩니다. 자체 registry에서 이미지를 제공하려면 container image를 미러링하고 values 오버레이에서 image.repository를 설정하십시오. egress 경로가 커넥터에 사설 CA를 제시하면 --api-private-ca를 전달하여 system trust store 대신 등록 번들에 포함된 CA 체인으로 API 엔드포인트를 검증하십시오.
설치 프로그램은 미러에서도 작동합니다. 자체 미러에서 릴리스 아티팩트와 install.sh를 호스팅하고 CLICKLINK_MIRROR_URL로 지정하십시오.
수동 다운로드 및 검증
sudo ./install.sh를 실행하십시오. 이 스크립트는 릴리스 아티팩트 옆에 설치되며, --host와 동일하게 호스트에 설치합니다.
문제가 발생한 경우
init는 멱등성을 보장하므로 다시 실행해도 동일한 상태에 도달하며, 기존 구성과 스테이징된 파일은 유지되고 완료된 작업은 건너뜁니다. 단계 진행 중 실패하면 CLI가 상황에 맞는 정확한 복구 명령어를 출력하며, 출력된 명령어는 안전하게 반복 실행할 수 있습니다.
등록이 거부되면 토큰이 이미 사용되었거나(최종 정리 단계 전까지 존재하는 handoff.yaml을 지정해 --handoff handoff.yaml과 함께 다시 실행하십시오), 유효하지 않거나 만료된 것입니다(새 토큰은 ClickHouse 계정 팀에 문의하십시오). 전송 오류로 등록에 실패한 경우 토큰은 사용되지 않았으므로 동일한 명령어를 다시 실행하십시오.
--force는 일반적인 재시도가 아닌 명시적 재설정입니다. 유지된 구성 또는 values 오버레이를 덮어쓰고, 클라이언트 키를 다시 생성하며, 만료되지 않은 클라이언트 인증서를 대체합니다(서명 엔드포인트에서 409가 반환되면 이미 인증서가 존재한다는 의미입니다). 커넥터의 cluster UUID는 --force를 사용해도 유지되므로, 다시 초기화된 커넥터도 아이덴티티를 유지합니다. 자격 증명을 교체하거나 인증서를 대체해야 할 때 사용하십시오. 전체 재실행 및 복구 모델은 운영을 참조하십시오.