Worker-Monitor-Node Stack & README

2026-01-22 11:06:46 +09:00
commit 4e7e9cd926
6 changed files with 410 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,113 @@
+# rpi-worker-monitor-node
+작성: AI / 수정: nkey
+
+라즈베리파이 **모니터링 워커 노드**에서 Prometheus/Alertmanager/Loki/Grafana를 **Docker Compose**로 구동하기 위한 레포입니다.
+
+- `monitoring/docker-compose.yml`: 모니터링 스택 컨테이너 실행
+- `monitoring/prometheus/*`: Prometheus 설정/알람 룰
+- `monitoring/alertmanager/*`: Alertmanager 라우팅/웹훅
+- `monitoring/loki/*`: Loki 스토리지/인덱싱 설정  
+
+docker compose로 배포하던 방식을 k3s로 배포하는 방식으로 수정하면서 master node에서 한번에 배포 진행합니다. (참고: `rpi-master-node/k3s-monitoring`)  
+아래 내용들은 docker compose로 하던 방식에 대한 설명이니 참고만 부탁드립니다.  
+
+
+## Quickstart
+### Recommended
+```bash
+# clone
+git clone https://nkeystudy.site/gitea/2025-capstone/rpi-worker-monitor-node.git
+cd rpi-worker-monitor-node/monitoring
+
+# run
+docker compose up -d
+
+# verify
+docker compose ps
+curl -s http://localhost:9090/-/ready
+curl -s http://localhost:9093/-/ready
+curl -s http://localhost:3100/ready
+```
+
+## Requirements
+- Runtime/Language: Docker Engine + Docker Compose
+- Dependencies: 없음(스택은 모두 컨테이너로 구동)
+- Tools: `docker`, `docker compose`
+
+## Configuration
+### Environment Variables
+| Key | Description | Default | Required |
+|---|---|---:|:---:|
+| TZ | 컨테이너 타임존 | `Asia/Seoul` |  |
+| GF_SECURITY_ADMIN_USER | Grafana 관리자 계정 | `admin` |  |
+| GF_SECURITY_ADMIN_PASSWORD | Grafana 관리자 비밀번호 | `admin1234` |  |
+
+### Ports
+| Service | Port | Description |
+|---|---:|---|
+| Prometheus | 9090 | Prometheus UI/API |
+| Alertmanager | 9093 | Alertmanager UI/API |
+| Loki | 3100 | Loki API |
+| Grafana | 3000 | Grafana UI |
+| Node-Exporter | 9100 | Prometheus scraping  |
+| Promtail | 9080 | Prometheus scraping |
+
+## Usage (minimal)
+- 실행/중지
+```bash
+cd monitoring
+docker compose up -d
+docker compose down
+```
+
+- Prometheus 설정 변경 후 reload
+```bash
+# docker-compose.yml 에서 --web.enable-lifecycle 활성화되어 있음
+curl -X POST http://localhost:9090/-/reload
+```
+
+## 설정 파일 설명 (이 레포에 포함된 것만)
+### Docker Compose
+- `monitoring/docker-compose.yml`
+  - `prometheus`, `alertmanager`, `loki`, `grafana` 4개 서비스를 동일 네트워크에서 실행
+  - Prometheus:
+    - `./prometheus/prometheus.yml`, `./prometheus/alert.rules.yml`을 컨테이너에 마운트
+    - 데이터는 `prometheus-data` 볼륨에 저장
+    - `--web.enable-lifecycle`로 `/-/reload` 지원
+  - Alertmanager:
+    - `./alertmanager/alertmanager.yml` 마운트
+    - 데이터는 `alertmanager-data` 볼륨에 저장
+  - Loki:
+    - `./loki/loki-config.yml` 마운트
+    - 데이터는 `loki-data` 볼륨에 저장
+  - Grafana:
+    - 데이터는 `grafana-data` 볼륨에 저장
+    - 관리자 계정/비번을 env로 주입
+
+### Prometheus
+- `monitoring/prometheus/prometheus.yml`
+  - 스크레이프 타겟:
+    - `node-exporter`를 노드별 `:9100`으로 수집(`rpi-master:9100`, `rpi-worker-monitor:9100`, `rpi-worker-service:9100`)
+    - `kube-state-metrics`는 `10.43.217.216:8080`로 설정(클러스터 환경에 맞게 조정 필요)
+  - Alertmanager 타겟: `alertmanager:9093`
+  - 룰 파일: `/etc/prometheus/alert.rules.yml`
+- `monitoring/prometheus/alert.rules.yml`
+  - 노드 상태/리소스 알람:
+    - `NodeDown`, `HighCpuLoad`, `HighMemoryUsage`, `DiskAlmostFull(>0.85)`, `HighSystemLoad`
+  - K8s 워크로드 알람:
+    - `KubeNodeNotReady`, `PodCrashLooping`, `PodNotReady`, `DeploymentReplicasMismatch`
+
+### Alertmanager
+- `monitoring/alertmanager/alertmanager.yml`
+  - `severity="critical"` 알람을 `n8n-webhook`으로 라우팅
+  - Webhook URL: `http://<IP>/n8n/webhook/alert`
+  - `send_resolved: true`로 해제 이벤트도 전송
+
+### Loki
+- `monitoring/loki/loki-config.yml`
+  - 단일 인스턴스 Loki 설정(filesystem 기반)
+  - `chunks_directory`, `active_index_directory` 등을 `/loki/*` 하위로 사용
+  - `auth_enabled: false`(내부 데모 용도)
+
+## License
+(Not specified in repo)