diff --git a/README.md b/README.md index 9389da2..219be0a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,233 @@ -# infra-report +# Infra Report -인프라 주간 모니터링 보고서 시스템 \ No newline at end of file +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 - <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으로 이미지 태그 결정 diff --git a/record.md b/record.md index a5c1fc6..bc91a70 100644 --- 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 빌드 및 파드 재배포 방지.