2.2. 설치 — Kubernetes
OPENMARU Observability를 Kubernetes 클러스터에 설치하는 방법을 안내합니다.
개요
OPENMARU Observability는 Helm 차트를 사용하여 Kubernetes 클러스터에 설치합니다. 하나의 Helm 차트 로 서버, UI, 데이터 저장소, 에이전트 등 모든 구성 요소가 함께 배포됩니다.
설치가 완료되면 노드 에이전트(Node Agent)가 각 노드(Node)에서 메트릭(Metric), 로그(Log), 추적(Trace), 프로파일링(Profiling) 데이터를 자동으로 수집하기 시작합니다. 애플리케이션(Application) 코드를 수정하거나 별도 SDK를 설치할 필요가 없습니다.
COP로 설치 시 자동 구성: OPENMARU COP(Container Orchestration Platform) 로 플랫폼을 구축하면 OPENMARU Observability와 필요한 의존 구성 요소(스토리지 프로비저너, cert-manager, 인그레스, SSO, OTel Operator, APM 서버 등)가 자동으로 설치·구성됩니다. 이 경우 이 장의 수동 Helm 설치 절차는 필요하지 않습니다. 이 장의 절차는 이미 운영 중인 Kubernetes 클러스터에 OPENMARU Observability만 별도로 추가할 때 사용합니다.
비-Kubernetes 설치: 이 장은 Kubernetes 클러스터에 Helm 차트로 설치하는 방법을 다룹니다. Kubernetes 없이 일반 Linux 호스트에 Docker Compose 로 서버 스택을 설치·운영하는 방식(인터넷 차단 air-gap·오프라인 설치 포함)도 지원하며, 이는 별도의 설치·운영 가이드로 제공됩니다. 비-Kubernetes 설치가 필요하면 제품 담당자에게 별도로 문의하세요.
설치되는 구성 요소
| 구성 요소 | 역할 | 배포 방식 |
|---|---|---|
| 서버 | 수집된 데이터를 처리하고 UI에 제공합니다 | StatefulSet (기본 1 복제본) |
| UI | 브라우저를 통해 접근하는 웹 인터페이스입니다 | Deployment |
| 클러스터 에이전트(Cluster Agent) | Kubernetes 클러스터 전반의 메트릭(Metric)과 리소스 메타데이터(클러스터 상태)를 수집합니다 | Deployment |
| 노드 에이전트(Node Agent) | 각 노드(Node)에서 시스템 메트릭, 로그, 추적, 프로파일 데이터를 수집합니다 | DaemonSet (노드당 1개) |
| ClickHouse | 로그, 추적, 프로파일링 데이터를 저장합니다 | Deployment |
| VictoriaMetrics | 메트릭 데이터를 저장하는 시계열 데이터베이스입니다 | Deployment |
| PostgreSQL | 설정 및 사용자 정보를 저장합니다 | Deployment |
| kube-state-metrics | Kubernetes 리소스 상태를 메트릭으로 노출합니다 | Deployment |
| OTel Collector | OpenTelemetry 데이터를 수신하는 수집기입니다 | Deployment |
시스템 요구사항
Kubernetes 클러스터
| 항목 | 요구사항 |
|---|---|
| Kubernetes 버전 | 1.23 이상 |
| Helm 버전 | 3.x 이상 |
| 스토리지 클래스 | PersistentVolume을 프로비저닝할 수 있는 스토리지 클래스 필요 |
노드(Node) 요구사항
노드 에이전트는 eBPF를 사용하여 애플리케이션 코드 수정 없이 자동으로 추적과 메트릭을 수집합니다. 이를 위해 아래 요건을 충족해야 합니다.
| 항목 | 요구사항 |
|---|---|
| 운영체제 | RHEL 8.2 이상 (또는 호환 리눅스 배포판) |
| 커널 버전 | 4.16 이상 (eBPF 지원 필수) |
| CPU 아키텍처 | x86_64 (amd64) 또는 arm64 (aarch64) |
| 접근 권한 | 호스트 PID, cgroup, tracefs, debugfs 접근 필요 (privileged 모드로 실행) |
참고: eBPF는 Linux 커널에서 코드를 안전하게 실행할 수 있는 기술로, 노드 에이전트가 이를 활용하여 네트워크 요청, 시스템 호출 등을 자동으로 관측합니다. 커널 4.16 미만의 환경에서는 노드 에이전트가 정상적으로 동작하지 않을 수 있습니다.
권장 리소스
아래는 각 구성 요소의 기본 리소스 요청값입니다. 클러스터 규모에 따라 조정이 필요할 수 있습니다.
| 구성 요소 | CPU (요청) | 메모리 (요청) | CPU (상한) | 메모리 (상한) | 스토리지 |
|---|---|---|---|---|---|
| 서버 (x1 복제본) | 500m | 1Gi | - | - | 50Gi |
| UI | 100m | 512Mi | - | - | - |
| 클러스터 에이전트 | 100m | 1Gi | - | - | - |
| 노드 에이전트 (DaemonSet, 노드당) | 500m | 500Mi | - | 4Gi | - |
| ClickHouse | 1,000m | 2Gi | - | - | 300Gi |
| VictoriaMetrics | - | - | - | - | 20Gi |
| PostgreSQL | - | 512Mi | - | 512Mi | 5Gi |
참고: VictoriaMetrics는 리소스 요청/상한이 설정돼 있지 않으므로, 대규모 클러스터에서는 커스텀
values.yaml로 지정하세요. 메트릭 기본 보존 기간은 3일(--retentionPeriod=3d)이며values.yaml로 변경할 수 없어, 늘리려면 VictoriaMetrics 배포 템플릿의 인자를 직접 수정해야 합니다.
주의: 위 값은 기본 설정입니다. 클러스터 규모와 데이터 보존 기간에 따라 ClickHouse와 VictoriaMetrics의 스토리지를 충분히 확보하세요. 로그와 추적 데이터가 많을수록 더 많은 스토리지가 필요합니다.
스토리지 용량 사이징 (대/중/소)
PersistentVolume(PVC) 용량은 데이터 종류별로 증가 요인이 다릅니다. 각 저장소의 저장 대상과 용량을 좌우하는 주 변수는 다음과 같습니다.
| 저장소 | 저 장 대상 | 용량 증가 요인 | 기본 PV |
|---|---|---|---|
| ClickHouse | 분산추적(트레이스)·로그 | 트래픽량(초당 요청·스팬·로그 수) — 특히 로그 볼륨이 지배적. ClickHouse 자체 진단 로그(system.*_log)는 차트 기본 설정으로 비활성/7일 TTL 관리됨 — 구버전 차트는 진단 로그가 무한 축적되므로 최신 차트 설정 적용 필요 | 300Gi |
| VictoriaMetrics | 메트릭 시계열 | 카디널리티(서비스·컨테이너 수) × 보존 기간(기본 3일). 가득 차면 메트릭 수집 전체가 중단되므로 여유 확보 필수 | 20Gi |
| 서버 | 설정·상태 + 메트릭 조회 캐시 | 조회 대상 메트릭 수 | 50Gi |
| PostgreSQL | 설정 DB(사용자·규칙 등) + 알림 이력 + 사용자 수 추정 통계 | 알림 발생량·네임스페이스 수 × 보존 기간(알림·인시던트 이력은 기본 62일 보존으로 상한 수렴) | 5Gi |
용량을 주로 좌우하는 것은 ClickHouse(트래픽) 와 VictoriaMetrics(카디널리티) 입니다. 아래는 클러스터 규모별 시작 권장치입니다. 실제 사용량을 모니터링하며 조정하세요.
| 규모 | 대상 환경 | ClickHouse | VictoriaMetrics | 서버 | PostgreSQL |
|---|---|---|---|---|---|
| 소(小) | 개발·PoC, 노드 5대 이하·서비스 수십 개 | 300Gi(기본) — 로그 적은 개발 환경은 축소 가능 | 20Gi(기본) | 20~50Gi | 5Gi(기본) |
| 중(中) | 운영, 노드 10~30대·중간 트래픽 | 500~600Gi | 50~100Gi | 50Gi | 10Gi |
| 대(大) | 대규모, 노드 30대 이상·고트래픽 | 1Ti 이상 | 200Gi 이상 | 100Gi 이상 | 20Gi 이상 |
참고: 위 값은 제품 기본 설정과 일반적인 관측성 사이징 기준으로 도출한 시작점이며, 실측 벤치마크가 아닙니다. 트래픽·서비스 수·보존 기간에 따라 달라지므로 초기에는 넉넉히 잡고 실제 사용량을 보며 조정하는 것을 권장합니다.
참고: 추적·로그(ClickHouse) 데이터는 트래픽에 따라 급변합니다. 디스크 사용률이 임계치(기본 70%)를 넘으면 가장 오래된 데이터(하루 단위)부터 정리하여 지정한 디스크 용량 안에서 최대한 많은 이력을 유지합니다. 따라서 보존 기간을 고정하기보다 디스크 용량을 예산에 맞춰 정하는 방식이 안전합니다.
설치 전 준비
스토리지 클래스 확인
OPENMARU Observability는 데이터 저장을 위해 PersistentVolume을 사용합니다. Helm 차트의 기본 스토리지 클래스는 nfs-client입니다.
클러스터에서 사용 가능한 스토리지 클래스를 확인합니다.
kubectl get storageclass
사용할 스토리지 클래스 이름을 확인해 두세요. 기본값(nfs-client)과 다른 경우 설치 시 별도로 지정해야 합니다.
이미지 레지스트리 접근 확인
모든 컨테이너 이미지는 registry.openmaru.io에서 제공됩니다. 클러스터에서 해당 레지스트리에 접근할 수 있는지 확인하세요.
프라이빗 레지스트리를 사용하는 경우 imagePullSecrets를 설정해야 합니다. 해당 설정은 아래 주요 설정 항목 섹션을 참고하세요.
참고: 인터넷이 차단된 환경(에어갭 환경)에서는 이미지를 내부 레지스트리로 미리 옮겨두어야 합니다. 자세한 내용은 OPENMARU 기술 지원팀에 문의하세요.
OPENMARU Observability 설치
1단계: Helm 차트 저장소 추가
helm repo add openmaru-observ http://registry.[domain].[tld]:8181/
helm repo update openmaru-observ
중요:
[domain].[tld]부분은 제공받은 실제 레지스트리 도메인으로 변경하세요.
2단계: 설치
기본값으로 설치
helm install -n openmaru-observ --create-namespace \
openmaru-observ openmaru-observ/openmaru-observ
스토리지 클래스를 지정하여 설치
클러스터의 스토리지 클래스가 nfs-client가 아닌 경우 --set 옵션으로 변경합니다.
helm install -n openmaru-observ --create-namespace \
--set openmaruObservGlobal.storage.storageClassName=<스토리지 클래스 이름> \
openmaru-observ openmaru-observ/openmaru-observ
Ingress 호스트를 지정하여 설치
외부에서 접근할 도메인을 함께 설정하는 경우:
helm install -n openmaru-observ --create-namespace \
--set openmaruObservServer.ingress.hosts[0].host=observ.example.com \
openmaru-observ openmaru-observ/openmaru-observ
커스텀 values.yaml 파일을 사용하여 설치
여러 항목을 변경해야 하는 경우 values.yaml 파일을 작성하여 사용합니다.
helm install -n openmaru-observ --create-namespace \
-f my-values.yaml \
openmaru-observ openmaru-observ/openmaru-observ
3단계: 설치 진행 확인
모든 Pod가 Running 상태가 될 때까지 기다립니다.
kubectl -n openmaru-observ get pods -w
정상 설치 시 아래와 유사한 출력을 확인할 수 있습니다.
NAME READY STATUS RESTARTS AGE
openmaru-observ-server-0 1/1 Running 0 3m
openmaru-observ-server-1 1/1 Running 0 3m
openmaru-observ-ui-xxxxxxxxxx-xxxxx 1/1 Running 0 3m
openmaru-cluster-agent-xxxxxxxxxx-xxxxx 1/1 Running 0 3m
openmaru-node-agent-xxxxx 1/1 Running 0 3m
openmaru-observ-clickhouse-xxxxxxxxxx-xxxxx 1/1 Running 0 3m
openmaru-observ-victoria-metrics-xxxxxxxxxx-xxxxx 1/1 Running 0 3m
openmaru-observ-postgres-xxxxxxxxxx-xxxxx 1/1 Running 0 3m
openmaru-observ-kube-state-metrics-xxxxx-xxxxx 1/1 Running 0 3m
openmaru-observ-otel-collector-xxxxxxxxxx-xxxxx 1/1 Running 0 3m
모든 Pod의 STATUS가 Running이고 READY가 정상이면 설치가 완료된 것입니다.
참고: 서버는 최초 기동 시 데이터 초기화에 최대 5분까지 소요될 수 있습니다.
주요 설정 항목
환경에 따라 아래 항목을 values.yaml에서 조정할 수 있습니다.
공통 설정
| 항목 | 기본값 | 설명 |
|---|---|---|
openmaruObservGlobal.storage.storageClassName | nfs-client | 모든 구성 요소에서 사용하는 스토리지 클래스 |
서버 설정
| 항목 | 기본값 | 설명 |
|---|---|---|
openmaruObservServer.replicas | 1 | 서버 복제본 수 |
openmaruObservServer.resources.requests.cpu | 500m | 서버 CPU 요청량 |
openmaruObservServer.resources.requests.memory | 1Gi | 서버 메모리 요청량 |
openmaruObservServer.persistentVolume.size | 50Gi | 서버 데이터 스토리지 크기 |
접근 설정 (Ingress)
| 항목 | 기본값 | 설명 |
|---|---|---|
openmaruObservServer.ingress.enabled | true | Ingress 활성화 여부 |
openmaruObservServer.ingress.className | (없음) | Ingress 클래스 이름 |
openmaruObservServer.ingress.hosts | (없음) | 접근할 호스트명 목록 |
openmaruObservServer.ingress.tls | (없음) | TLS 인증서 설정 |
팁: Ingress를 사용하는 경우
hosts에 접근할 도메인 이름을 설정하세요. TLS를 함께 설정하면 HTTPS로 접근할 수 있습니다.
Ingress 대신 OpenShift Route를 사용하는 경우:
| 항목 | 기본값 | 설명 |
|---|---|---|
openmaruObservServer.route.enabled | false | OpenShift Route 활성화 |
openmaruObservServer.ingress.enabled | false로 변경 | Ingress 비활성화 |
데이터 저장소 설정
| 항목 | 기본값 | 설명 |
|---|---|---|
openmaruObservClickhouse.persistentVolume.size | 300Gi | ClickHouse 스토리지 크기 |
openmaruObservClickhouse.resources.requests.cpu | 1000m | ClickHouse CPU 요청량 |
openmaruObservClickhouse.resources.requests.memory | 2Gi | ClickHouse 메모리 요청량 |
openmaruObservPostgres.persistentVolume.size | 5Gi | PostgreSQL 스토리지 크기 |
openmaruObservVictoriaMetrics.storage.size | 20Gi | VictoriaMetrics 스토리지 크기 |
스토리지 용량 산정: 위 PVC 용량 기본값은 동작을 위한 최소값입니다. 실제 필요한 용량은 모니터링 대상 규모(클러스터·노드·애플리케이션 수), 로그·추적 수집량, 데이터 보존 기간에 따라 크게 달라지므로, 운영 환경에서는 아래 기준으로 사이징하세요.
각 저장소는 저장 대상이 다르며, 용량이 늘어나는 요인도 다릅니다.
| 저장소 | 저장 대상 | 용량 증가 요인 |
|---|---|---|
| VictoriaMetrics | 메트릭(시계열) | 모니터링 대상(클러스터·노드·애플리케이션·컨테이너) 수에 비례하는 시계열 카디널리티 × 보존 기간(메트릭 기본 3일) |
| ClickHouse | 로그·추적·프로파일 | 로그·추적 수집량 × 보존 기간 — 세 저장소 중 가장 크고 변동이 큽니다. 로그가 많은 환경일수록 빠르게 증가합니다 |
| 서버 데이터(캐시) | 메트릭 쿼리 캐시 | 메트릭 카디널리티 × 캐시 보존 기간에 비례 |
| PostgreSQL | 설정·사용자 정보 + 알림 이력·사용자 수 추정 통계 | 알림·인시던트 이력은 기본 62일 보존(메트릭 캐시 TTL 연동)으로 상한 수렴 — 보존 기간 내 알림 발생량에 비례. 볼륨이 가득 차면 DB 전체가 중단되므로 여유를 확보하세요 (기본 5Gi) |
사이징 기준:
- 클러스터·애플리케이션이 많을수록 메트릭 시계열(카디널리티)이 늘어 VictoriaMetrics와 서버 캐시 용량이 커집니다.
- 로그·추적 양이 많을수록 ClickHouse 용량이 가장 크게 늘어납니다. 로그량이 많은 서비스가 있으면
openmaruObservClickhouse.persistentVolume.size를 넉넉히 잡으세요. - 보존 기간이 길수록 모든 저장소 용량이 비례해 증가합니다.
- 처음에는 기본값보다 크게 잡고, 실제 사용량 추이를 모니터링하며 조정하는 것을 권장합니다. 용량이 부족하면 PVC 크기를 확장하거나(스토리지 클래스가 볼륨 확장을 지원하는 경우), 보존 기간을 줄여 조절할 수 있습니다.
UI 설정
| 항목 | 기본값 | 설명 |
|---|---|---|
openmaruObservUi.config.use_cogentai | false | CogentAI(AI 분석 기능) 활성화 여부 |
openmaruObservUi.config.cop_console_url | (없음) | COP 콘솔 URL (연동 시 설정) |
openmaruObservUi.config.readtimeout_ms | 300000 | 서버 요청 읽기 타임아웃(ms, 기본 5분) — 대용량 쿼리 시 조정 |
openmaruObservUi.config.writetimeout_ms | 300000 | 서버 요청 쓰기 타임아웃(ms, 기본 5분) |
클러스터 에이전트 설정
| 항목 | 기본값 | 설명 |
|---|---|---|
openmaruClusterAgent.config.api_key | (없음) | 서버 인증 API 키 |
openmaruClusterAgent.config.metrics.scrape.interval | 15s | 메트릭 수집 주기 |
openmaruClusterAgent.config.profiles.scrape.interval | 1m | 프로파일 수집 주기 |
openmaruClusterAgent.config.config.update.interval | 60s | 설정 동기화 주기 |
openmaruClusterAgent.resources.requests.cpu | 100m | CPU 요청량 |
openmaruClusterAgent.resources.requests.memory | 1Gi | 메모리 요청량 |
노드 에이전트 설정
| 항목 | 기본값 | 설명 |
|---|---|---|
openmaruObservNodeAgent.resources.requests.cpu | 500m | 노드당 CPU 요청량 |
openmaruObservNodeAgent.resources.requests.memory | 500Mi | 노드당 메모리 요청량 |
openmaruObservNodeAgent.resources.limits.memory | 4Gi | 노드당 메모리 상한 (CPU 상한은 기본 미설정) |
openmaruObservNodeAgent.tolerations | 모든 노드 허용 | 에이전트가 배포될 노드(Node) 범위 |
참고: 노드 에이전트는 DaemonSet으로 배포되어 모든 노드(Node)에 하나씩 실행됩니다. 기본 설정은 taint가 있는 노드를 포함한 모든 노드에 배포됩니다. 특정 노드를 제외하려면
tolerations이나affinity를 조정하세요.
노드 에이전트 런타임 옵션
노드 에이전트의 동작은 아래 옵션으로 세밀하게 조정할 수 있습니다. Helm 설치 시에는 openmaruObservNodeAgent.<Helm 값>으로, Docker Compose·systemd 등 Helm 외 설치 시에는 환경변수( 또는 동일 이름의 커맨드라인 플래그)로 지정합니다.
로그 볼륨 제어 — 폭주하는 컨테이너 로그가 에이전트 CPU와 저장소를 잠식하는 것을 방어합니다(v1.0.3에서 추가). 신규 설치는 기본적으로 활성화되어 폭주 컨테이너 로그가 상한선에서 캡됩니다. 전량 전송이 필요하면 해당 값을 0으로 끕니다.
| Helm 값 / 환경변수 | 기본값 | 설명 |
|---|---|---|
logMessagesPerContainerPerSec / LOG_MESSAGES_PER_CONTAINER_PER_SEC | 100 | 컨테이너별 INFO/DEBUG/미분류 로그 전송 속도 상한(개/초). 0=비활성 |
(Helm 미노출) / LOG_MESSAGES_BURST | 0 | 위 속도 상한의 버스트 허용량. 0=상한×2 |
logDedupFirstNPerSec / LOG_DEDUP_FIRST_N_PER_SEC | 5 | WARN 이상 반복 로그를 (레벨,패턴)별 초당 첫 N건만 통과. 0=비활성 |
logDedupEveryNth / LOG_DEDUP_EVERY_NTH | 100 | 첫 N건 이후에는 M건마다 1건씩만 전송 |
(Helm 미노출) / LOG_PATTERNS_PER_CONTAINER | 256 | 컨테이너·레벨별 최대 고유 로그 패턴 수 |
(Helm 미노출) / DISABLE_LOG_PARSING | false | 컨테이너 로그 파싱 전체 비활성화 |
참고: 속도 상한·중복 제거로 버려진 로그 건수는
container_log_messages_dropped_total메트릭으로 노출되어, 얼마나 캡됐는지 확인할 수 있습니다(레벨별 카운트는 유지됨).
TLS 계측 제외(denylist) — Go/OpenSSL TLS uprobe 계측 시 전체 심볼 테이블 로드로 메모리가 폭증하는 특정 바이너리를 계측 대상에서 제외합니다.
| Helm 값 / 환경변수 | 기본값 | 설명 |
|---|---|---|
tlsInstrumentDenylist / TLS_INSTRUMENT_DENYLIST | argocd,argocd-dex,karmada-controller-manager,karmada-scheduler,karmada-webhook,karmada-aggregated-apiserver,karmada-agent | TLS uprobe 계측에서 제외할 바이너리 이름·절대경로(콤마 구분). 비우면 모두 계측 |
호스트 프로세스 모니터링 — Kubernetes 밖에서 실행되는 독립(standalone) 호스트 프로세스도 모니터링합니다.
| Helm 값 / 환경변수 | 기본값 | 설명 |
|---|---|---|
(Helm 미노출) / TRACK_STANDALONE_PROCESSES | false | OBSERV_APP_NAME 환경변수를 설정한 호스트 프로세스를 모니터링(앱 ID: /host-process/<이름>:<포트>). Compose·systemd 설치에서 주로 사용 |
OTel Collector 설정
| 항목 | 기본값 | 설명 |
|---|---|---|
openmaruObservOTelCollector.enabled | true | OTel Collector 활성화 여부 |
openmaruObservOTelCollector.OPENMARU_OBSERV_API_KEY | openmaru-observ-api-key | OpenTelemetry 데이터 수신 인증 키 |
팁: 기존에 OpenTelemetry로 계측된 애플리케이션이 있다면 OTel Collector를 통해 해당 데이터도 함께 수집할 수 있습니다.
노드 에이전트 별도 설치
노드 에이전트는 메인 Helm 차트에 포함되어 함께 설치됩니다. 앞의 "Helm 차트 설치" 절차대로 Helm으로 설치하면 노드 에이전트가 DaemonSet으로 배포되어 클러스터의 모든 노드에 자동으로 올라가므로, 노드를 개별적으로 추가하는 작업은 필요하지 않습니다.
아래 절차는 Kubernetes가 아닌 Linux 서버나 별도의 클러스터에 노드 에이전트만 추가로 설치해야 하는 경우에만 필요합니다.
참고: 노드 에이전트가 서버로 데이터를 전송하려면 OPENMARU Observability URL과 API 키가 필요합니다. API 키는 설정 > 시스템 설정 탭에서 생성하며(생성 권한은 관리자(Admin)), 아래 설치 시 URL·API 키 값으로 지정합니다.
Linux 서버에 직접 설치
Kubernetes가 아닌 Linux 서버에 직접 노드 에이전트를 설치할 수 있습니다.
요구사항:
- Linux 운영체제 (x86_64 또는 arm64)
- 커널 버전 4.16 이상
- systemd 지원
- root 권한
노드 에이전트를 systemd 서비스로 등록하여 자동 실행하며, 설치 시 환경 변수로 OPENMARU Observability URL과 API 키를 지정합니다. Linux 직접 설치용 상세 명령·스크립트는 별도의 설치·운영 가이드로 제공됩니다(제품 담당자에게 문의).
브라우저 인증서 신뢰 설정
사내 인증 기관(CA)이 발급한 인증서로 HTTPS를 제공하는 환경이라면, 접속할 PC마다 이 절차를 한 번씩 수행해야 합니다. 폐쇄망에서 .local 같은 사내 도메인을 쓰는 경우가 여기에 해당합니다.
공인 인증서(Let's Encrypt 등)를 사용한다면 이 절은 건너뛰어도 됩니다.
왜 필요한가
인증서를 신뢰 목록에 등록하지 않으면 두 가지 문제가 생깁니다.
첫째, 접속할 때마다 경고 화면이 표시됩니다. 브라우저는 "연결이 비공개로 설정되어 있지 않습니다" 라는 화면과 함께 NET::ERR_CERT_AUTHORITY_INVALID 오류를 보여줍니다.
둘째, 경고를 그때그때 넘겨도 실시간 화면이 주기적으로 멈춥니다. 경고 화면에서 고급 > 계속 진행을 누르면 접속은 되지만, 이는 영구 설정이 아니라 7일간만 유지되는 임시 허용입니다. 7일이 지나면 허용이 사라지고, 이때 대시보드의 실시간 연결(WebSocket)이 끊어집니다. 브라우저는 실시간 연결에 대해서는 경고 화면을 띄우지 못하고 연결만 실패시키므로, 화면은 그대로인데 데이터만 갱신되지 않는 상태가 됩니다. APM 대시보드를 장시간 띄워 두는 환경에서 특히 문제가 됩니다.
인증서를 신뢰 목록에 등록하면 두 문제가 모두 사라집니다.
1단계: 인증서 파일 준비
시스템 관리자에게 사내 루트 CA 인증서 파일(.crt 또는 .pem)을 요청합니다.
관리자가 직접 추출하는 경우, Kubernetes 클러스터에서 아래 명령으로 얻을 수 있습니다.
# Ingress가 사용하는 인증서 전체를 내려받습니다
kubectl -n kube-system get secret wildcard-tls \
-o jsonpath='{.data.tls\.crt}' | base64 -d > full-chain.pem
# 이 중 두 번째 인증서(루트 CA)만 분리합니다
awk '/BEGIN CERT/{n++} n==2' full-chain.pem > openmaru-ca.crt
# 확인 — CA:TRUE 로 표시되어야 합니다
openssl x509 -in openmaru-ca.crt -noout -subject -dates -ext basicConstraints
참고: Secret 이름과 네임스페이스는 설치 환경에 따라 다를 수 있습니다. 위 명령이 동작하지 않으면 Ingress 설정을 확인하거나 제품 담당자에게 문의하세요.
배포 전에 인증서의 지문(fingerprint) 을 확인해 두면, 각 PC에서 올바른 인증서가 설치되었는지 대조할 수 있습니다.
openssl x509 -in openmaru-ca.crt -noout -fingerprint -sha256
2단계(Windows): 인증서 등록
Windows에서는 신뢰할 수 있는 루트 인증 기관 저장소에 등록합니다. 두 가지 방법이 있으며, 결과는 같습니다.
방법 A. 화면에서 등록
openmaru-ca.crt파일을 더블클릭합니다.- 인증서 설치 버튼을 클릭합니다.
- 저장소 위치에서 로컬 컴퓨터를 선택하고 다음을 클릭합니다.
- 사용자 계정 제어(UAC) 창이 뜨면 예를 클릭합니다. 관리자 권한이 필요합니다.
- 현재 사용자를 선택하면 해당 계정에만 적용됩니다. PC를 여러 사람이 쓴다면 로컬 컴퓨터를 선택하세요.
- 모든 인증서를 다음 저장소에 저장을 선택하고 찾아보기를 클릭합니다.
- 목록에서 신뢰할 수 있는 루트 인증 기관을 선택하고 확인을 클릭합니다.
- 다음 > 마침을 클릭합니다.
- "가져오기를 완료했습니다" 메시지가 표시되면 등록된 것입니다.
주의: 4단계에서 인증서 종류에 따라 자동으로 저장소 선택(기본값)을 그대로 두면 다른 저장소에 등록되어 효과가 없습니다. 반드시 저장소를 직접 지정하세요.
방법 B. 명령으로 등록
명령 프롬프트를 관리자 권한으로 실행한 뒤 아래를 입력합니다.
certutil -addstore -f Root openmaru-ca.crt
CertUtil: -addstore 명령이 성공적으로 완료되었습니다. 가 출력되면 등록된 것입니다.
등록 여부는 아래 명령으로 확인합니다.
certutil -store Root | findstr /i "openmaru"
PC가 여러 대인 경우 — 그룹 정책 배포
Active Directory 도메인 환경이라면 그룹 정책으로 한 번에 배포할 수 있습니다. PC마다 방문할 필요가 없습니다.
-
도메인 컨트롤러에서 그룹 정책 관리 편집기를 엽니다.
-
아래 경로로 이동합니다.
컴퓨터 구성 → 정책 → Windows 설정 → 보안 설정→ 공개 키 정책 → 신뢰할 수 있는 루트 인증 기관 -
오른쪽 영역에서 마우스 오른쪽 버튼을 클릭하고 가져오기를 선택합니다.
-
openmaru-ca.crt파일을 선택하고 마법사를 완료합니다.
정책이 적용된 PC는 다음 정책 갱신 주기(기본 90분 이내) 또는 재부팅 시 자동으로 반영됩니다. 즉시 적용하려면 해당 PC에서 gpupdate /force 를 실행합니다.
2단계(macOS): 인증서 등록
macOS에서는 시스템 키체인에 등록하고 항상 신뢰로 설정합니다. 등록만 하고 신뢰 설정을 하지 않으면 경고가 그대로 표시되므로, 두 단계를 모두 수행해야 합니다.
방법 A. 화면에서 등록
openmaru-ca.crt파일을 더블클릭합니다. 키체인 접근 앱이 열립니다.- 키체인 선택 창이 뜨면 시스템을 선택합니다.
- 관리자 암호를 입력합니다.
- 키체인 접근 왼쪽에서 시스템 키체인을 선택하고, 방금 추가한 인증서를 찾습니다. 이름은
ca.로 시작하는 사내 도메인입니다. - 해당 인증서를 더블클릭합니다.
- 신뢰 항목을 펼칩니다.
- 이 인증서 사용 시를 항상 신뢰로 변경합니다.
- 창을 닫고 관리자 암호를 입력하면 저장됩니다.
- 목록에서 인증서 아이콘에 파란색
+표시가 나타나면 신뢰 설정이 적용된 것입니다.
방법 B. 명령으로 등록
터미널에서 아래 명령을 실행합니다. 등록과 신뢰 설정이 한 번에 처리됩니다.
sudo security add-trusted-cert -d -r trustRoot \
-k /Library/Keychains/System.keychain openmaru-ca.crt
관리자 암호를 입력하면 완료됩니다.
옵션의 의미는 다음과 같습니다.
| 옵션 | 의미 |
|---|---|
-d | 모든 사용자에게 적용 (생략하면 현재 사용자만) |
-r trustRoot | 루트 인증 기관으로 신뢰 |
-k /Library/Keychains/System.keychain | 시스템 키체인에 저장 |
등록 여부는 아래 명령으로 확인합니다.
security find-certificate -a -c "ca." /Library/Keychains/System.keychain | head
3단계: 확인
브라우저를 완전히 종료했다가 다시 실행합니다. 탭만 닫는 것으로는 반영되지 않습니다.
- OPENMARU Observability 주소로 접속합니다.
- 주소창에 경고 표시 없이 자물쇠 아이콘이 표시되면 정상입니다.
- 대시보드 상단의 실시간 배지가 활성 상태인지 확인합니다.
명령으로 확인하려면 아래를 실행합니다. 접속주소 부분을 실제 주소로 바꾸세요.
# macOS · Linux
echo | openssl s_client -connect 접속주소:443 -servername 접속주소 2>&1 | grep 'Verify return code'
| 출력 | 의미 |
|---|---|
Verify return code: 0 | 정상 등록됨 |
Verify return code: 19 | 아직 등록되지 않음 |
반환 코드 19 뒤에는 (self-signed certificate in certificate chain) 이 함께 표시됩니다. 인증서 체인의 최상위 발급 기관을 이 PC가 모른다는 뜻입니다.
브라우저별 주의사항
| 브라우저 | 참조하는 신뢰 목록 | 추가 작업 |
|---|---|---|
| Chrome, Edge (Windows) | Windows 인증서 저장소 | 없음 |
| Chrome, Safari (macOS) | macOS 시스템 키체인 | 없음 |
| Firefox (모든 운영체제) | 자체 신뢰 목록 | 아 래 절차 필요 |
Firefox는 운영체제 신뢰 목록을 사용하지 않으므로 별도로 등록해야 합니다.
- 설정 > 개인 정보 및 보안으로 이동합니다.
- 아래로 스크롤하여 인증서 보기 버튼을 클릭합니다.
- 인증 기관 탭을 선택하고 가져오기를 클릭합니다.
openmaru-ca.crt파일을 선택합니다.- 이 인증 기관이 웹사이트를 식별하도록 신뢰를 체크하고 확인을 클릭합니다.
참고: 접속하는 클러스터가 여러 개라면 클러스터마다 인증서가 다릅니다. 접속할 모든 환경의 인증서를 각각 등록해야 합니다.
설치 확인
UI에서 연결 상태 확인
설치가 완료되면 설정 메뉴의 시스템 설정 탭에서 각 구성 요소의 연결 상태를 확인할 수 있습니다.
- 좌측 메뉴 하단의 설정을 클릭합니다.
- 시스템 설정 탭의 노드 상태 섹션을 확인합니다.
| 항목 | 정상 상태 |
|---|---|
| VictoriaMetrics | 정상 |
| openmaru-node-agent | N nodes 찾음 |
| kube-state-metrics | N applications 찾음 |
모든 항목이 정상 상태로 표시되면 설치가 완료된 것입니다.
팁: 에이전트 설치 직후에는 서버로 첫 데이터가 전송되기까지 1~2분이 소요될 수 있습니다. 상태가 바로 표시되지 않으면 잠시 후 페이지를 새로고침하세요.
대시보드에서 데이터 확인
- 좌측 메뉴에서 대시보드를 클릭합니다.
- 클러스터 리소스 게이지에 CPU, 메모리 사용량이 표시되는지 확인합니다.
- Pod 맵에 클러스터의 Pod 목록이 나타나는지 확인합니다.
데이터가 표시되면 OPENMARU Observability가 정상적으로 데이터를 수집하고 있는 것입니다.
kubectl로 확인
아래 명령어로 모든 구성 요소의 실행 상태를 확인할 수 있습니다.
kubectl -n openmaru-observ get pods
주요 확인 사항:
- 모든 Pod의 STATUS가
Running인지 확인합니다. - 노드 에이전트 Pod가 각 노드(Node)마다 하나씩 실행 중인지 확인합니다.
- 클러스터 에이전트 Pod가 실행 중인지 확인합니다.
업그레이드
설치된 OPENMARU Observability를 새 버전으로 업그레이드하려면 helm upgrade 명령어를 사용합니다.
1단계: 차트 저장소 업데이트
helm repo update openmaru-observ
2단계: 업그레이드 실행
helm upgrade -n openmaru-observ \
openmaru-observ openmaru-observ/openmaru-observ
커스텀 values.yaml 파일을 사용하는 경우:
helm upgrade -n openmaru-observ \
-f my-values.yaml \
openmaru-observ openmaru-observ/openmaru-observ
3단계: 업그레이드 확인
kubectl -n openmaru-observ get pods -w
모든 Pod가 새 버전으로 교체되어 Running 상태가 되면 업그레이드가 완료된 것입니다.
주의: 업그레이드 중 서버가 재시작되면서 일시적으로 데이터 수집이 중단될 수 있습니다. 서버는 RollingUpdate 전략으로 배포되므로 한 복제본씩 순차적으로 교체됩니다.
삭제
OPENMARU Observability를 클러스터에서 삭제하려면 아래 명령어를 실행합니다.
helm uninstall -n openmaru-observ openmaru-observ
주의: Helm 삭제 후에도 PersistentVolumeClaim(PVC)은 자동으로 삭제되지 않습니다. 데이터를 완전히 삭제하려면 아래 명령어로 PVC를 수동 삭제하세요.
kubectl -n openmaru-observ get pvc
kubectl -n openmaru-observ delete pvc <PVC 이름>
문제 해결
VictoriaMetrics(메트릭 저장소) 연결 실패
- 서버 Pod가 정상 실행 중인지 확인합니다.
- VictoriaMetrics Pod의 로그에서 오류 메시지가 없는지 확인합니다.
kubectl -n openmaru-observ logs <victoria-metrics-pod-이름>
노드 에이전트가 탐지되지 않음
- 노드 에이전트 Pod가 모든 노드(Node)에서
Running상태인지 확인합니다. - API 키가 올바르게 설정되었는지 확인합니다.
- 노드 에이전트 Pod의 로그에서 연결 오류가 없는지 확인합니다.
kubectl -n openmaru-observ logs <node-agent-pod-이름>
kube-state-metrics가 탐지되지 않음
- kube-state-metrics Pod가 클러스터에서 실행 중인지 확인합니다.
- Helm 차트의
openmaruObservKubeStateMetrics.enabled값이true인지 확인합니다.
노드 에이전트 Pod가 시작되지 않음
- 노드(Node)의 Linux 커널 버전이 4.16 이상인지 확인합니다.
- 노드 에이전트는 privileged 모드로 실행되어야 합니다. 클러스터의 보안 정책이 이를 허용하는지 확인합니다.
- Pod 이벤트를 확인합니다.
kubectl -n openmaru-observ describe pod <노드 에이전트 Pod 이름>
스토리지 관련 오류
- 지정한 스토리지 클래스가 클러스터에 존재하는지 확인합니다.
kubectl get storageclass
- PersistentVolume을 자동 프로비저닝할 수 있는 환경인지 확인합니다.
- 스토리지 용량이 부족한 경우
values.yaml에서 해당 구성 요소의 스토리지 크기를 조정한 후 업그레이드합니다.
팁: 더 자세한 문제 해결 방법은 문제 해결 문서를 참고하세요.