Agent 클러스터

최종 수정: 2026. 4. 7.

Agent 클러스터 설치

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

개요

Agent Cluster에 설치되는 컴포넌트가 관측성 데이터(메트릭, 로그, 트레이스)를 수집하여 Host Cluster의 OTel Gateway로 전송합니다.

사전 조건: Host 클러스터 설치가 완료되어 있어야 합니다.
Host 설치 시 확인한 OTel Gateway IP가 필요합니다.

설치되는 컴포넌트

컴포넌트 타입 역할
OTel Collector Agent DaemonSet 노드별 호스트 메트릭, 컨테이너 로그, 트레이스 수집
OTel Collector Deployment Deployment 클러스터 레벨 메트릭, Kubernetes 이벤트 수집
APM Agent DaemonSet eBPF 기반 자동 서비스 감지 및 네트워크 메트릭 수집
Kube State Metrics Deployment Kubernetes 오브젝트 상태 메트릭 (Pod, Deployment 등)
OTel Operator Deployment Instrumentation CRD 관리 (자동 계측)

아키텍처

사전 요구사항

  • Host 클러스터 설치 완료 — OTel Gateway IP 확인
  • Kubernetes 1.24+ 클러스터
  • kubectl 및 helm v3.12+ 설치
  • cert-manager 설치 — OTel Operator가 cert-manager에 의존합니다. 차트에 미포함이므로 사전 설치 필수. 설치 가이드의 Step 5 참조
  • Linux 커널 5.8+ — eBPF APM Agent 요구사항
  • Host Cluster OTel Gateway 네트워크 접근 가능 (gRPC :4317, HTTP :4318)

설치

클러스터 이름 일관성: global.clusterName과 skuber-apm-agent...cluster_name은 동일한 값을 사용하세요. 다르면 Host UI에서 데이터가 분리되어 표시됩니다.

Helm 차트 설치

helm upgrade --install skuberplus-observability-agent \
  oci://registry.skuberplus.com/charts/skuberplus-observability-agent \
  --version <차트-버전> \
  --kube-context <agent-cluster-context> \
  --namespace skuber-observability \
  --create-namespace \
  --set global.clusterName=<클러스터-이름> \
  --set global.deploymentEnvironment=<환경> \
  --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=<클러스터-이름> \
  --set instrumentation.exporter.endpoint=http://<host-gateway-ip>:4317 \
  --wait --timeout 25m

--wait --timeout 25m은 cert-manager CRD 및 OTel Operator 초기화를 기다리기 위해 필요합니다.

필수 옵션

옵션 설명 예시
--version Helm 차트 버전 26.2.1
--kube-context Agent 클러스터의 kubectl 컨텍스트 my-agent-cluster
global.clusterName 클러스터 식별 이름 (Host UI에서 표시됨) production-cluster
global.deploymentEnvironment 배포 환경 dev, staging, prod
global.hostEndpointHttp Host OTel Gateway HTTP 엔드포인트 (.NET/Python 계측용) http://10.0.1.50:4318
skuber-otel-agent.otelCollectorEndpoint Host OTel Gateway gRPC 엔드포인트 10.0.1.50:4317
skuber-apm-agent.config.data.attributes.kubernetes.cluster_name APM Agent에 전달할 클러스터명 production-cluster
instrumentation.exporter.endpoint 자동 계측 OTLP gRPC 엔드포인트 http://10.0.1.50:4317

Host Gateway가 TLS를 사용하는 경우 아래 TLS 전송 설정을 참조하세요.

(선택) TLS 전송 설정

Host Cluster에서 TLS를 활성화한 경우, Agent도 TLS로 전송하도록 설정해야 합니다.

기존 설치 명령어에서 아래 옵션을 변경/추가합니다:

옵션 평문 (기본) TLS
global.otelInsecure true false
global.hostEndpointHttp http://<ip>:4318 https://<ip>:4318
instrumentation.exporter.endpoint http://<ip>:4317 https://<ip>:4317
skuber-otel-agent.otelInsecure (없음) false 추가
skuber-otel-agent.insecureSkipVerify (없음) true 추가 (self-signed용)

주의: http:// → https:// 변경을 빠뜨리면 연결이 실패합니다.

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

TLS 적용 설치 예시:

  oci://registry.skuberplus.com/charts/skuberplus-observability-agent \
  --version <차트-버전> \
  --kube-context <agent-cluster-context> \
  --namespace skuber-observability \
  --create-namespace \
  --set global.clusterName=<클러스터-이름> \                                                                                            --set global.deploymentEnvironment=<환경> \
  --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=<클러스터-이름> \
  --set instrumentation.exporter.endpoint=https://<host-gateway-ip>:4317 \
  --wait --timeout 25m

설치 확인

파드 상태

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

정상 설치 시:

NAME                                    READY   STATUS    RESTARTS   AGE
skuber-otel-agent-xxxxx                 1/1     Running   0          5m
skuber-otel-deployment-xxxxxxxxx-xxxxx  1/1     Running   0          5m
skuber-apm-agent-xxxxx                  1/1     Running   0          5m
skuber-ksm-xxxxxxxxx-xxxxx              1/1     Running   0          5m
skuber-otel-operator-xxxxxxxxx-xxxxx    1/1     Running   0          5m

DaemonSet(skuber-otel-agent, skuber-apm-agent)은 노드 수만큼 생성됩니다.

Host Gateway 연결 확인

kubectl --context <agent-context> -n skuber-observability \
  logs -l app.kubernetes.io/name=skuber-otel-agent --tail=20

정상이면 Everything is ready 또는 OTLP exporter 연결 성공 로그가 출력됩니다. connection refused 또는 context deadline exceeded가 보이면 Host Gateway 네트워크를 확인하세요.

자동 계측

OTel Operator 설치 시 Instrumentation CRD(skuber-instrumentation)가 자동 생성됩니다. 애플리케이션 Deployment에 annotation을 추가하면 트레이스/메트릭이 자동 수집됩니다.

언어 Annotation
Java instrumentation.opentelemetry.io/inject-java: "skuber-instrumentation"
.NET instrumentation.opentelemetry.io/inject-dotnet: "skuber-instrumentation"
Python instrumentation.opentelemetry.io/inject-python: "skuber-instrumentation"
Node.js instrumentation.opentelemetry.io/inject-nodejs: "skuber-instrumentation"
Go instrumentation.opentelemetry.io/inject-go: "skuber-instrumentation" 
                                                   > 자세한 설정 및 언어별 프로토콜 차이는 자동 계측 가이드를 참조하세요.

문제 해결

Host Gateway 연결 실패

Agent Cluster 내부에서 Host Gateway 접근 테스트

kubectl --context <agent-context> -n skuber-observability \
  run gw-test --rm -it --image=busybox -- nc -zv <host-gateway-ip> 4317
                                                                                                                               | 원인 | 해결 |

|------|------|
| 네트워크 불통 | 방화벽, SecurityGroup, VPC 피어링 확인 |
| Host Gateway 미기동 | Host 클러스터에서 OTel Gateway 파드 상태 확인 |
| IP/포트 오류 | skuber-otel-agent.otelCollectorEndpoint 값 재확인 |

APM Agent 데이터 미수집

원인 해결
커널 버전 미달 uname -r로 5.8+ 확인. 미달 시 apmAgent.enabled=false로 비활성화
권한 부족 APM Agent DaemonSet에 필요한 SecurityContext(SYS_PTRACE 등) 확인
서비스 미감지 APM Agent는 네트워크 트래픽이 있는 프로세스만 감지. 트래픽 유발 후 확인

cert-manager/Operator 오류 — cert-manager CRD가 준비되지 않으면 OTel Operator가 기동하지 않습니다. 사전 요구사항의 cert-manager 설치를 확인하세요.

파드가 Pending 상태인 경우 — kubectl describe pod로 이벤트 확인. DaemonSet은 모든 노드에 배포되므로 노드 리소스를 확인하세요.

다음 단계

Agent Cluster 설치가 완료되면:

  1. Host UI에서 데이터 수집 확인 — 서비스 맵에서 Agent Cluster의 데이터가 표시되는지 확인
  2. 자동 계측 적용 — 애플리케이션 Deployment에 annotation 추가
  3. 추가 클러스터 연결 — 다른 모니터링 대상 클러스터에도 동일하게 설치