Agent 클러스터 설치

모니터링 대상 클러스터에 Skuber+ Observability Agent를 설치하는 방법을 안내합니다.

개요

Agent Cluster는 메트릭, 로그, 트레이스를 수집하여 Host Cluster로 전송하는 역할을 합니다.

설치되는 컴포넌트

아키텍처

컴포넌트 역할:

사전 요구사항

필수 사항

• Host Cluster 설치 완료 및 Gateway IP 확인
• Agent Cluster에 대한 kubectl 접근 권한
• Linux 커널 5.8+ (eBPF 자동 계측 지원)

Host Gateway IP 확인

Agent 설치 전 Host Cluster의 Gateway IP를 확인합니다:

# Host Cluster 컨텍스트에서 실행
kubectl config use-context <host-cluster-context>

kubectl get svc otel-collector-gateway -n skuber-observability \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

출력된 IP를 기록합니다 (예: 192.168.254.246).

네트워크 연결 확인

Agent Cluster에서 Host Gateway로 연결 가능한지 확인합니다:

# Agent Cluster 컨텍스트에서 실행
kubectl config use-context <agent-cluster-context>

kubectl run test --rm -it --image=busybox -- \
  wget -O- --timeout=5 http://<host-gateway-ip>:4317

설치 방법

설치 스크립트 다운로드

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

스크립트 실행

./o11y-agent-install.sh \
  --cluster-context <agent-cluster-context> \
  --host-lb-ip <host-gateway-ip> \
  --cluster-name <cluster-name> \
  --environment <environment>

파라미터 설명:

사용 예시:

# 개발 환경 설치
./o11y-agent-install.sh \
  --cluster-context flash-cluster-1 \
  --host-lb-ip 192.168.254.246 \
  --cluster-name flash-cluster-1 \
  --environment dev

# 프로덕션 환경 설치 (상세 로그)
./o11y-agent-install.sh \
  --cluster-context prod-cluster \
  --host-lb-ip 10.0.0.100 \
  --cluster-name production \
  --environment prod \
  --verbose

# Dry-run (검증만)
./o11y-agent-install.sh \
  --cluster-context test-cluster \
  --host-lb-ip 172.16.0.50 \
  --cluster-name test-env \
  --environment staging \
  --dry-run

설치 확인

파드 상태 확인

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

정상 설치 시 출력:

NAME                                           READY   STATUS    RESTARTS   AGE
skuber-k8s-infra-otel-agent-xxxxx              1/1     Running   0          2m
skuber-apm-agent-xxxxx                         1/1     Running   0          2m
skuber-apm-agent-yyyyy                         1/1     Running   0          2m
kube-state-metrics-xxxxx                       1/1     Running   0          2m
opentelemetry-operator-xxxxx                   1/1     Running   0          2m

DaemonSet 상태 확인

kubectl --context=<agent-context> get daemonset -n skuber-observability

NAME                          DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE
skuber-k8s-infra-otel-agent   3         3         3       3            3
skuber-apm-agent              3         3         3       3            3

로그 확인

# OTel Collector 로그
kubectl --context=<agent-context> logs -n skuber-observability \
  -l app.kubernetes.io/name=k8s-infra --tail=50

# APM Agent 로그
kubectl --context=<agent-context> logs -n skuber-observability \
  -l app.kubernetes.io/name=skuber-apm-agent --tail=50

데이터 확인

Host Cluster UI에서 확인

1. Host Cluster UI에 접속 (http://<host-ui-ip>:8080)
2. 좌측 메뉴에서 Infrastructure > Kubernetes 클릭
3. 상단 필터에서 설치한 클러스터 선택
4. 노드 및 파드 메트릭 확인

Service Map 확인

1. 좌측 메뉴에서 Service Map 클릭
2. 클러스터 필터에서 새로 설치한 클러스터 선택
3. 서비스 간 연결이 표시되면 정상 (트래픽 발생 후 몇 분 소요)

로그 확인

1. 좌측 메뉴에서 Logs 클릭
2. 쿼리 입력:

   k8s.cluster.name:<cluster-name>

3. 파드 로그가 수집되는지 확인

자동 계측 활성화

설치 후 자동 계측을 활성화하려면 파드에 어노테이션을 추가합니다.

Namespace 전체 활성화

apiVersion: v1
kind: Namespace
metadata:
  name: my-app
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
    instrumentation.opentelemetry.io/inject-python: "true"
    instrumentation.opentelemetry.io/inject-nodejs: "true"

개별 Deployment 활성화

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-java-app
spec:
  template:
    metadata:
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"

지원 언어

추가 클러스터 연결

다른 클러스터를 추가로 연결하려면 동일한 설치 과정을 반복합니다:

# 두 번째 클러스터
./o11y-agent-install.sh \
  --cluster-context second-cluster \
  --host-lb-ip 192.168.254.246 \
  --cluster-name second-cluster \
  --environment prod

# 세 번째 클러스터
./o11y-agent-install.sh \
  --cluster-context third-cluster \
  --host-lb-ip 192.168.254.246 \
  --cluster-name third-cluster \
  --environment prod

모든 클러스터는 동일한 Host Gateway IP를 사용합니다.

문제 해결

Host로 연결 실패

증상: OTel Collector 로그에 연결 오류 표시

kubectl logs -n skuber-observability -l app.kubernetes.io/name=k8s-infra | grep -i error

해결 방법:

1. Host Gateway IP 확인:

   kubectl --context=<host-context> get svc otel-collector-gateway \
     -n skuber-observability -o wide

2. 네트워크 연결 테스트:

   kubectl run test --rm -it --image=busybox -- \
     wget -O- --timeout=5 http://<host-gateway-ip>:4317

3. 방화벽에서 4317, 4318 포트 허용 확인

APM Agent가 데이터를 수집하지 않음

증상: Service Map에 서비스가 표시되지 않음

해결 방법:

1. 커널 버전 확인:

   uname -r
   # 5.8 이상이어야 함

2. APM Agent 파드 로그 확인:

   kubectl logs -n skuber-observability -l app.kubernetes.io/name=skuber-apm-agent

3. 권한 확인 (privileged 모드 필요):

   kubectl describe daemonset skuber-apm-agent -n skuber-observability | grep -A5 "Security Context"

메트릭이 보이지 않음

증상: Infrastructure 화면에 데이터 없음

해결 방법:

1. kube-state-metrics 파드 상태 확인:

   kubectl get pods -n skuber-observability -l app.kubernetes.io/name=kube-state-metrics

2. OTel Collector 설정 확인:

   kubectl get configmap -n skuber-observability k8s-infra -o yaml

다음 단계

• 자동 계측 - 상세 자동 계측 가이드