운영 - ClickHouse Documentation

이 페이지에서는 두 설치 대상에서 ClickHouse Connector를 배포한 후 수행하는 운영 작업을 다룹니다. 설치 및 등록은 온보딩을 참조하십시오.

업그레이드

Kubernetes

Day-2 Kubernetes 작업에는 워크스테이션의 helm CLI를 사용합니다. 내장 Helm 클라이언트는 init에만 포함되어 있으므로 첫 업그레이드 전에 helm을 설치하십시오.

init에서 준비한 values 오버레이를 재사용하여 공개 차트 리포지토리의 릴리스를 업그레이드합니다:

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
helm upgrade --install clicklink-connector clicklink-connector \
  --repo https://releases.clicklink.clickhouse.com/charts \
  --version <version> \
  -n "${CONNECTOR_NAMESPACE}" \
  -f clicklink-values.yaml

차트 버전은 앞의 v를 제외한 릴리스 태그입니다(차트 0.9.0은 태그 v0.9.0에 해당합니다). 게시된 차트는 이미 공개 컨테이너 이미지를 가리키므로 일반 설치 및 업그레이드에는 이미지 values를 지정할 필요가 없습니다. 차트 기본값을 확인하려면 helm show values clicklink-connector --repo https://releases.clicklink.clickhouse.com/charts를 실행하십시오. 직접 차트 참조(oci://, URL 또는 로컬 아카이브나 디렉터리)로 설치한 경우에는 확인할 리포지토리가 없습니다. 대신 새 버전에서 helm upgrade clicklink-connector <same-chart-reference>를 다시 실행하십시오. 최신 CLI로 init를 다시 실행해도 원하는 상태로 수렴하지만, init에는 항상 진입점 중 하나가 필요합니다. 번들을 보관한 경우에는 --handoff를 사용하고, 문서화된 정리 후에는 --force와 함께 새 등록 토큰을 사용하십시오. 위의 helm upgrade가 일반적인 방법입니다(재실행 및 복구 참조).

Linux VM

호스트에서 설치 관리자를 다시 실행하십시오. 온보딩 시와 동일한 방식으로 최신 릴리스를 다운로드하고 검증하며, 기존 바이너리를 백업하고, 현재 사용 중인 민감 정보 마스킹 패턴과 환경 파일을 유지합니다. 그런 다음 데몬을 다시 시작하십시오:

curl -fsSL https://releases.clicklink.clickhouse.com/install.sh | sudo bash -s -- --host
sudo systemctl restart clicklink-scraper clicklink-troubleshooter

최신 버전 대신 특정 릴리스로 업그레이드하려면 설치 명령에 --version vX.Y.Z를 추가하십시오.

상태

각 데몬은 상태 확인 포트에서 /livez 엔드포인트를 제공합니다. 응답 본문의 JSON status 필드는 HTTP 상태 코드가 아닌 상태 신호이므로, 200에 의존하지 말고 본문을 확인하십시오. Prometheus 메트릭은 각 구성 요소의 메트릭 포트에서 제공됩니다. 두 대상의 기본 포트는 다음과 같습니다.

구성 요소	상태 확인 포트	메트릭 포트
전역 기본값	8080	9090
Scraper	8082	9092
Troubleshooter	8084	9094

지원 세션이 활성화되면 gateway는 추가로 포트 8443에서 수신 대기합니다. VM에서는 자체 서명 TLS를 사용하며, Kubernetes에서는 kubectl port-forward를 통한 파드 로컬 HTTP 또는 TLS 종료 인그레스를 사용합니다. VM에서는 언제든지 전체 검사 모음을 실행할 수 있습니다.

sudo clicklink clctl preflight

구성, 파일, 포트 충돌, 네트워크 연결 가능 여부(API 엔드포인트 및 각 ClickHouse 인스턴스), ClickHouse 연결, systemd 유닛 상태, 구성 요소별 액세스, 디스크 및 민감 정보 마스킹 패턴을 확인하며, 하나라도 확인에 실패하면 2로 종료합니다.

인증서

connector는 자체 클라이언트 인증서를 갱신합니다. 각 데몬은 12시간마다 리프를 확인하며, 만료까지 10일이 남으면 기존 mTLS 및 HMAC 인증 채널을 통해 30일 유효한 리프를 받아 갱신합니다. 연산자가 별도로 수행할 작업은 없습니다. Kubernetes에서는 갱신된 리프가 clicklink-mtls 시크릿에 다시 기록되고, VM에서는 /etc/clicklink/tls/ 아래에 기록됩니다. 현재 만료일을 확인하려면:

# Linux VM
sudo openssl x509 -in /etc/clicklink/tls/client.crt -noout -enddate

# Kubernetes
CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl get secret clicklink-mtls -n "${CONNECTOR_NAMESPACE}" -o jsonpath='{.data.tls\.crt}' \
  | base64 -d | openssl x509 -noout -enddate

자격 증명 교체

API (HMAC) 자격 증명

ClickHouse 계정 팀에 새 등록 토큰을 요청한 후, --enroll 및 --force를 지정하여 기존 init 명령을 다시 실행하십시오. --force는 기존 구성을 다시 준비하므로, 최초 설치 시 사용한 모든 대상별 플래그(--target-namespace, --values 및 모든 --chart, --chart-repo, --chart-version 미러 플래그)를 그대로 유지하십시오. 기본 설치에서는 다음과 같습니다:

# Kubernetes, from your workstation
clicklink clctl init --enroll https://<subdomain>.<connector-domain> --target helm --force

# Linux VM, on the host
sudo clicklink clctl init --enroll https://<subdomain>.<connector-domain> --force

SQL 프로비저닝에 password가 필요한 무인 교체 시 stdin을 통해 두 시크릿이 순서대로 전달됩니다. 첫 번째 줄에는 token, 두 번째 줄에는 password를 입력합니다. token을 읽으면 정확히 한 줄이 소비됩니다.

printf '%s\n' "$ENROLLMENT_TOKEN" "$CH_ADMIN_PASSWORD" | \
  clicklink clctl init --enroll https://<subdomain>.<connector-domain> --force --ch-admin-password-stdin

ClickHouse 사용자

인스턴스별로 connector의 읽기 전용 사용자를 다시 프로비저닝합니다. Kubernetes에서는 워크스테이션에서 다음을 실행하십시오. --apply-ch-grants는 재생성된 권한을 파드 내에서 다시 적용하여 새 자격 증명이 ClickHouse에 반영되도록 합니다(admin user에 password가 설정되어 있으면 --ch-admin-password-stdin을 추가하고 파이프로 전달하십시오):

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
clicklink clctl scraper access provision --target helm \
  --target-namespace "${CONNECTOR_NAMESPACE}" \
  --instance <instance-name> --instance-namespace <clickhouse-namespace> \
  --server <kubernetes-api-server-url> \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace <clickhouse-namespace> \
  --force
clicklink clctl troubleshoot access provision --target helm \
  --target-namespace "${CONNECTOR_NAMESPACE}" \
  --instance <instance-name> --instance-namespace <clickhouse-namespace> \
  --server <kubernetes-api-server-url> \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace <clickhouse-namespace> \
  --force

VM의 호스트에서:

sudo clicklink clctl scraper access provision --provider local \
  --instance <instance-name> --server <kubernetes-api-server-url> --force
sudo clicklink clctl troubleshoot access provision --provider local \
  --instance <instance-name> --server <kubernetes-api-server-url> --force

연산자가 관리하는 인스턴스에서는 두 형식 중 어느 쪽이든 --ch-user-via cr 및 파드 선택 플래그를 추가하십시오. 자세한 내용은 CLI 참고를 참조하십시오.

클라이언트 인증서

인증서는 자동으로 갱신됩니다(인증서 참조). 아직 만료되지 않은 인증서를 즉시 교체하려면 --force 옵션과 함께 init을 다시 실행하십시오.

재실행 및 복구

init은 재실행해도 동일한 상태로 수렴하므로, 먼저 같은 명령어를 다시 실행해 보십시오. --force 없이 실행하면 기존 /etc/clicklink/config.yaml(VM) 또는 clicklink-values.yaml 오버레이(Kubernetes)는 유지되고, 기존 클라이언트 키는 재사용됩니다. 자격 증명과 CA 체인은 원자적으로 덮어씌워집니다. 부분 실패 후 CLI가 출력하는 복구 명령어는 반복 실행해도 안전합니다. --force는 유지된 구성 또는 오버레이를 덮어쓰고, 클라이언트 키를 다시 생성하며, 아직 만료되지 않은 클라이언트 인증서를 대체합니다. 새 클러스터 UUID를 발급하지는 않습니다. --force를 사용하더라도 connector의 아이덴티티는 유지됩니다. 스테이징 후 인증서 서명에 실패했거나, 아직 만료되지 않은 인증서가 이미 존재해 서명 엔드포인트가 409를 반환한 경우 새 token이나 두 번째 발급은 필요하지 않습니다. 디스크에 이미 있는 서명된 자료로 설치를 완료하십시오:

sudo clicklink clctl init --signed-cert client.crt --chain ca-chain.crt

이는 VM용 형식입니다(root가 /etc/clicklink를 재작성하고 서비스를 관리합니다). Kubernetes에서는 CLI가 --target helm, --target-namespace, --values를 포함한 전체 형식을 출력하므로, 출력된 명령을 그대로 사용하세요.

제거

Linux VM

uninstall.sh는 릴리스 tarball에 포함되어 있습니다. 호스트에 추출된 tarball이 남아 있지 않으면 수동 다운로드 및 검증에 설명된 대로 tarball을 가져와 추출한 다음, 추출된 디렉터리에서 실행하십시오:

sudo ./uninstall.sh

이 명령은 서비스를 중지하고 비활성화하며 systemd 유닛과 바이너리를 제거합니다. 하지만 /etc/clicklink, /var/lib/clicklink, /var/log/clicklink 및 clicklink 사용자는 유지되므로, 나중에 다시 설치하면 기존 구성이 적용됩니다. 이 항목들까지 제거하려면:

sudo ./uninstall.sh --purge

Kubernetes

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
helm uninstall clicklink-connector -n "${CONNECTOR_NAMESPACE}"

init가 생성한 시크릿은 차트에서 관리하지 않으므로 제거해도 남아 있습니다. 구성한 모든 인스턴스의 인스턴스별 액세스 시크릿을 포함해 명시적으로 삭제하십시오:

kubectl delete secret clicklink-hmac clicklink-mtls -n "${CONNECTOR_NAMESPACE}"
kubectl delete secret -n "${CONNECTOR_NAMESPACE}" \
  clicklink-connector-scraper-access-<instance> \
  clicklink-connector-troubleshooter-access-<instance>
kubectl delete serviceaccount -n "${CONNECTOR_NAMESPACE}" \
  pcm-scraper-<instance> pcm-troubleshooter-<instance>
# Repeat for every ClickHouse namespace that holds a provisioned instance.
for ns in <clickhouse-namespace-1> <clickhouse-namespace-2>; do
  kubectl delete serviceaccount,role,rolebinding -n "${ns}" \
    pcm-scraper pcm-troubleshooter
done

ClickHouse 사용자

어느 대상에서 제거하더라도 프로비저닝된 읽기 전용 사용자는 그대로 남습니다. 각 인스턴스에서 관리자로 해당 사용자를 삭제하십시오(설정한 경우 이름에 --ch-user-suffix를 추가하십시오):

DROP USER IF EXISTS pcm_scraper, pcm_troubleshooter;

Get started

Services and infrastructure

Bring Your Own Cloud

Data and integrations

Connect and query

Access management

Security and compliance

Monitoring and backups

AI tools and agents

Cloud API

Billing

Support

ClickHouse Private

운영

업그레이드

Kubernetes

Linux VM

상태

인증서

자격 증명 교체

API (HMAC) 자격 증명

ClickHouse 사용자

클라이언트 인증서

재실행 및 복구

제거

Linux VM

Kubernetes

ClickHouse 사용자

​업그레이드

​Kubernetes

​Linux VM

​상태

​인증서

​자격 증명 교체

​API (HMAC) 자격 증명

​ClickHouse 사용자

​클라이언트 인증서

​재실행 및 복구

​제거

​Linux VM

​Kubernetes

​ClickHouse 사용자

업그레이드

Kubernetes

Linux VM

상태

인증서

자격 증명 교체

API (HMAC) 자격 증명

ClickHouse 사용자

클라이언트 인증서

재실행 및 복구

제거

Linux VM

Kubernetes

ClickHouse 사용자