Skip to content
Monithub DocsMonithub Docs

Kubernetes 연결

전체 문서 PDF

Kubernetes 연결은 클러스터의 각 노드에 OpenTelemetry Collector를 배치해 노드, Pod, 컨테이너 메트릭을 Monithub로 보냅니다. Connect에서 생성하는 기본 설치 방식은 otel-host DaemonSet입니다.

시작하기 전에

Section titled “시작하기 전에”

다음 조건을 확인합니다.

  • 설치할 클러스터를 가리키는 kubectl context가 준비되어 있어야 합니다.
  • 클러스터에서 https://otel.monithub.org로 HTTPS 통신할 수 있어야 합니다.
  • Namespace, Secret, ServiceAccount, ClusterRole, ClusterRoleBinding, ConfigMap, DaemonSet을 만들 수 있는 권한이 필요합니다.
  • 조직 토큰이 포함된 manifest를 Git 저장소나 공개 위치에 저장하지 않습니다.

권한이 없다면 생성된 manifest를 클러스터 관리자에게 안전한 경로로 전달하고, 필요한 RBAC 범위를 함께 검토합니다.

적용할 터미널에서 현재 context가 대상 클러스터인지 먼저 확인합니다.

Terminal window
kubectl config current-context
kubectl get nodes

1. Kubernetes 설정 계획 만들기

Section titled “1. Kubernetes 설정 계획 만들기”
  1. Connect → 카탈로그를 엽니다.
  2. 설치 위치에서 Kubernetes를 선택합니다.
  3. 카탈로그에서 Kubernetes를 선택합니다.
  4. 설정 계획의 Kubernetes 카드를 선택합니다.
  5. 서비스 또는 소스 이름에 클러스터를 구분할 이름을 입력합니다. 예: prod-cluster-a.
  6. 환경 이름에 prod, staging과 같은 환경을 입력합니다.
  7. 연결 준비를 누릅니다.

같은 클러스터를 여러 이름으로 중복 연결하지 않도록 기존 연결 목록을 먼저 확인합니다.

2. 생성된 manifest 검토하기

Section titled “2. 생성된 manifest 검토하기”

설정 계획은 monithub-kubernetes-otel-host.yaml manifest를 생성합니다. 적용 전에 다음 리소스를 검토합니다.

리소스 역할
Namespace Monithub 수집 리소스를 분리합니다.
Secret 조직 토큰과 조직·사용자·Connect 식별자를 보관합니다.
ServiceAccount와 RBAC 노드, Pod, kubelet 통계를 읽을 권한을 부여합니다.
ConfigMap Collector receiver, processor, exporter 설정을 보관합니다.
DaemonSet 각 노드에서 otel-host Collector를 실행합니다.

기본 RBAC는 수집에 필요한 조회 권한을 대상으로 합니다. 조직 보안 정책에 따라 ClusterRole과 host 접근을 검토한 뒤 적용합니다.

3. 클러스터에 적용하기

Section titled “3. 클러스터에 적용하기”

설정 계획의 manifest를 파일로 저장한 뒤, 현재 context가 대상 클러스터인지 다시 확인하고 화면에 표시된 명령을 실행합니다.

Terminal window
kubectl config current-context
kubectl get nodes
kubectl apply -f ./monithub-kubernetes-otel-host.yaml
kubectl -n monithub rollout status daemonset/monithub-otel-host
kubectl -n monithub logs daemonset/monithub-otel-host --tail=50

추가로 Pod 배치 상태를 확인하려면 다음 명령을 사용합니다.

Terminal window
kubectl -n monithub get pods -o wide

모든 대상 노드의 Pod가 Running이고 DaemonSet rollout이 완료되어야 합니다. 일부 노드에 Pod가 없다면 node selector, taint, 리소스 부족, 이미지 pull, 네트워크 정책을 확인합니다.

4. 수집 범위 확인하기

Section titled “4. 수집 범위 확인하기”

기본 DaemonSet은 다음 데이터를 자동 수집합니다.

  • kubelet 통계 기반의 노드, Pod, 컨테이너 메트릭
  • 각 노드의 CPU, memory, disk, filesystem, network, process 메트릭

manifest에는 OTLP receiver도 포함되어 있지만, 이 기본 설치만으로 워크로드용 고정 Service나 애플리케이션 전송 경로가 만들어지지는 않습니다. 따라서 애플리케이션 트레이스·로그를 자동 수집한다고 가정하면 안 됩니다. 워크로드 계측과 Collector gateway를 함께 관리하려면 Monithub K8S Operator 설치 절차를 사용합니다.

5. Connect에서 연결 확인하기

Section titled “5. Connect에서 연결 확인하기”
  1. DaemonSet rollout과 로그를 확인한 뒤 Connect 화면으로 돌아갑니다.
  2. 연결 시작을 누릅니다.
  3. 클러스터에서 실제 워크로드 트래픽을 발생시킵니다.
  4. 데이터 수집 확인에서 신호별 결과를 확인합니다.
  5. 연결 목록에서 연결 상태, 데이터 수집 상태, 마지막 수집 시각을 확인합니다.

첫 수집 결과가 나타나기까지 Collector 전송 주기와 워크로드 트래픽에 따라 시간이 걸릴 수 있습니다. 연결됨인데 데이터가 없다면 Collector Pod 로그에서 인증 오류와 exporter 오류를 먼저 확인합니다.

Operator 설치와의 차이

Section titled “Operator 설치와의 차이”

이 문서는 Connect 화면이 생성하는 기본 otel-host DaemonSet 설치 절차입니다. Monithub K8S Operator를 사용해 수집 구성과 Flow Agent를 관리하려면 Monithub K8S Operator 설치 가이드를 따릅니다.

두 방식을 같은 클러스터에 중복 적용하기 전에 수집 범위와 Connect ID가 겹치지 않는지 확인합니다.

연결을 삭제할 때

Section titled “연결을 삭제할 때”

Connect의 연결 삭제는 Monithub에 저장된 연결과 설정 계획만 삭제합니다. 고객 클러스터에 이미 적용한 Kubernetes 리소스는 자동으로 제거되지 않습니다.

먼저 이 Connect가 만든 리소스만 있는 전용 Namespace인지 확인합니다. Secret 값은 출력하지 않습니다.

Terminal window
kubectl -n monithub get daemonset,configmap,serviceaccount,secret
kubectl get clusterrole,clusterrolebinding monithub-otel-host

출력된 리소스가 모두 이 Connect를 위해 만든 것이고 monithub Namespace가 전용인 경우에만 다음 명령으로 제거합니다.

Terminal window
kubectl delete -f ./monithub-kubernetes-otel-host.yaml