Operator 설치

Monithub Operator는 고객 Kubernetes 클러스터 안에서 Monithub 수집 컴포넌트를 설치하고 관리합니다. 기본 설치는 Operator, OpenTelemetry Collector gateway, Flow Agent, MonithubAgent 리소스를 함께 구성해 서비스 맵과 네트워크 흐름 데이터를 Monithub로 보냅니다.

이 가이드는 처음 설치하는 사용자가 준비해야 할 값, 실행해야 할 명령, 설치 후 확인할 화면을 순서대로 설명합니다.

1. 값 준비

Monithub Connect에서 cluster ID, connect ID, token, OTLP endpoint, registry 인증 정보를 확인합니다.

2. 클러스터 설치

Secret과 values 파일을 만든 뒤 Helm chart로 Operator와 기본 Agent를 설치합니다.

3. 데이터 확인

Rollout, Agent condition, Monithub 서비스 맵을 순서대로 확인해 수집 상태를 검증합니다.

설치 전 준비

항목	필요 내용
Kubernetes 권한	CRD, ClusterRole, ServiceAccount, Deployment, DaemonSet을 생성할 수 있는 권한
로컬 도구	`kubectl`, Helm 3.8 이상, 설치 대상 클러스터 context
네트워크	클러스터에서 `registry.monithub.org`와 Monithub OTLP endpoint로 나가는 egress
Monithub 값	`clusterId`, `connect.id`, `connect.orgId`, `connect.tenantId`, Connect token
Registry 인증	Monithub가 발급한 registry pull username과 token

1. Monithub Connect 값 확인

Monithub에서 Kubernetes 연결을 만들면 설치에 필요한 값이 발급됩니다. 설치 전에 아래 값을 한곳에 모아 둡니다.

값	설명	예시
`clusterId`	Monithub에서 클러스터를 식별하는 이름입니다. 설치 후 바꾸면 기존 데이터와 새 데이터가 분리될 수 있습니다.	`customer-prod-a`
`connect.id`	Connect 설정과 telemetry를 연결하는 ID입니다.	`customer-connect-a`
`connect.orgId`	Monithub 조직 ID입니다.	`org_customer_a`
`connect.tenantId`	tenant routing에 사용할 ID입니다. 별도 값이 없으면 보통 `orgId`와 같은 값을 사용합니다.	`org_customer_a`
`endpoint.otlpHttp`	Collector가 데이터를 보낼 OTLP HTTP endpoint입니다.	`https://otel.monithub.org`
Connect token	Collector export 인증에 사용하는 token입니다.	`<MONITHUB_CONNECT_TOKEN>`
Registry pull 정보	Operator와 Flow Agent 이미지를 pull하기 위한 registry 인증 정보입니다.	`<MONITHUB_REGISTRY_PULL_USERNAME>`

2. 클러스터 context 확인

설치 명령을 실행하기 전에 현재 kubectl이 올바른 클러스터를 바라보는지 확인합니다.

kubectl config current-context
kubectl get nodes

운영 클러스터와 개발 클러스터를 함께 다룬다면 context 이름, namespace, clusterId가 서로 맞는지 한 번 더 확인합니다.

3. Namespace와 Secret 생성

Monithub Operator는 기본적으로 monithub-system namespace에 설치합니다. 민감한 값은 Helm values 파일에 직접 쓰지 않고 Kubernetes Secret으로 분리합니다.

kubectl create namespace monithub-system --dry-run=client -o yaml | kubectl apply -f -

kubectl -n monithub-system create secret generic monithub-auth \
  --from-literal=token='<MONITHUB_CONNECT_TOKEN>' \
  --dry-run=client -o yaml | kubectl apply -f -

kubectl -n monithub-system create secret docker-registry registry-credentials \
  --docker-server=registry.monithub.org \
  --docker-username='<MONITHUB_REGISTRY_PULL_USERNAME>' \
  --docker-password='<MONITHUB_REGISTRY_PULL_TOKEN>' \
  --dry-run=client -o yaml | kubectl apply -f -

생성 후 Secret 이름만 확인합니다. Secret 값을 출력할 필요는 없습니다.

kubectl -n monithub-system get secret monithub-auth registry-credentials

4. values 파일 작성

로컬에 monithub-values.yaml 파일을 만들고 Monithub에서 발급받은 값으로 채웁니다.

clusterId: customer-prod-a

connect:
  id: customer-connect-a
  orgId: org_customer_a
  tenantId: org_customer_a

endpoint:
  otlpHttp: https://otel.monithub.org

authSecret:
  name: monithub-auth
  key: token

imagePullSecrets:
  - name: registry-credentials

telemetryPreset: service-map-lite

telemetry preset 선택

preset	수집 범위	권장 상황
`service-map-lite`	Operator, Collector gateway, Flow Agent 중심의 서비스 맵 기본 수집	첫 설치, 비용과 리소스를 보수적으로 시작할 때
`kubernetes-basic`	`service-map-lite`에 host metrics, kubelet stats, k8s cluster 수집을 추가	클러스터 상태와 워크로드 리소스 신호까지 함께 보고 싶을 때

처음 설치할 때는 service-map-lite로 시작한 뒤, 데이터가 정상 유입되는 것을 확인하고 필요할 때 kubernetes-basic으로 확장하는 방식을 권장합니다.

5. Helm registry 로그인

Monithub chart는 OCI registry로 배포됩니다.

helm registry login registry.monithub.org

로그인에는 Monithub에서 발급받은 registry 계정을 사용합니다. 클러스터 내부 이미지 pull은 앞에서 만든 registry-credentials Secret이 담당합니다.

6. Operator 설치

아래 명령은 v0.1.2 chart를 기준으로 Operator를 설치하거나 기존 설치를 업데이트합니다.

helm upgrade --install monithub-operator oci://registry.monithub.org/monithub/charts/monithub-operator \
  -n monithub-system \
  --version 0.1.2 \
  -f monithub-values.yaml

설치가 시작되면 Helm release와 Kubernetes 리소스를 확인합니다.

helm -n monithub-system status monithub-operator
kubectl -n monithub-system get deploy,ds,svc,cm

7. 설치 상태 확인

먼저 Operator와 Collector, Flow Agent가 정상적으로 rollout되는지 확인합니다.

kubectl -n monithub-system rollout status deploy/monithub-operator
kubectl -n monithub-system rollout status deploy/monithub-collector
kubectl -n monithub-system rollout status daemonset/monithub-flow-agent

그다음 MonithubAgent 상태를 확인합니다.

kubectl -n monithub-system get monithubagent monithub

kubectl -n monithub-system get monithubagent monithub \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\n"}{end}'

주요 condition은 아래처럼 읽습니다.

condition	정상 상태	의미
`CollectorAvailable`	`True`	Monithub Collector gateway가 실행 중입니다.
`AgentAvailable`	`True`	Flow Agent DaemonSet이 사용 가능한 노드에 배포되었습니다.
`EBPFSupported`	`True` 또는 `Unknown`	eBPF 기반 네트워크 수집 상태입니다. 설치 직후에는 metrics scrape 전까지 `Unknown`일 수 있습니다.
`DataExporting`	`True` 또는 `Unknown`	Monithub로 데이터 export가 관찰되었거나, 트래픽을 기다리는 상태입니다.
`TelemetryGuardrails`	`True`	고비용 telemetry 옵션이 보호 정책에 맞게 적용되었습니다.

8. Monithub 화면에서 확인

클러스터 리소스가 Ready 상태가 되면 Monithub에서 아래 순서로 확인합니다.

Connect 화면에서 해당 Kubernetes 연결이 활성 상태인지 확인합니다.
Service Map에서 clusterId에 해당하는 노드와 서비스가 나타나는지 확인합니다.
대시보드에서 최근 메트릭, 로그, 트레이스 또는 network edge 데이터가 들어오는지 확인합니다.
데이터가 보이지 않으면 설치한 clusterId, connect.id, orgId, OTLP endpoint가 values 파일과 Connect 화면에서 같은지 비교합니다.

첫 데이터가 보이기까지는 클러스터 트래픽과 수집 주기에 따라 몇 분이 걸릴 수 있습니다.

자주 바꾸는 설정

namespace 수집 범위 제한

특정 namespace만 네트워크 topology에 포함하려면 topology.network.includeNamespaces를 사용합니다.

topology:
  network:
    includeNamespaces:
      - default
      - payments

특정 namespace를 제외하려면 excludeNamespaces를 사용합니다. 기본값은 kube-system, monithub-system을 제외합니다.

topology:
  network:
    excludeNamespaces:
      - kube-system
      - monithub-system
      - monitoring

Kubernetes 기본 telemetry 켜기

노드, kubelet, cluster 상태를 함께 보고 싶다면 preset을 바꿉니다.

telemetryPreset: kubernetes-basic

적용은 같은 Helm upgrade 명령을 다시 실행하면 됩니다.

helm upgrade monithub-operator oci://registry.monithub.org/monithub/charts/monithub-operator \
  -n monithub-system \
  --version 0.1.2 \
  -f monithub-values.yaml

application trace 수집 켜기

애플리케이션 HTTP 또는 gRPC trace를 eBPF 기반으로 수집하려면 application topology를 명시적으로 켭니다.

topology:
  application:
    enabled: true
    provider: obi
    openPorts: 80,443,3000,5000,8000-8999
    traceSampleRate: 0.01

처음부터 모든 옵션을 켜기보다, 서비스 맵 기본 수집이 안정적으로 동작하는 것을 확인한 뒤 단계적으로 확장하는 편이 운영 리스크가 낮습니다.

업데이트와 롤백

values 파일을 수정하거나 새 chart 버전을 적용할 때는 같은 release 이름으로 upgrade합니다.

helm upgrade monithub-operator oci://registry.monithub.org/monithub/charts/monithub-operator \
  -n monithub-system \
  --version 0.1.2 \
  -f monithub-values.yaml

이전 release로 되돌릴 때는 history를 확인한 뒤 원하는 revision으로 rollback합니다.

helm -n monithub-system history monithub-operator
helm -n monithub-system rollback monithub-operator 1

CRD schema가 바뀌는 릴리즈는 Helm upgrade 전에 CRD를 먼저 적용해야 합니다.

helm show crds oci://registry.monithub.org/monithub/charts/monithub-operator \
  --version 0.1.2 | kubectl apply --server-side -f -

제거

Operator를 제거할 때는 Helm release를 먼저 삭제합니다.

helm -n monithub-system uninstall monithub-operator

더 이상 같은 클러스터에서 Monithub Operator를 사용하지 않는다면 Secret과 namespace도 정리할 수 있습니다.

kubectl -n monithub-system delete secret monithub-auth registry-credentials
kubectl delete namespace monithub-system

CRD는 다른 MonithubAgent 또는 MonithubInstrumentationPolicy 리소스가 없는지 확인한 뒤 삭제합니다.

kubectl get monithubagent --all-namespaces
kubectl get monithubinstrumentationpolicy --all-namespaces
kubectl delete crd monithubagents.monithub.io monithubinstrumentationpolicies.monithub.io

Troubleshooting

증상	확인할 것	조치
`ImagePullBackOff`	`registry-credentials` Secret 이름과 registry 계정	Secret을 다시 만들고 Helm values의 `imagePullSecrets`를 확인합니다.
`MonithubAgent`가 생성되지 않음	Helm values의 `monithubAgent.create` 값, CRD 설치 여부	`helm status`, `kubectl get crd monithubagents.monithub.io`를 확인합니다.
`InvalidSpec` condition	`clusterId`, `endpoint.otlpHttp` 또는 `endpoint.otlpGrpc` 값	values 파일의 필수 값을 채운 뒤 Helm upgrade를 다시 실행합니다.
Collector는 Ready지만 데이터가 없음	Connect token, OTLP endpoint, egress 정책	`monithub-auth` Secret과 방화벽, proxy, endpoint 오타를 확인합니다.
Flow Agent DaemonSet이 일부 노드에서 Ready가 아님	노드 Ready 상태, 커널/eBPF 지원, taint	`kubectl get nodes`, Agent pod event, `EBPFSupported` condition을 확인합니다.
`DataExporting`이 `Unknown`	실제 네트워크 트래픽 또는 metrics scrape 대기	서비스 요청을 발생시키고 몇 분 뒤 `MonithubAgent` condition을 다시 확인합니다.
Kubernetes telemetry collector가 없음	`telemetryPreset` 값	기본값 `service-map-lite`에서는 host/cluster collector가 생성되지 않습니다.

진단 로그는 아래 순서로 확인합니다.

kubectl -n monithub-system logs deploy/monithub-operator --tail=100
kubectl -n monithub-system logs deploy/monithub-collector --tail=100
kubectl -n monithub-system logs daemonset/monithub-flow-agent --tail=100
kubectl -n monithub-system describe monithubagent monithub

다음 단계

Connect와 Gateway에서 연결 생성 화면을 확인합니다.
서비스 맵과 트레이스에서 수집된 데이터를 확인합니다.
대시보드에서 운영 지표를 해석하는 방법을 확인합니다.