운영 - ClickHouse Documentation

이 페이지에서는 두 설치 대상에서 커넥터를 배포한 후 수행하는 운영 작업을 다룹니다. 설치 및 등록은 온보딩을 참조하십시오. 서비스 자체의 운영(생성, 스케일링, 삭제 및 플랫폼 업데이트)은 관리형 서비스 및 플랫폼 업데이트에서 다룹니다.

업그레이드

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를 제외한 릴리스 태그입니다(차트 X.Y.Z는 태그 vX.Y.Z에 해당합니다). 게시된 차트는 이미 공개 컨테이너 이미지를 가리키므로 일반 설치 및 업그레이드에는 이미지 values를 지정할 필요가 없습니다. 차트 기본값을 확인하려면 helm show values clicklink-connector --repo https://releases.clicklink.clickhouse.com/charts를 실행하십시오. 실행기는 Recreate strategy를 사용하는 단일 레플리카로 동작하므로 업그레이드 시 잠시 연결이 끊어집니다. 해당 구간 동안 명령어가 어떻게 처리되는지는 커넥터가 오프라인일 때를 참조하십시오. 직접 차트 참조(oci://, URL 또는 로컬 아카이브나 디렉터리)로 설치한 경우에는 확인할 리포지토리가 없습니다. 대신 새 버전에서 helm upgrade clicklink-connector <same-chart-reference>를 다시 실행하십시오. 최신 CLI로 init를 다시 실행해도 원하는 상태로 수렴하지만, 진입점이 필요합니다. 번들을 보관한 경우에는 --handoff를 사용하고, 문서화된 정리 후에는 --force와 함께 새 등록 토큰을 사용하십시오. 위의 helm upgrade가 일반적인 방법입니다(재실행 및 복구 참조).

Linux VM

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

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

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

상태

각 데몬은 상태 확인 포트에서 /livez 엔드포인트를 제공합니다. 상태 신호는 HTTP 상태 코드가 아닌 응답 본문의 JSON status 필드입니다. Prometheus 메트릭은 동일한 포트의 /metrics에서 제공되며, 별도의 메트릭 포트는 없습니다. 두 대상의 기본 포트는 다음과 같습니다.

구성 요소	상태 확인 포트
스크레이퍼	8082
Troubleshooter	8084
실행기	8086

실행기는 또한 127.0.0.1:9999에서 로컬 명령 API를 제공합니다. 자체 인증은 없으며 호스트나 파드 외부로 노출되지 않습니다. clicklink clctl 서비스 명령어가 로컬에서 이 API에 접근합니다. 지원 세션이 활성화되면 gateway는 추가로 포트 8443에서 수신 대기합니다. VM에서는 자체 서명 TLS를 사용하며, Kubernetes에서는 kubectl port-forward를 통한 파드 로컬 HTTP 또는 TLS 종료 인그레스를 사용합니다. VM에서는 언제든지 전체 검사 모음을 실행하십시오.

sudo clicklink clctl preflight

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

인증서

커넥터는 자체 클라이언트 인증서를 갱신합니다. 스크레이퍼, troubleshooter, 실행기는 각각 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) 자격 증명

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

# 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

VM에서 init은 아직 실행되고 있지 않은 유닛만 활성화하고 시작하므로, 교체 후에는 데몬을 다시 시작하십시오:

sudo systemctl restart clicklink-scraper clicklink-troubleshooter clicklink-executor

Kubernetes에서는 init이 교체된 clicklink-hmac 및 clicklink-mtls 시크릿을 미리 생성하며, 차트는 이를 렌더링하지 않습니다. 차트의 체크섬 annotation에도 이들 시크릿이 포함되지 않으므로, 실행 중인 파드는 시작 시점의 자격 증명을 계속 사용합니다. 교체 후에는 모든 구성 요소를 다시 시작하십시오:

kubectl rollout restart deployment,statefulset -n "${CONNECTOR_NAMESPACE}" \
  -l app.kubernetes.io/part-of=clicklink-connector

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

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에 반영되도록 합니다. 관리자 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에서는 관리자 password를 파이프로 전달하여 호스트에서 실행하십시오. 이 경우 --ch-user-via cr을 전달하지 않는 한 password가 필수입니다:

printf '%s\n' "$CH_ADMIN_PASSWORD" | sudo clicklink clctl scraper access provision --provider local \
  --instance <instance-name> --server <kubernetes-api-server-url> --ch-admin-password-stdin --force
printf '%s\n' "$CH_ADMIN_PASSWORD" | sudo clicklink clctl troubleshoot access provision --provider local \
  --instance <instance-name> --server <kubernetes-api-server-url> --ch-admin-password-stdin --force

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

클라이언트 인증서

인증서는 자동으로 갱신됩니다(인증서 참조). 아직 만료되지 않은 인증서를 즉시 교체하려면 --force 옵션과 함께 init을 다시 실행하십시오. 그런 다음 데몬이 새 리프 인증서를 제시하도록 모든 구성 요소를 재시작하십시오. Kubernetes에서는 API 자격 증명에 설명된 방식으로, VM에서는 세 개의 유닛을 재시작합니다.

재실행 및 복구

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

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

이는 VM용 형식입니다(root가 /etc/clicklink를 재작성하고 서비스를 관리합니다). Kubernetes에서는 CLI가 --target helm, --target-namespace, --values를 포함한 전체 형식을 출력하므로, 출력된 명령을 그대로 사용하세요. 커넥터 오프라인. 커넥터가 중단되었거나 연결할 수 없는 동안에도 커넥터가 관리하는 서비스는 계속 실행됩니다. 클러스터의 ClickHouse Operator가 서비스를 유지하며, 실행기는 데이터 경로에 포함되지 않습니다. 수명 주기 변경에는 실행기 연결이 필요하므로, 다시 연결될 때까지는 어떤 변경도 적용되지 않습니다. 재시작 시 실행기는 진행 중이던 명령어를 자체 명령 데이터베이스에서 복구합니다. ClickHouse Cloud가 다시 전달하는 명령어는 기록된 결과로 응답합니다. 실패한 명령어만 다시 실행됩니다. 연결된 실행기가 없는 동안의 수명 주기 명령어에 대해서는 커넥터가 오프라인일 때를 참조하십시오.

제거

제거하기 전에 서비스 삭제 절차에 따라 모든 관리형 서비스를 삭제하고, 각 서비스의 제거 작업이 완료될 때까지 기다리십시오. 커넥터를 먼저 제거하면 서비스의 수명 주기를 관리할 구성 요소가 없는 상태로 남게 됩니다.

Linux VM

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

sudo ./uninstall.sh

이 명령은 clicklink-scraper, clicklink-troubleshooter, clicklink-executor 유닛을 중지하고 비활성화하며 systemd 유닛과 바이너리를 제거합니다. 다음 항목은 유지되므로, 나중에 다시 설치하면 기존 구성이 적용됩니다:

/etc/clicklink (/etc/clicklink/access/executor 아래의 실행기 access bundles 포함)
/var/lib/clicklink (실행기의 명령 데이터베이스 executor.db 및 서비스 레지스트리 포함)
/var/log/clicklink
clicklink 사용자

이 항목들까지 제거하려면:

sudo ./uninstall.sh --purge

실행기의 클러스터 전체 권한 부여는 호스트가 아니라 클러스터에 존재합니다. 관리형 서비스가 더 이상 남아 있지 않으면 클러스터 관리자 권한으로 이를 제거하십시오:

kubectl delete validatingadmissionpolicybinding pcm-executor-prefix-guard
kubectl delete validatingadmissionpolicy pcm-executor-prefix-guard
kubectl delete clusterrolebinding pcm-executor-cluster
kubectl delete clusterrole pcm-executor-cluster
kubectl delete serviceaccount pcm-executor -n clicklink-system

이 권한 부여는 clicklink-system 네임스페이스도 생성했으므로, 다른 곳에서 사용하지 않는다면 삭제하십시오.

Kubernetes

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

실행기의 PersistentVolumeClaim에는 helm.sh/resource-policy: keep 어노테이션이 지정되어 있으므로, 제거(uninstall) 후에도 명령 데이터베이스와 서비스 레지스트리를 담은 채로 남아 있습니다. init이 생성한 시크릿, platform approve가 기록한 플랫폼 번들 시크릿, 실행기가 유지 관리하는 서비스 레지스트리 ConfigMap도 차트 소유 리소스가 아니므로 제거 후에도 그대로 남습니다. 이러한 리소스는 명시적으로 삭제하십시오. 직접 등록한 모든 인스턴스와 Troubleshooter를 프로비저닝한 모든 관리형 서비스의 액세스 시크릿 및 ServiceAccount 쌍(서비스 이름을 따서 명명됨)도 포함하십시오. --ignore-not-found를 사용하면 최초 승인 이전의 플랫폼 번들 시크릿처럼 생성된 적이 없는 객체도 문제없이 처리됩니다:

kubectl delete pvc -n "${CONNECTOR_NAMESPACE}" -l app.kubernetes.io/instance=clicklink-connector --ignore-not-found
kubectl delete secret clicklink-hmac clicklink-mtls clicklink-platform-bundle -n "${CONNECTOR_NAMESPACE}" --ignore-not-found
kubectl delete configmap clicklink-instance-registry -n "${CONNECTOR_NAMESPACE}" --ignore-not-found
kubectl delete secret -n "${CONNECTOR_NAMESPACE}" --ignore-not-found \
  clicklink-connector-scraper-access-<instance> \
  clicklink-connector-troubleshooter-access-<instance>
kubectl delete serviceaccount -n "${CONNECTOR_NAMESPACE}" --ignore-not-found \
  pcm-scraper-<instance> pcm-troubleshooter-<instance>
# Repeat for every ClickHouse namespace that holds an instance you registered yourself;
# a managed service's namespace went away with the service.
for ns in <clickhouse-namespace-1> <clickhouse-namespace-2>; do
  kubectl delete serviceaccount,role,rolebinding -n "${ns}" --ignore-not-found \
    pcm-scraper pcm-troubleshooter
done

init은 차트가 아니라 실행기의 클러스터 전체 권한 부여를 적용했습니다. 남아 있는 관리형 서비스가 없으면 클러스터 관리자 권한으로 해당 권한 부여를 제거하십시오:

kubectl delete validatingadmissionpolicybinding pcm-executor-prefix-guard
kubectl delete validatingadmissionpolicy pcm-executor-prefix-guard
kubectl delete clusterrolebinding pcm-executor-cluster
kubectl delete clusterrole pcm-executor-cluster
kubectl delete serviceaccount pcm-executor -n "${CONNECTOR_NAMESPACE}"

플랫폼 레이어

커넥터를 제거해도 플랫폼 레이어는 삭제되지 않습니다. 플랫폼 네임스페이스와 워크로드, pcm-platform RBAC, 승인을 통해 설치된 admission 객체는 클러스터에 그대로 남으며, 모든 관리형 서비스도 마찬가지입니다. 먼저 서비스를 삭제하십시오. 서비스 삭제를 참조하십시오. 서비스가 없는 테스트 클러스터에서는 clicklink clctl platform reset 명령으로 플랫폼 릴리스를 제거할 수 있습니다. 이때 남는 CustomResourceDefinition, RBAC, StorageClass는 직접 삭제해야 합니다. 테스트 클러스터 초기화를 참조하십시오. 테스트 클러스터가 아닌 환경에서는 플랫폼 레이어를 변경하기 전에 계정 담당 팀과 삭제 계획을 협의하십시오.

ClickHouse 사용자

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

DROP USER IF EXISTS pcm_scraper, pcm_troubleshooter;

시작하기

서비스 및 인프라

Bring Your Own Cloud

데이터 및 통합

연결 및 쿼리 실행

접근 관리

보안 및 컴플라이언스

모니터링 및 백업

AI 도구 및 에이전트

Cloud API

청구

지원

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 사용자