Host 클러스터 설치

Host Cluster에 Skuber+ Observability 중앙 서버를 설치하는 방법을 안내합니다.

개요

Host Cluster는 모든 Agent Cluster의 관측성 데이터를 수집하고, 외부 ClickHouse 서버에 저장된 데이터를 조회하여 시각화하는 중앙 서버입니다.

중요: ClickHouse는 Host Cluster 내부가 아닌 외부 별도 VM 서버에 설치됩니다.
ClickHouse 서버 설치는 ClickHouse 서버 설치 문서를 참조하세요.

설치되는 컴포넌트

아키텍처

사전 요구사항

설치 전 다음 사항을 확인하세요:

• ClickHouse 서버 설치 완료 (필수)
• Kubernetes 1.24+ 클러스터 접근 권한
• kubectl 설치 및 클러스터 접근 설정
• LoadBalancer 또는 Ingress 설정 가능
• ClickHouse 서버로 네트워크 연결 가능 (TCP 9000)

ClickHouse 연결 정보 확인

Host 설치 전에 ClickHouse 서버 정보를 확인합니다:

# ClickHouse 서버 연결 테스트
nc -zv <clickhouse-ip> 9000

# ClickHouse 접속 확인
clickhouse-client --host <clickhouse-ip> --password '<password>' --query "SELECT 1"

설치 방법

설치 스크립트 사용 (권장)

Skuber+ Observability Host는 설치 스크립트를 통해 간편하게 설치할 수 있습니다.

Step 1: 스크립트 다운로드

curl -O https://install.skuberplus.com/o11y-host-install.sh
chmod +x o11y-host-install.sh

Step 2: 스크립트 실행

기본 설치:

./o11y-host-install.sh \
  --cluster-context <host-cluster-context> \
  --external-clickhouse-host <clickhouse-ip> \
  --external-clickhouse-user <username> \
  --external-clickhouse-password <password>

이메일 알림 포함 설치:

./o11y-host-install.sh \
  --cluster-context skuber-observability \
  --external-clickhouse-host 192.168.254.237 \
  --external-clickhouse-user default \
  --external-clickhouse-password "YourPassword" \
  --enable-email-alerts \
  --smtp-from "noreply@example.com" \
  --smtp-hello "mail.example.com" \
  --smtp-smarthost "smtp.mailgun.org:587" \
  --smtp-username "postmaster@example.com" \
  --smtp-password "smtp-password" \
  --smtp-require-tls

파라미터 설명

필수 파라미터

선택 파라미터

이메일 알림 파라미터 (선택)

사용 예시

# 기본 설치 (검증 모드)
./o11y-host-install.sh \
  --cluster-context skuber-observability \
  --external-clickhouse-host 192.168.254.237 \
  --external-clickhouse-user default \
  --external-clickhouse-password "Wonder9595" \
  --dry-run

# 실제 설치 (상세 로그)
./o11y-host-install.sh \
  --cluster-context skuber-observability \
  --external-clickhouse-host 192.168.254.237 \
  --external-clickhouse-user default \
  --external-clickhouse-password "Wonder9595" \
  --verbose

설치 확인

파드 상태 확인

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

정상 설치 시 출력:

NAME                                    READY   STATUS    RESTARTS   AGE
skuber-observability-0                  2/2     Running   0          5m
o11y-core-xxx-yyy                       1/1     Running   0          5m
otel-collector-gateway-xxx-yyy          1/1     Running   0          5m

서비스 상태 확인

kubectl --context=<host-context> get svc -n skuber-observability

ClickHouse 연결 확인

# o11y-core에서 ClickHouse 연결 확인
kubectl --context=<host-context> logs -n skuber-observability \
  -l app.kubernetes.io/name=o11y-core --tail=20 | grep -i clickhouse

서비스 접근 설정

LoadBalancer 사용 시

External IP 확인:

# UI 접근 IP
kubectl --context=<host-context> get svc skuber-observability \
  -n skuber-observability \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

# OTel Gateway IP (Agent Cluster에서 사용)
kubectl --context=<host-context> get svc otel-collector-gateway \
  -n skuber-observability \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

NodePort 사용 시

NodePort 확인:

kubectl --context=<host-context> get svc -n skuber-observability -o wide

접근 URL: http://<node-ip>:<node-port>

Gateway IP 기록

Agent Cluster 설치 시 필요한 Gateway IP를 기록합니다:

# Gateway IP 확인 및 기록
export HOST_GATEWAY_IP=$(kubectl --context=<host-context> get svc otel-collector-gateway \
  -n skuber-observability \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

echo "Host Gateway IP: $HOST_GATEWAY_IP"
echo "Agent Cluster 설치 시 이 IP를 사용하세요: $HOST_GATEWAY_IP:4317"

초기 접속

웹 UI 접속

1. 브라우저에서 UI 서비스 주소로 접속합니다:

   http://<ui-external-ip>:8080

2. 초기 화면에서 다음을 확인할 수 있습니다:

   • Service Map (Agent 연결 후 데이터 표시)
   • Logs Explorer
   • Metrics Explorer
   • Traces Explorer

Skuber+ Client 연동

Skuber+ Client에서 Observability 플러그인을 사용하려면:

1. Skuber+ Client 실행
2. Settings > Plugins > Observability 활성화
3. Host Cluster URL 입력: http://<ui-external-ip>:8080
4. 연결 테스트 및 저장

설치 검증

컴포넌트 상태 확인

# 모든 파드 상태 확인
kubectl --context=<host-context> get pods -n skuber-observability -o wide

# 서비스 엔드포인트 확인
kubectl --context=<host-context> get endpoints -n skuber-observability

로그 확인

# OTel Gateway 로그
kubectl --context=<host-context> logs -n skuber-observability \
  -l app.kubernetes.io/name=otel-gateway --tail=50

# o11y-core 로그
kubectl --context=<host-context> logs -n skuber-observability \
  -l app.kubernetes.io/name=o11y-core --tail=50

연결 테스트

# OTel Gateway 헬스체크
kubectl --context=<host-context> exec -n skuber-observability \
  -l app.kubernetes.io/name=otel-gateway -- wget -O- http://localhost:13133/health

문제 해결

파드가 Pending 상태인 경우

# 파드 이벤트 확인
kubectl --context=<host-context> describe pod <pod-name> -n skuber-observability

# 일반적인 원인:
# - StorageClass 없음 → --storage-class 옵션 지정
# - 리소스 부족 → 노드 스케일업 또는 리소스 요청 감소

LoadBalancer IP가 할당되지 않는 경우

# 서비스 상태 확인
kubectl --context=<host-context> describe svc otel-collector-gateway \
  -n skuber-observability

# 클라우드 환경 확인:
# - AWS: AWS Load Balancer Controller 설치 필요
# - GKE: 자동 지원
# - NKS: Naver Cloud LoadBalancer 자동 지원

ClickHouse 연결 오류

# 네트워크 연결 테스트
kubectl --context=<host-context> run test --rm -it --image=busybox -- \
  nc -zv <clickhouse-ip> 9000

# o11y-core 로그에서 오류 확인
kubectl --context=<host-context> logs -n skuber-observability \
  -l app.kubernetes.io/name=o11y-core | grep -i error

다음 단계

Host Cluster 설치가 완료되면:

1. Agent 클러스터 설치 - 모니터링 대상 클러스터에 Agent 설치
2. 데이터 보존 설정 - 데이터 보존 기간 설정