Host 클러스터 설치

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

개요

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

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

설치되는 컴포넌트

아키텍처

사전 요구사항

• ClickHouse 서버 설치 완료 — ClickHouse 서버 설치 문서 참조
• Kubernetes 1.28+ 클러스터
• kubectl 및 helm v3.12+ 설치
• Harbor 레지스트리 접근 가능 — registry.skuberplus.com (차트 및 이미지)
• ClickHouse 서버 네트워크 접근 가능 (TCP :9000, HTTP :8123)

설치

Helm 차트 설치

OCI 레지스트리에서 직접 설치합니다.

helm install skuberplus-observability-host \
  oci://registry.skuberplus.com/charts/skuberplus-observability-host \
  --version <차트-버전> \
  --kube-context <host-cluster-context> \
  --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-이미지-태그> \
  --set o11yHub.image.tag=<hub-이미지-태그> \
  --set o11yHub.additionalEnvs.CH_HOST=<CLICKHOUSE_VM_IP> \
  --set o11yHub.additionalEnvs.CH_PASSWORD='<CLICKHOUSE_PASSWORD>' \
  --set o11yHub.additionalEnvs.SKUBER_ENCRYPTION_KEY=<ENCRYPTION_KEY>

SKUBER_ENCRYPTION_KEY는 DB 설치 시 사용한 동일한 키입니다. S3 credential 암/복호화에 사용됩니다.

설치 옵션

필수 옵션

ClickHouse 연결 옵션

기타 옵션

주의: ClickHouse가 단일 노드(Keeper 미연결)인 경우 schemaMigrator.enableReplication을 반드시 false로 설정하세요. true인 상태에서 Keeper가 없으면 ReplicatedMergeTree 테이블 생성이 실패합니다.

(선택) TLS 보안 통신

Agent Cluster가 다른 VPC 또는 다른 클라우드/네트워크에 위치하여 퍼블릭 구간을 경유하는 경우, Agent → Host 간 OTLP 전송에 TLS 암호화를 적용해야 합니다.

같은 VPC/네트워크 내에서 통신하는 경우 TLS 설정은 불필요합니다. 기본값(평문 전송)으로 사용하세요.

[TLS 필요한 경우]
Agent (VPC A) → 퍼블릭 NLB → Host OTel Gateway (VPC B)  ← 암호화 필수

[TLS 불필요한 경우]
Agent (VPC A) → 프라이빗 LB → Host OTel Gateway (VPC A)  ← 평문 OK

Step 1: 인증서 준비

인증서를 K8s Secret으로 준비합니다. 4가지 방식 중 환경에 맞게 선택하세요.

TLS 설정 도구(skuberplus-observability-tls)를 사용하면 인증서 생성부터 Secret 등록까지 자동화됩니다:

# 고객 인증서 사용
./skuberplus-observability-tls setup --mode existing \
  --cert ./tls.crt --key ./tls.key \
  --secret-name skuber-otel-collector-tls \
  --kube-context <host-cluster-context>

# 사내 CA
./skuberplus-observability-tls setup --mode private-ca \
  --domain <도메인> \
  --ca-cert ./ca.crt --ca-key ./ca.key \
  --secret-name skuber-otel-collector-tls \
  --kube-context <host-cluster-context>

# Let's Encrypt (퍼블릭 도메인 필요)
./skuberplus-observability-tls setup --mode letsencrypt \
  --domain <도메인> --email <이메일> \
  --secret-name skuber-otel-collector-tls \
  --kube-context <host-cluster-context>

# Self-signed (테스트용)
./skuberplus-observability-tls setup --mode selfsigned \
  --domain <도메인> \
  --secret-name skuber-otel-collector-tls \
  --kube-context <host-cluster-context>

cert-manager가 필요한 모드(사내 CA, Let's Encrypt, Self-signed)는 도구가 자동 설치합니다.
모든 모드의 사용법은 ./skuberplus-observability-tls setup --help로 확인할 수 있습니다.

Step 2: Helm 설치 시 TLS 옵션 추가

기존 helm install 명령어에 아래 3줄을 추가합니다:

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

TLS 옵션

TLS를 활성화하면 OTel Gateway의 gRPC(:4317)와 HTTP(:4318) 모두 TLS로 수신합니다. Agent 클러스터 설치 시에도 TLS 옵션을 맞춰야 합니다 — Agent 클러스터 TLS 설정을 참조하세요.

설치 확인

파드 상태

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

정상 설치 시:

NAME                                              READY   STATUS      RESTARTS   AGE
skuberplus-observability-host-0                   2/2     Running     0          5m
o11y-core-xxxxxxxxx-xxxxx                         1/1     Running     0          5m
skuberplus-observability-host-otel-collector-gw-xxx 1/1   Running     0          5m
skuberplus-observability-host-schema-migrator-xxx 0/1     Completed   0          5m

schema-migrator는 ClickHouse에 기본 테이블을 생성하는 초기화 Job으로, Completed가 정상입니다.

OTel Gateway IP 기록

Agent Cluster 설치 시 필요한 Gateway 주소를 확인합니다:

kubectl --context <host-context> -n skuber-observability \
  get svc skuberplus-observability-host-otel-collector-gw \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

이 IP를 기록해두세요. Agent 클러스터 설치 시 사용합니다.

• gRPC: <gateway-ip>:4317
• HTTP (평문): http://<gateway-ip>:4318
• HTTP (TLS): https://<gateway-ip>:4318

웹 UI 접속

LoadBalancer IP 확인

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

브라우저에서 http://<external-ip>:8080으로 접속합니다.

문제 해결

Schema Migrator 실패

kubectl --context <host-context> -n skuber-observability \
  logs -l app.kubernetes.io/component=schema-migrator

ClickHouse 연결 오류

Host Cluster 내부에서 ClickHouse 접근 테스트

kubectl --context <host-context> -n skuber-observability \
  run ch-test --rm -it --image=busybox -- nc -zv $CH_HOST 9000

파드가 Pending 상태인 경우 — kubectl describe pod로 이벤트 확인. StorageClass 미지정 또는 리소스 부족이 일반적 원인입니다.

LoadBalancer IP가 할당되지 않는 경우 — AWS는 Load Balancer Controller, On-premise는 MetalLB 등 LB 프로비저너가 필요합니다.

다음 단계

Host Cluster 설치가 완료되면:

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