docs: update record.md (#28-31) and add comprehensive README

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-17 14:03:16 +09:00 · 2026-03-17 14:03:16 +09:00 · 139e758ad8
parent 59c1a29400
commit 139e758ad8
2 changed files with 240 additions and 2 deletions
--- a/README.md
+++ b/README.md
@ -1,3 +1,233 @@
-# infra-report
+# Infra Report

-인프라 주간 모니터링 보고서 시스템
+Kubernetes 클러스터 인프라 모니터링 주간 리포트 시스템. Prometheus와 Kubernetes API에서 메트릭을 수집하여 웹 대시보드로 시각화합니다.
+
+## 기능
+
+- **CPU / Memory / Disk / NAS 사용률** 시계열 차트 및 통계 (avg, max, min)
+- **Ingress / Istio Network Traffic** RX/TX 분리 차트 및 통계
+- **노드별 상세 테이블** (CPU, Memory, Disk avg/max/min, 노드 스펙)
+- **NAS / Ingress / Istio 상세 테이블** (mountpoint별, RX/TX별 avg/max/min)
+- **주의 구간 자동 감지** (임계값 기반 + Z-score peak 감지)
+- **기간 선택** (시작일/종료일 직접 설정 + 프리셋 버튼)
+- **차트 인터랙션** (hover 시 전체 데이터 tooltip, 클릭 시 solo 모드)
+- **PDF 내보내기**
+
+## 기술 스택
+
+| 구분 | 기술 |
+|------|------|
+| Frontend | Next.js 14 (App Router), React 18, TypeScript |
+| 스타일링 | Tailwind CSS 3 |
+| 차트 | Apache ECharts 6 (echarts-for-react) |
+| 상태관리 | TanStack React Query 5 |
+| 데이터 소스 | Prometheus HTTP API, Kubernetes API |
+| PDF 생성 | html2canvas + jsPDF |
+| 컨테이너 | Docker (multi-stage build, standalone output) |
+| 패키지 관리 | Helm Chart (OCI) |
+| CI/CD | Gitea Actions → Harbor (Docker + Helm OCI) |
+| 배포 | ArgoCD (자동 sync, semver range `>0.0.0`) |
+| 레지스트리 | Harbor |
+
+## 프로젝트 구조
+
+```
+src/
+├── app/
+│   ├── page.tsx                    # 메인 대시보드 페이지
+│   └── api/
+│       ├── report/route.ts         # 전체 리포트 API
+│       ├── metrics/[type]/route.ts # 개별 메트릭 API
+│       └── health/route.ts         # 헬스체크
+├── components/
+│   ├── charts/
+│   │   ├── TimeSeriesChart.tsx     # CPU/Memory/Disk/NAS 차트
+│   │   └── NetworkChart.tsx        # Ingress/Istio 네트워크 차트
+│   ├── report/
+│   │   ├── SummaryCards.tsx        # 상단 요약 카드 (5개)
+│   │   ├── NodeTable.tsx           # 노드별 상세 테이블
+│   │   ├── NasTable.tsx            # NAS mountpoint별 상세
+│   │   ├── NetworkTable.tsx        # Network RX/TX 상세
+│   │   ├── AlertPanel.tsx          # 주의 구간 패널 (CPU/Memory/Disk/NAS)
+│   │   ├── NetworkAlertPanel.tsx   # Network 주의 구간 패널
+│   │   └── ReportHeader.tsx        # 리포트 헤더 + PDF 버튼
+│   └── ErrorBoundary.tsx           # 에러 격리 컴포넌트
+├── hooks/
+│   └── useReport.ts                # React Query 기반 데이터 fetch
+├── lib/
+│   ├── prometheus.ts               # Prometheus API 클라이언트 + PromQL 쿼리
+│   ├── kubernetes.ts               # Kubernetes API 클라이언트
+│   ├── analytics.ts                # 통계 계산 + Z-score peak 감지
+│   └── formatters.ts               # 포맷팅 유틸 (bytes, percent, timestamp)
+└── types/
+    └── metrics.ts                  # TypeScript 인터페이스 정의
+
+charts/infra-report/                # Helm Chart
+├── Chart.yaml
+├── values.yaml
+└── templates/
+    ├── deployment.yaml
+    ├── service.yaml
+    ├── ingress.yaml
+    ├── configmap.yaml
+    ├── serviceaccount.yaml
+    ├── clusterrole.yaml
+    └── clusterrolebinding.yaml
+```
+
+## 주의 구간 판단 기준
+
+### 임계값 기반
+
+| 메트릭 | Warning | Critical |
+|--------|---------|----------|
+| CPU | - | max > 90% |
+| Memory | 80% < max ≤ 90% | max > 90% |
+| Disk | 80% < max ≤ 90% | max > 90% |
+| NAS | 80% < max ≤ 90% | max > 90% |
+
+### Z-score Peak 감지
+
+CPU, Memory, Ingress, Istio에 적용됩니다.
+
+- **알고리즘**: 전체 데이터의 평균(mean)과 모표준편차(stddev)를 계산하고, 각 데이터 포인트의 Z-score `(값 - mean) / stddev`를 산출
+- **Threshold**: `|Z-score| > 5` (평균에서 표준편차 5배 이상 벗어난 경우)
+- **구간 병합**: 연속된 peak 포인트를 하나의 구간으로 묶어 시작/종료 시간, 최대값, 평균값 기록
+- **차트 표시**: peak 구간은 차트에 빨간색 반투명 영역으로 표시
+
+## 환경 변수 (ConfigMap)
+
+`charts/infra-report/values.yaml`의 `config` 섹션에서 설정합니다.
+
+| 변수 | 기본값 | 설명 |
+|------|--------|------|
+| `PROMETHEUS_URL` | `http://prometheus-server.monitoring` | Prometheus 서버 주소 |
+| `REPORT_STEP` | `5m` | 데이터 수집 간격 |
+| `REPORT_RANGE_DAYS` | `7` | 기본 조회 기간 (일) |
+| `TZ` | `Asia/Seoul` | 타임존 |
+| `QUERY_CPU` | `100 - (avg by (node)(...))` | CPU 사용률 PromQL |
+| `QUERY_MEMORY` | `(1 - MemAvailable/MemTotal) * 100` | Memory 사용률 PromQL |
+| `QUERY_DISK` | `(1 - avail/size) * 100` | Disk 사용률 PromQL |
+| `QUERY_NAS` | NFS 기반 쿼리 | NAS 사용률 PromQL |
+| `QUERY_INGRESS_RX/TX` | ingress-nginx 컨테이너 네트워크 | Ingress 트래픽 PromQL |
+| `QUERY_ISTIO_RX/TX` | istio-system 컨테이너 네트워크 | Istio 트래픽 PromQL |
+
+PromQL 쿼리를 변경하면 values.yaml 수정 후 Helm chart를 재배포하면 됩니다 (소스 코드 수정 불필요).
+
+## 배포 방법
+
+### 사전 요구사항
+
+- Kubernetes 클러스터
+- Prometheus (node-exporter 포함)
+- Harbor 레지스트리
+- ArgoCD
+- Gitea (소스 저장소 + CI/CD)
+
+### 1. Gitea 저장소 Secrets 등록
+
+Gitea 저장소 Settings > Secrets에 다음을 등록합니다:
+
+| Secret | 설명 |
+|--------|------|
+| `REGISTRY_URL` | Harbor 주소 (예: `harbor.example.com`) |
+| `REGISTRY_USER` | Harbor 사용자 |
+| `REGISTRY_PASSWORD` | Harbor 비밀번호 |
+
+### 2. Harbor Pull Secret 생성
+
+```bash
+kubectl create secret docker-registry harbor-pull-secret \
+  --docker-server=harbor.example.com \
+  --docker-username=admin \
+  --docker-password='password' \
+  -n soo
+```
+
+### 3. ArgoCD Repository Secret 생성
+
+```bash
+kubectl apply -f - <<EOF
+apiVersion: v1
+kind: Secret
+metadata:
+  name: harbor-helm-repo
+  namespace: argocd
+  labels:
+    argocd.argoproj.io/secret-type: repository
+type: Opaque
+stringData:
+  type: helm
+  name: harbor-infra
+  url: harbor.example.com/infra
+  enableOCI: "true"
+  username: admin
+  password: "password"
+EOF
+```
+
+### 4. ArgoCD Application 생성
+
+```bash
+kubectl apply -f - <<EOF
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: infra-report
+  namespace: argocd
+spec:
+  project: default
+  source:
+    chart: infra-report
+    repoURL: harbor.example.com/infra
+    targetRevision: ">0.0.0"
+    helm:
+      releaseName: infra-report
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: soo
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+EOF
+```
+
+### 5. 코드 Push → 자동 배포
+
+`main` 브랜치에 push하면:
+1. **Gitea Actions**: Docker 이미지 빌드 → Harbor push
+2. **Gitea Actions**: Helm chart 패키징 → Harbor OCI push (타임스탬프 기반 버전)
+3. **ArgoCD**: 새 chart 버전 감지 → 자동 sync → 파드 재배포
+
+> `.md` 파일만 변경된 push에서는 CI가 실행되지 않습니다 (`paths-ignore` 설정).
+
+### 로컬 개발
+
+```bash
+npm install
+npm run dev    # http://localhost:3000
+```
+
+Prometheus 접근이 필요하므로 포트포워딩 또는 환경 변수 설정이 필요합니다:
+```bash
+PROMETHEUS_URL=http://localhost:9090 npm run dev
+```
+
+## 시간대 처리
+
+- Prometheus는 항상 UTC로 데이터를 저장/반환합니다
+- 프론트엔드에서 `Asia/Seoul` 타임존으로 변환하여 표시합니다
+- `TZ` 환경 변수는 Prometheus 쿼리에 영향을 주지 않습니다
+
+## Kubernetes RBAC
+
+ServiceAccount `infra-report-sa`에 ClusterRole이 부여되어 노드 정보를 조회합니다:
+- `nodes` 리소스에 대한 `get`, `list` 권한
+
+## 이미지 태그 전략
+
+- CI에서 `sha-<7자리 commit hash>` 형태로 태그 생성 (예: `sha-25c7d82`)
+- `v*` 태그 push 시 태그 이름 그대로 사용 (예: `v1.0.0`)
+- Helm chart의 `appVersion`에 이미지 태그가 자동 설정됨
+- Deployment는 `appVersion` fallback으로 이미지 태그 결정
--- a/record.md
+++ b/record.md
@ -59,3 +59,11 @@
 26. **Ingress/Istio Network 상세 테이블 추가**: `NetworkTable` 컴포넌트 신규 생성. RX(파란색 태그)/TX(초록색 태그)별 avg/max/min 표시. Ingress, Istio 각각 별도 테이블로 표시.

 27. **주의 구간을 차트 옆으로 이동**: 하단 `AlertSection` 제거하고 `AlertPanel` 컴포넌트 신규 생성. CPU/Memory/Disk 각 차트 오른쪽(280px)에 해당 메트릭의 주의 구간 표시. 차트 높이(300px)에 맞추고 내용 초과 시 스크롤 가능. 주의사항 없으면 초록색 "특이사항 없음" 표시.
+
+28. **NAS/Ingress/Istio 주의 구간 추가**: NAS는 Disk과 동일 기준(80% warning, 90% critical). Ingress/Istio는 `NetworkAlertPanel` 컴포넌트 신규 생성, Z-score peak 기반 트래픽 급증 감지. 모든 차트 오른쪽에 AlertPanel 배치.
+
+29. **Z-score threshold 변경**: peak 감지 기본 threshold 2 → 5로 상향. 평균에서 표준편차 5배 이상 벗어나야 peak 판정.
+
+30. **Memory 주의 기준 변경**: warning 85%/critical 95% → warning 80%~90%/critical 90% 초과로 변경.
+
+31. **CI paths-ignore 추가**: `*.md`, `docs/**` 파일만 변경된 push에서는 CI 스킵. 불필요한 Docker 빌드 및 파드 재배포 방지.