운영 가이드

Skuber+ Observability의 업그레이드, 롤백, 삭제 등 운영 작업을 안내합니다.

업그레이드

업그레이드 순서

업그레이드는 반드시 아래 순서로 수행하세요:

1. CH VM (DB 에이전트 + OTel Agent + DDL)
2. Host 클러스터
3. Agent 클러스터

Schema Migrator가 ClickHouse 스키마를 업데이트하므로 Host를 Agent보다 먼저 처리해야 합니다.

CH VM 업그레이드

DB 에이전트, OTel Agent config, DDL 스키마를 업그레이드합니다.

./skuberplus-observability-db upgrade \
    --mode ssh \
    --ssh-user <SSH_USER> \
    --ssh-key <SSH_KEY_PATH> \
    --ssh-password '<SSH_PASSWORD>' \
    --clickhouse-host <CLICKHOUSE_IP> \
    --clickhouse-password '<CLICKHOUSE_PASSWORD>' \
    --otel-endpoint <HOST_GATEWAY_IP>:4317 \
    --environment <ENV> \
    --verbose --yes

TLS 사용 시 --otel-tls, self-signed 인증서는 --otel-tls-skip-verify 추가

업그레이드 실패 시 자동 롤백: 헬스체크 실패 시 이전 바이너리/config로 자동 복원됩니다.

버전 확인:

./skuberplus-observability-db --version

VM에서 실행 중인 에이전트 버전 확인:

curl http://127.0.0.1:8099/health

"version" 필드에 현재 버전이 표시됩니다.

Host 클러스터 업그레이드

--reuse-values 주의: 이미지 태그만 변경할 때는 --reuse-values가 안전합니다. 그러나 차트 버전을 변경할 때는 새 차트에 추가된 values가 누락되거나 구조 변경으로 충돌할 수 있습니다. 차트 버전 변경 시에는 아래 안전 패턴을 사용하세요.

이미지 태그 또는 설정 변경:

helm upgrade skuberplus-observability-host \
  oci://registry.skuberplus.com/charts/skuberplus-observability-host \
  --version <차트-버전> \
  --kube-context <host-context> \
  --namespace skuber-observability \
  --reuse-values \
  --set o11yHub.image.tag=<새-태그>

--reuse-values는 기존 설정값을 유지하면서 지정한 값만 변경합니다.

차트 버전 업그레이드 (안전 패턴):

helm get values skuberplus-observability-host \
  --kube-context <host-context> \
  --namespace skuber-observability \
  -o yaml > current-values.yaml

필요한 값을 수정한 후:

helm upgrade skuberplus-observability-host \
  oci://registry.skuberplus.com/charts/skuberplus-observability-host \
  --version <새-차트-버전> \
  --kube-context <host-context> \
  --namespace skuber-observability \
  -f current-values.yaml

업그레이드 확인:

kubectl --context <host-context> -n skuber-observability get pods

다운타임 주의: Hub는 StatefulSet이므로 업그레이드 시 다운타임이 발생합니다. 유지보수 시간에 수행하세요.

Agent 클러스터 업그레이드

helm upgrade skuberplus-observability-agent \
  oci://registry.skuberplus.com/charts/skuberplus-observability-agent \
  --version <차트-버전> \
  --kube-context <agent-context> \
  --namespace skuber-observability \
  --reuse-values

DaemonSet(OTel Agent, APM Agent)은 Rolling Update 방식으로 노드별 순차 업그레이드됩니다. 데이터 수집이 잠시 중단될 수 있습니다.

모든 파드가 Running 상태이고 RESTARTS가 0인지 확인합니다.

롤백

업그레이드 후 문제가 발생하면 이전 버전으로 롤백할 수 있습니다.

경고: 차트 버전 업그레이드 후 롤백하면 ClickHouse 스키마와 불일치가 발생할 수 있습니다. Schema Migrator가 실행한 ALTER TABLE/CREATE TABLE은 자동으로 되돌아가지 않습니다. 롤백 전 스키마 변경 내역을 확인하세요.

릴리스 히스토리 확인

helm history skuberplus-observability-host \
  --kube-context <host-context> \
  --namespace skuber-observability

이전 버전으로 롤백

helm rollback skuberplus-observability-host <리비전-번호> \
  --kube-context <host-context> \
  --namespace skuber-observability

현재 설정값 확인

helm get values skuberplus-observability-host \
  --kube-context <host-context> \
  --namespace skuber-observability

삭제

삭제는 Agent 클러스터 → Host 클러스터 → CH VM 순서로 수행합니다.

주의: 삭제 후에도 ClickHouse에 저장된 관측성 데이터는 유지됩니다. 데이터까지 삭제하려면 ClickHouse에서 별도로 처리해야 합니다.

Agent 클러스터 삭제

1. Instrumentation CRD 삭제

OTel Operator가 삭제되기 전에 Instrumentation CRD를 먼저 제거해야 합니다.

kubectl --context <agent-context> -n skuber-observability \
  delete instrumentation --all

2. Helm 릴리스 삭제

helm uninstall skuberplus-observability-agent \
  --kube-context <agent-context> \
  --namespace skuber-observability

3. cert-manager 처리

cert-manager는 다른 애플리케이션에서도 사용할 수 있으므로 기본적으로 보존합니다.
다른 곳에서 사용하지 않는 경우에만 삭제:

helm --kube-context <agent-context> uninstall cert-manager -n cert-manager

4. 네임스페이스 삭제 (선택)

kubectl --context <agent-context> delete namespace skuber-observability

Host 클러스터 삭제

사전 확인:

• Agent 클러스터 삭제 완료
• ClickHouse 데이터 백업 여부 결정

1. Helm 릴리스 삭제

helm uninstall skuberplus-observability-host \
  --kube-context <host-context> \
  --namespace skuber-observability

2. PVC 삭제 (선택)

PVC(영구 볼륨)는 자동 삭제되지 않습니다. Hub의 로컬 데이터가 불필요하면:

kubectl --context <host-context> -n skuber-observability delete pvc --all

3. 네임스페이스 삭제 (선택)

kubectl --context <host-context> delete namespace skuber-observability

CH VM 삭제

ClickHouse, Keeper, DB 에이전트, OTel Agent를 삭제합니다.

./skuberplus-observability-db uninstall \
    --mode ssh \
    --ssh-user <SSH_USER> \
    --ssh-key <SSH_KEY_PATH> \
    --ssh-password '<SSH_PASSWORD>' \
    --keeper-host <KEEPER_IP> \
    --clickhouse-host <CLICKHOUSE_IP> \
    --verbose --yes

삭제 항목: ClickHouse Server/Client, Keeper, clickhouse-backup, DB 에이전트 (systemd), OTel Agent (otelcol-contrib), 설정 파일, 데이터 디렉토리

--keep-data를 추가하면 /var/lib/clickhouse 데이터를 보존합니다 (미지정 시 전체 삭제).

삭제 확인

각 클러스터에서 리소스가 남아있지 않은지 확인합니다:

helm --kube-context <context> list -n skuber-observability
kubectl --context <context> -n skuber-observability get all

ClickHouse 데이터만 삭제

VM은 유지하면서 관측성 데이터만 삭제하려면:

경고: 이 작업은 되돌릴 수 없습니다. 모든 메트릭, 로그, 트레이스 데이터가 영구 삭제됩니다.

ClickHouse 서버에 접속:

clickhouse-client --password '<CLICKHOUSE_PASSWORD>'

데이터베이스 삭제:

DROP DATABASE IF EXISTS signoz_metrics ON CLUSTER skuber_cluster SYNC;
DROP DATABASE IF EXISTS signoz_traces ON CLUSTER skuber_cluster SYNC;
DROP DATABASE IF EXISTS signoz_logs ON CLUSTER skuber_cluster SYNC;
DROP DATABASE IF EXISTS signoz_meter ON CLUSTER skuber_cluster SYNC;
DROP DATABASE IF EXISTS signoz_metadata ON CLUSTER skuber_cluster SYNC;
DROP DATABASE IF EXISTS signoz_analytics ON CLUSTER skuber_cluster SYNC;
DROP DATABASE IF EXISTS skuber ON CLUSTER skuber_cluster SYNC;

문제 해결

문의

기술 지원 문의: sales@skuberplus.com