설치 가이드

Skuber+ Observability 전체 설치 가이드입니다.
요구사항과 AWS 인프라 구성이 완료된 상태에서 진행합니다.

설치 순서

TLS: Agent가 다른 VPC/네트워크에 위치하여 퍼블릭 구간을 경유하는 경우, Step 2에서 TLS 인증서를 설정하고 Step 3, 6에서 TLS 옵션을 추가합니다. 같은 네트워크 내 통신이면 TLS는 불필요합니다.

사전 확인

VM 접속 확인

Keeper VM에 접속하여 sudo 권한을 확인합니다.

ssh -i <SSH_KEY> <SSH_USER>@<KEEPER_IP>
sudo whoami

ClickHouse VM에 접속하여 sudo 권한을 확인합니다.

ssh -i <SSH_KEY> <SSH_USER>@<CLICKHOUSE_IP>
sudo whoami

두 VM 모두 root가 출력되어야 합니다.

K8s 접근 확인

Host Cluster 접근을 확인합니다.

kubectl --context <HOST_CONTEXT> get nodes

Agent Cluster 접근을 확인합니다.

kubectl --context <AGENT_CONTEXT> get nodes

로드밸런서 정보 확인

Host 설치 시 externalClickhouse.host 값으로 사용할 로드밸런서 DNS 이름 또는 IP를 확인합니다. AWS 환경의 경우 NLB DNS를 AWS Console에서 확인하세요.

SKUBER_ENCRYPTION_KEY 생성

S3 credential 암호화에 사용하는 키를 생성합니다. Step 1과 Step 3에서 동일한 키를 사용합니다.

openssl rand -hex 32

⚠️ 이 키는 반드시 안전하게 보관하세요. 분실 시 S3 credential 복호화가 불가능하며, 복구할 수 없습니다.

Step 1. DB 설치 + 에이전트 배포

설치 도구가 SSH로 VM에 접속하여 Keeper, ClickHouse, DB 에이전트를 자동 설치합니다.

설치되는 항목

설치 도구 준비

설치 도구(skuberplus-observability-db)는 Wondermove에서 별도 전달됩니다.

실행

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

--clickhouse-password는 이후 모든 ClickHouse 접속에 사용됩니다. 안전하게 보관하세요.

--encryption-key를 지정하면 에이전트가 자동으로 함께 설치됩니다. 생략하면 에이전트 없이 DB만 설치됩니다.

⚠️ 비밀번호에 $, !, ` 등 특수문자가 포함된 경우 반드시 **single quote(')**로 감싸세요. Double quote는 shell에서 변수 확장이 발생할 수 있습니다.

결과 확인

Keeper 상태를 확인합니다. (Keeper VM에서 실행)

echo mntr | nc localhost 9181 | grep zk_server_state

zk_server_state standalone이 출력되어야 합니다.

ClickHouse 서비스 상태를 확인합니다. (ClickHouse VM에서 실행)

systemctl is-active clickhouse-server

active가 출력되어야 합니다.

에이전트 상태를 확인합니다. (ClickHouse VM에서 실행)

curl http://127.0.0.1:8099/health

{"status":"ok","ch_connected":true,...}가 출력되면 정상입니다.

Step 2. (선택) TLS 인증서 설정

이 단계는 Agent가 다른 VPC/네트워크에 위치하여 퍼블릭 구간을 경유하는 경우에만 필요합니다. 같은 네트워크 내 통신이면 이 단계를 건너뛰고 Step 3으로 진행하세요.

TLS 설정 도구가 인증서를 생성하고 K8s Secret으로 등록합니다.

고객 자체 인증서 사용:

./skuberplus-observability-tls setup --mode existing \
    --cert <인증서_경로> \
    --key <개인키_경로> \
    --secret-name skuber-otel-collector-tls \
    --kube-context <HOST_CONTEXT>

Self-signed (테스트/PoC용):

./skuberplus-observability-tls setup --mode selfsigned \
    --domain <도메인> \
    --secret-name skuber-otel-collector-tls \
    --kube-context <HOST_CONTEXT>

모든 모드의 사용법은 ./skuberplus-observability-tls setup --help로 확인할 수 있습니다.

상세한 TLS 옵션은 Host 클러스터 문서의 "TLS 보안 통신" 섹션을 참조하세요.

Secret 생성 확인

kubectl --context <HOST_CONTEXT> -n skuber-observability get secret skuber-otel-collector-tls

Step 3. Host 클러스터 설치

중앙 수집 서버(UI, OTel Gateway, 백엔드)를 배포합니다.

상세한 Helm 값 설정은 Host 클러스터 문서를 참조하세요.

helm upgrade --install skuberplus-observability-host \
    --kube-context <HOST_CONTEXT> \
    oci://registry.skuberplus.com/charts/skuberplus-observability-host \
    --version <CHART_VERSION> \
    --namespace skuber-observability \
    --create-namespace \
    --set externalClickhouse.host=<NLB_DNS_OR_IP> \
    --set externalClickhouse.user=default \
    --set externalClickhouse.password='<CLICKHOUSE_PASSWORD>' \
    --set o11yCore.image.tag=<CORE_IMAGE_TAG> \
    --set o11yHub.image.tag=<HUB_IMAGE_TAG> \
    --set o11yHub.additionalEnvs.CH_HOST=<CLICKHOUSE_VM_IP> \
    --set o11yHub.additionalEnvs.CH_PASSWORD='<CLICKHOUSE_PASSWORD>' \
    --set o11yHub.additionalEnvs.SKUBER_ENCRYPTION_KEY=<ENCRYPTION_KEY>

TLS 사용 시 위 명령어 끝에 아래 3줄을 추가합니다 (Step 2 완료 필요):

    --set otelCollector.tls.enabled=true \
    --set otelCollector.tls.existingSecretName=skuber-otel-collector-tls \
    --set otelCollector.tls.path=/etc/otel/tls

주요 파라미터

Pod 상태 확인

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

아래 Pod이 모두 Running 상태인지 확인 후 다음 단계로 진행합니다:

Step 4. Post-Install

ClickHouse에 Skuber+ Observability 전용 스키마를 적용하고, CH VM에 메트릭 수집 에이전트를 설치합니다.

./skuberplus-observability-db post-install \
    --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

--otel-endpoint를 지정하면 CH VM에 OTel Agent(otelcol-contrib)가 설치되어 호스트 메트릭과 ClickHouse 메트릭을 수집합니다. 생략하면 OTel Agent 설치를 스킵합니다.

Host에서 TLS를 활성화한 경우 --otel-tls를 추가하세요. Self-signed 인증서라면 --otel-tls-skip-verify도 추가합니다.

적용 내용

데이터 보존 기간(TTL)과 S3 스토리지는 설치 후 UI에서 설정합니다.
데이터 보존 문서를 참조하세요.

결과 확인

ClickHouse VM에서 클라이언트에 접속합니다.

clickhouse-client -h 127.0.0.1 --password '<CLICKHOUSE_PASSWORD>'

데이터베이스가 생성되었는지 확인합니다.

SHOW DATABASES;

signoz_logs, signoz_metrics, signoz_traces, signoz_analytics, skuber 등이 표시되어야 합니다.

테이블 수를 확인합니다.

SELECT database, count() FROM system.tables
WHERE database LIKE 'signoz_%' OR database = 'skuber' GROUP BY database;

Step 5. cert-manager 설치 (Agent 클러스터)

Agent 차트의 OTel Operator가 cert-manager에 의존합니다. Agent 클러스터마다 사전 설치가 필요합니다.

helm install cert-manager jetstack/cert-manager \
    --namespace cert-manager \
    --create-namespace \
    --version v1.17.1 \
    --set crds.enabled=true \
    --kube-context <AGENT_CONTEXT> \
    --wait --timeout 5m

Helm repo가 없으면 먼저 추가합니다: helm repo add jetstack https://charts.jetstack.io

설치 확인

kubectl --context <AGENT_CONTEXT> -n cert-manager get pods

3개 Pod(cert-manager, cainjector, webhook)이 모두 Running이어야 합니다.

이미 cert-manager가 설치된 클러스터라면 이 단계를 건너뛰세요.

Step 6. Agent 클러스터 설치

모니터링 대상 클러스터에 수집 에이전트를 설치합니다.

상세한 Helm 값 설정은 Agent 클러스터 문서를 참조하세요.

기본 설치 (평문 통신):

helm upgrade --install skuberplus-observability-agent \
    --kube-context <AGENT_CONTEXT> \
    oci://registry.skuberplus.com/charts/skuberplus-observability-agent \
    --version <CHART_VERSION> \
    --namespace skuber-observability \
    --create-namespace \
    --set global.clusterName=<CLUSTER_NAME> \
    --set global.deploymentEnvironment=<ENV> \
    --set global.otelInsecure=true \
    --set global.hostEndpointHttp=http://<HOST_GATEWAY_IP>:4318 \
    --set skuber-otel-agent.otelCollectorEndpoint=<HOST_GATEWAY_IP>:4317 \
    --set skuber-apm-agent.config.data.attributes.kubernetes.cluster_name=<CLUSTER_NAME> \
    --set instrumentation.exporter.endpoint=http://<HOST_GATEWAY_IP>:4317 \
    --wait --timeout 25m

TLS 설치:

Host에서 TLS를 활성화한 경우 (Step 2, 3 참조), Agent도 TLS로 전송해야 합니다.

helm upgrade --install skuberplus-observability-agent \
    --kube-context <AGENT_CONTEXT> \
    oci://registry.skuberplus.com/charts/skuberplus-observability-agent \
    --version <CHART_VERSION> \
    --namespace skuber-observability \
    --create-namespace \
    --set global.clusterName=<CLUSTER_NAME> \
    --set global.deploymentEnvironment=<ENV> \
    --set global.otelInsecure=false \
    --set global.hostEndpointHttp=https://<HOST_GATEWAY_IP>:4318 \
    --set skuber-otel-agent.otelCollectorEndpoint=<HOST_GATEWAY_IP>:4317 \
    --set skuber-otel-agent.otelInsecure=false \
    --set skuber-otel-agent.insecureSkipVerify=true \
    --set skuber-apm-agent.config.data.attributes.kubernetes.cluster_name=<CLUSTER_NAME> \
    --set instrumentation.exporter.endpoint=https://<HOST_GATEWAY_IP>:4317 \
    --wait --timeout 25m

insecureSkipVerify=true는 self-signed 인증서 사용 시 필요합니다. 공인 인증서(Let's Encrypt 등)를 사용하는 경우 이 옵션은 불필요합니다.

주요 파라미터

Pod 상태 확인

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

Step 7. 설치 확인

모든 설치가 완료되면 UI에 접속하여 데이터 수집을 확인합니다.

UI 접속

Host Cluster의 UI Service IP를 확인합니다.

kubectl --context <HOST_CONTEXT> get svc -n skuber-observability | grep 8080

브라우저에서 http://<UI_IP>:8080에 접속합니다.

첫 접속 시 admin 계정 생성 화면이 표시됩니다. 이름, 이메일, 비밀번호를 입력하여 관리자 계정을 생성하세요.

확인 항목

• 초기 admin 계정 생성 완료
• 로그인 성공
• Services 메뉴에서 서비스 목록 표시
• Logs 메뉴에서 로그 검색 가능
• Traces 메뉴에서 트레이스 표시
• Metrics 메뉴에서 메트릭 그래프 표시
• Infrastructure 메뉴에서 K8s 리소스 표시

데이터가 표시되기까지 2~3분 정도 소요될 수 있습니다.

삭제 (Uninstall)

삭제 방법은 운영 가이드를 참조하세요.

문제 해결

Keeper 서비스 시작 실패

서비스 상태를 확인합니다.

systemctl status clickhouse-keeper

로그를 확인합니다.

journalctl -u clickhouse-keeper --no-pager -n 50

데이터 디렉토리 권한을 확인합니다.

ls -la /var/lib/clickhouse/coordination/

ClickHouse 서비스 시작 실패

서비스 상태를 확인합니다.

systemctl status clickhouse-server

에러 로그를 확인합니다.

tail -50 /var/log/clickhouse-server/clickhouse-server.err.log

설정 파일을 확인합니다.

ls -la /etc/clickhouse-server/config.d/

에이전트 상태 확인

서비스 상태:

systemctl status skuber-db-agent

로그 확인:

journalctl -u skuber-db-agent --no-pager -n 50

헬스체크:

curl http://127.0.0.1:8099/health

Host Cluster에서 ClickHouse 연결 실패

로드밸런서를 통한 연결을 테스트합니다. (Host Cluster에서 실행)

kubectl --context <HOST_CONTEXT> run test --rm -it --image=busybox -- \
    nc -zv <LB_DNS_OR_IP> 9000

AWS 환경의 경우 NLB Target Group 상태가 healthy인지 AWS Console에서 확인하세요.

ClickHouse VM에서 직접 연결을 테스트합니다.

clickhouse-client -h 127.0.0.1 --password '<PASSWORD>' -q 'SELECT 1'

Agent에서 Host로 데이터 전송 실패

Agent Cluster에서 Host Gateway 연결을 테스트합니다.

kubectl --context <AGENT_CONTEXT> run test --rm -it --image=busybox -- \
    nc -zv <HOST_GATEWAY_IP> 4317

OTel Agent 로그를 확인합니다.

kubectl --context <AGENT_CONTEXT> \
    logs -n skuber-observability -l app=skuber-otel-agent --tail=50

UI에서 데이터가 표시되지 않음

SigNoz Pod 로그를 확인합니다.

kubectl --context <HOST_CONTEXT> \
    logs skuberplus-observability-host-0 -n skuber-observability -c signoz --tail=50

ClickHouse에 데이터가 유입되고 있는지 확인합니다.

clickhouse-client -h 127.0.0.1 --password '<PASSWORD>' \
    -q "SELECT count() FROM signoz_logs.logs_v2"

다음 단계

설치가 완료되면 데이터 보존 기간과 S3 스토리지를 설정합니다:

• 데이터 보존 — TTL 설정, S3 Warm/Cold 스토리지 활성화

문의

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