2.1. 빠른 시작

OPENMARU Observability를 설치하고 첫 번째 모니터링 데이터를 확인하는 최단 경로를 안내합니다.

개요

이 가이드는 OPENMARU Observability를 처음 도입하는 운영자를 위한 안내입니다. Helm을 사용하여 Kubernetes 클러스터에 설치하고, 대시보드에서 첫 번째 데이터를 확인하기까지의 과정을 단계별로 설명합니다.

전체 과정은 약 15~30분이 소요됩니다.

화면 구성

빠른 시작 과정에서 접하게 되는 주요 화면은 다음과 같습니다.

화면	설명
로그인	이메일과 비밀번호를 입력하여 시스템에 접속하는 화면
설정 > 시스템 설정	서버 상태 확인 및 API 키(API Key) 관리 화면
대시보드	클러스터 전체 현황을 실시간으로 모니터링하는 메인 화면
애플리케이션	모니터링 대상 애플리케이션(Application) 목록과 상태를 확인하는 화면

주요 기능

설치

OPENMARU COP(Container Orchestration Platform) 로 플랫폼을 구축하면 OPENMARU Observability와 필요한 구성 요소가 자동으로 설치·구성되므로 별도 설치가 필요 없습니다.

이미 운영 중인 Kubernetes 클러스터에 OPENMARU Observability만 추가하려면 Helm 차트로 설치합니다. 시스템 요구사항(운영체제·커널·Kubernetes·스토리지), values.yaml 설정, 리소스 요구사항, 설치되는 구성 요소 등 자세한 설치 절차는 3장 설치 를 참고하세요.

설치가 완료되어 모든 Pod가 정상 상태가 되면 다음 단계로 진행합니다.

처음 접속 및 로그인

브라우저에서 Ingress에 설정한 주소로 접속합니다.

최초 접속 시 관리자 비밀번호 설정 화면이 표시됩니다. 비밀번호를 입력하고 비밀번호 확인 필드에 동일한 비밀번호를 한 번 더 입력합니다.
관리자 비밀번호 설정 및 로그인 버튼을 클릭하면 관리자 계정이 생성되고 자동으로 로그인됩니다.
이후 접속 시에는 로그인 화면에서 이메일과 비밀번호를 입력한 뒤 로그인 버튼을 클릭합니다.

참고: SSO(Single Sign-On)가 설정된 환경에서는 SSO 로그인 버튼이 별도로 표시됩니다. SSO 설정은 관리자에게 문의하세요.

API 키 발급 및 에이전트 연결

클러스터 에이전트와 노드 에이전트가 Observability 서버에 데이터를 전송할 때 사용할 API 키(API Key)를 발급합니다.

API 키 발급

좌측 사이드바 하단의 설정을 클릭합니다.
시스템 설정 탭의 API 키 섹션에서 API 키 생성 버튼을 클릭합니다.
키 설명(예: cluster-agent)을 입력하고 생성 버튼을 클릭합니다.
발급된 API 키 옆의 복사 버튼을 클릭하여 키를 복사합니다.

중요: API 키는 에이전트가 서버에 데이터를 전송할 때 인증에 사용됩니다. 안전한 곳에 보관하세요.

에이전트에 API 키 설정

발급한 API 키를 values.yaml에 추가한 뒤 Helm 업그레이드를 실행합니다.

openmaruClusterAgent:
  config:
    api_key: "<발급받은 API 키>"

helm upgrade openmaru-observ openmaru-observ/openmaru-observ \
  --namespace openmaru-observ \
  -f values.yaml

참고: Helm 업그레이드 후 에이전트 Pod가 재시작되며, 데이터가 수집되기까지 약 1~2분이 소요됩니다.

노드 상태 확인

API 키를 설정한 후 설정 > 시스템 설정 탭의 노드 상태 섹션에서 각 구성 요소의 상태를 확인합니다.

항목	정상 상태
VictoriaMetrics	정상
openmaru-node-agent (노드 에이전트)	노드(Node) 수 표시 (예: `7 nodes 찾음`)
kube-state-metrics	애플리케이션 수 표시 (예: `221 applications 찾음`)

모든 항목에 녹색 상태 표시등이 나타나면 데이터 수집이 정상적으로 진행 중인 것입니다.

첫 번째 데이터 확인

에이전트가 정상적으로 연결되면 대시보드에서 데이터를 확인할 수 있습니다.

대시보드 확인

좌측 사이드바에서 대시보드를 클릭합니다.
상단의 실시간 배지가 초록색으로 표시되면 실시간 데이터가 수신 중인 것입니다.
클러스터 리소스 게이지에서 CPU, 메모리, 디스크, Pod 사용 현황을 확인합니다.
클러스터 상태 카드에서 노드(Node), Pod, 워크로드(Workload), 인시던트(Incident), 배포(Deployment) 현황을 확인합니다.

대시보드에서는 다음과 같은 정보를 한눈에 파악할 수 있습니다.

영역	확인 내용
리소스 게이지	CPU, 메모리, 디스크, Pod의 전체 사용률
상태 카드	노드, Pod, 워크로드, 인시던트, 배포의 수와 상태 요약
네임스페이스(Namespace) 트리맵	네임스페이스별 리소스 배분 현황
Pod 맵	전체 Pod의 상태를 타일 형태로 시각화

애플리케이션 확인

좌측 사이드바에서 애플리케이션을 클릭합니다.
모니터링 중인 애플리케이션 목록이 표시됩니다. 각 애플리케이션의 상태, 오류(Error), 응답 시간(Latency), 인스턴스(Instance) 수 등을 확인할 수 있습니다.
특정 애플리케이션을 클릭하면 상세 페이지로 이동하여 CPU, 메모리, SLO(Service Level Objective, 서비스 수준 목표) 등의 상세 메트릭을 확인할 수 있습니다.

노드 확인

좌측 사이드바에서 노드를 클릭합니다.
노드 에이전트가 설치된 노드(Node) 목록과 각 노드의 CPU 사용률, 메모리 사용률, 네트워크 상태 등이 표시됩니다.
특정 노드를 클릭하면 상세 페이지에서 시스템 메트릭 차트를 확인할 수 있습니다.

팁: 데이터가 표시되지 않는다면 아래 항목을 확인하세요.

모든 Pod가 Running 상태인지 확인: kubectl get pods -n openmaru-observ

클러스터 에이전트에 올바른 API 키가 설정되어 있는지 확인

노드 에이전트 Pod의 로그에 오류가 없는지 확인: kubectl logs -n openmaru-observ <에이전트-pod-이름>

다음 단계

기본 설치가 완료되었습니다. 아래 기능을 추가로 설정하면 더 풍부한 모니터링 환경을 구성할 수 있습니다.

기능	설명	참고 문서
알림 채널 연결	Slack, Teams, Webhook으로 인시던트 알림 수신	설정
검사 조건 설정	CPU, 메모리, 응답 시간 등의 임계값(Threshold) 설정	설정
분산추적 연동	OpenTelemetry SDK로 상세 추적 수집	분산추적
사용자 관리	팀원 추가 및 역할 기반 액세스 제어(RBAC) 설정	설정

개요​

화면 구성​

주요 기능​

설치​

처음 접속 및 로그인​

API 키 발급 및 에이전트 연결​

API 키 발급​

에이전트에 API 키 설정​

노드 상태 확인​

첫 번째 데이터 확인​

대시보드 확인​

애플리케이션 확인​

노드 확인​

다음 단계​

관련 문서​

개요