Murat ÖZDEMİR
72a91072fb
- Add health-agent README with architecture, config, and deployment docs - Add deploy-monitoring-test.yml workflow (mirrors prod, test-runner, test storagebox paths) - Add health-agent service to docker-stack-monitoring.yml - Add .env.example with all runtime variables and .gitignore for generated files - Add config/generated/.gitkeep to track empty generated directory - Translate all Turkish group names and status page titles in monitors.yml to English - Remove users.yml.example (Dozzle was removed in previous commit)
197 lines
8.9 KiB
Markdown
197 lines
8.9 KiB
Markdown
# iklim.co Health Agent
|
||
|
||
Docker Swarm cluster içinde çalışan, push modeli üzerinden Uptime Kuma'ya sağlık durumu ileten ve Docker olaylarını Slack'e doğrudan bildiren hafif bir Python servisidir. Gelen bağlantı gerekmez — tüm trafik dışa yönelik HTTPS'tir.
|
||
|
||
---
|
||
|
||
## Mimari
|
||
|
||
Agent, Swarm manager node üzerinde tek replica olarak çalışır ve şu kaynaklara erişir:
|
||
|
||
- `/var/run/docker.sock` (salt okunur) — Swarm servislerini, node'ları ve event stream'ini dinler
|
||
- `iklimco-net` overlay ağı — tüm iç servislere DNS adıyla erişir
|
||
- StorageBox bind mount (salt okunur) — sertifika dosyaları ve yapılandırma varlığını kontrol eder
|
||
- `config/generated/uk_tokens.yml` — `setup_uptime_kuma.py` tarafından üretilir, agent bu dosyayı okur
|
||
|
||
Her check bağımsız çalışır ve kendi Uptime Kuma monitörüne push yapar. Bir check'in başarısız olması diğerlerini etkilemez.
|
||
|
||
Slack bildirimleri iki kanaldan gelir:
|
||
- **`[Uptime Kuma]`** — Uptime Kuma'nın kendi HTTP/DNS/Ping monitörleri tarafından üretilir
|
||
- **`[Health Agent]`** — health-agent'ın push check'lerinden; Uptime Kuma'nın group monitor mekanizması üzerinden iletilir
|
||
- **`[Health Agent / Events]`** — Docker events stream'den gelen anlık restart/OOM bildirimleri; doğrudan Slack webhook'una gönderilir, Uptime Kuma'dan geçmez
|
||
|
||
---
|
||
|
||
## Dizin Yapısı
|
||
|
||
```
|
||
Environment_Monitoring/health-agent/
|
||
├── config/
|
||
│ ├── monitors.yml # tüm monitor/group/tag/status-page tanımları; node IP'leri buraya yazılır
|
||
│ └── generated/
|
||
│ └── uk_tokens.yml # setup_uptime_kuma.py tarafından üretilir; health-agent okur
|
||
├── src/
|
||
│ └── health_agent/
|
||
│ ├── main.py # giriş noktası; scheduler loop
|
||
│ ├── config.py # .env + uk_tokens.yml yükler; ortam ayarlarını expose eder
|
||
│ ├── uptime_kuma.py # push(token, status, msg, ping_ms) yardımcısı
|
||
│ ├── slack.py # notify(webhook, source, priority, title, detail, uk_group_url) — kaynak etiketli + UK grup linki
|
||
│ ├── state.py # restart sayısı gibi session-arası state'i dosyaya yazar/okur
|
||
│ ├── checks/
|
||
│ │ ├── swarm.py # Docker API: node listesi, servis replica sayıları
|
||
│ │ ├── http.py # genel HTTP check + uygulama bazlı parser'lar (Patroni, Vault, RabbitMQ...)
|
||
│ │ ├── tcp.py # TCP port erişilebilirliği
|
||
│ │ ├── tls.py # TLS sertifika son kullanma tarihi (dosyadan veya handshake'den)
|
||
│ │ ├── redis_sentinel.py # Redis Sentinel — redis-py ile quorum ve master kontrolü
|
||
│ │ ├── mongodb.py # MongoDB rs.status() — pymongo ile PRIMARY ve lag kontrolü
|
||
│ │ └── filesystem.py # StorageBox mount varlığı ve SSL cert sync durumu
|
||
│ └── events/
|
||
│ └── docker_events.py # arka plan thread'i; Docker /events stream'ini dinler, restart/OOM bildirir
|
||
├── scripts/
|
||
│ └── setup_uptime_kuma.py # monitors.yml'i okur, UK'da oluşturur, uk_tokens.yml'e yazar
|
||
├── Dockerfile
|
||
├── pyproject.toml
|
||
├── .env.example # health-agent runtime değişkenleri (credentials, ENV, CLUSTER_SIZE_*)
|
||
└── .env.setup.example # setup script değişkenleri (UK_API_KEY, Slack webhook'ları)
|
||
```
|
||
|
||
---
|
||
|
||
## Yapılandırma
|
||
|
||
**`config/monitors.yml`** — Tüm monitor, group, tag ve status page tanımları bu dosyadadır. Yeni bir monitor eklemek için kod değişikliği gerekmez; `monitors.yml`'e yeni bir blok eklenir ve `setup_uptime_kuma.py` çalıştırılır.
|
||
|
||
**`.env`** — Runtime değişkenler:
|
||
|
||
| Variable | Description |
|
||
|----------|-------------|
|
||
| `UK_PUSH_URL_BASE` | Uptime Kuma push base URL (e.g. `https://status.iklim.co/api/push`) |
|
||
| `ENV` | `prod` or `test` |
|
||
| `CLUSTER_SIZE_ETCD` | etcd node count (prod: 3, test: 1) |
|
||
| `CLUSTER_SIZE_PATRONI` | Patroni node count |
|
||
| `CLUSTER_SIZE_MONGODB` | MongoDB node count |
|
||
| `CLUSTER_SIZE_RABBITMQ` | RabbitMQ node count |
|
||
| `CLUSTER_SIZE_VAULT` | Vault node count |
|
||
| `REDIS_MODE` | `sentinel` or `standalone` |
|
||
| `EXTERNAL_DOMAIN` | Base domain — `iklim.co` in both environments |
|
||
| `EXTERNAL_SUBDOMAIN_SUFFIX` | Subdomain suffix — empty for prod, `-test` for test → `api-test.iklim.co` |
|
||
| `SLACK_WEBHOOK_IKLIM_{ENV}_OPS` | Direct Slack webhook for container crash/OOM events — e.g. `SLACK_WEBHOOK_IKLIM_PROD_OPS` |
|
||
| `RABBITMQ_USER` / `RABBITMQ_PASS` | RabbitMQ management credentials |
|
||
| `MONGO_URI` | MongoDB connection URI |
|
||
| `REDIS_PASSWORD` | Redis / Sentinel password |
|
||
| `REDIS_MASTER_NAME` | Redis Sentinel master name |
|
||
| `REDIS_SENTINEL_HOSTS` | Sentinel host list (comma-separated `host:port`) |
|
||
| `STORAGEBOX_PATH` | StorageBox mount path for filesystem check |
|
||
| `APISIX_ADMIN_KEY` | APISIX admin API key for health check |
|
||
|
||
Check periyotları `monitors.yml`'de her monitor için tanımlanır; `.env`'e eklenmez.
|
||
|
||
Push token'ları `config/generated/uk_tokens.yml`'den otomatik okunur — bu dosya `setup_uptime_kuma.py` tarafından üretilir ve `.env`'e elle kopyalanmaz.
|
||
|
||
---
|
||
|
||
## Yeni Check Ekleme
|
||
|
||
1. `src/health_agent/checks/` altına yeni bir dosya ekle veya uygun mevcut dosyaya yeni bir fonksiyon ekle.
|
||
2. Fonksiyon `(ok: bool, msg: str, ping_ms: int)` tuple'ı döndürmeli.
|
||
3. `config/monitors.yml`'e yeni monitor bloğu ekle (isim, grup, öncelik, bildirim kanalı, check periyodu).
|
||
4. `setup_uptime_kuma.py`'yi çalıştır — yeni monitor UK'da oluşturulur ve token `uk_tokens.yml`'e yazılır.
|
||
5. `main.py`'de check fonksiyonunu token ve yapılandırmayla kaydet.
|
||
|
||
---
|
||
|
||
## İlk Kurulum (Uptime Kuma)
|
||
|
||
Health-agent deploy edilmeden önce kurulum script'i çalıştırılır. Script, `monitors.yml`'i okuyarak tüm monitor, tag, group ve status page'leri Uptime Kuma'da oluşturur; push token'larını `config/generated/uk_tokens.yml`'e yazar.
|
||
|
||
Script [`uptime-kuma-api`](https://pypi.org/project/uptime-kuma-api/) kütüphanesini kullanır. API key authentication desteği implementasyon öncesi doğrulanmalıdır; desteklenmiyorsa `requests` + `Authorization: Bearer <api_key>` ile REST API doğrudan çağrılır.
|
||
|
||
```bash
|
||
cd Environment_Monitoring/health-agent
|
||
|
||
# setup değişkenlerini doldur
|
||
cp .env.setup.example .env.setup
|
||
|
||
# önce dry-run ile ne yapılacağını gör
|
||
python scripts/setup_uptime_kuma.py --dry-run
|
||
|
||
# tüm kaynakları oluştur
|
||
python scripts/setup_uptime_kuma.py
|
||
|
||
# sadece belirli bileşenleri güncelle
|
||
python scripts/setup_uptime_kuma.py --only monitors
|
||
python scripts/setup_uptime_kuma.py --only notifications
|
||
python scripts/setup_uptime_kuma.py --only status-page
|
||
```
|
||
|
||
Script idempotent çalışır — CI/CD pipeline'ında her deploy'da güvenle tetiklenebilir.
|
||
|
||
---
|
||
|
||
## Notification Flood Önleme
|
||
|
||
Uptime Kuma group monitor mekanizması kullanılır: Slack bildirimi child monitor'lere değil, **yalnızca group monitor'e** bağlanır. Bir grup içinde birden fazla monitor aynı anda çökse dahi tek bildirim üretilir.
|
||
|
||
Planlı bakım/deploy sırasında etkilenecek group için Uptime Kuma'da Maintenance penceresi açılır (API üzerinden otomatik yapılabilir). Bu süre zarfında alarm üretilmez.
|
||
|
||
---
|
||
|
||
## Yerel Geliştirme
|
||
|
||
```bash
|
||
cd Environment_Monitoring/health-agent
|
||
|
||
# bağımlılıkları kur
|
||
pip install -e ".[dev]"
|
||
|
||
# .env dosyasını hazırla
|
||
cp .env.example .env
|
||
|
||
# tek döngü çalıştır (scheduler olmadan, credential kontrolü için)
|
||
python -m health_agent.main --once
|
||
|
||
# tam scheduler'ı başlat
|
||
python -m health_agent.main
|
||
```
|
||
|
||
`--once` bayrağı her check'i bir kez çalıştırıp çıkar — credential ve bağlantı doğrulama için kullanılır.
|
||
|
||
---
|
||
|
||
## Deployment
|
||
|
||
Monitoring stack ve health-agent ayrı Gitea workflow'larıyla deploy edilir:
|
||
|
||
- `.gitea/workflows/deploy-monitoring-prod.yml` — prod ortamı
|
||
- `.gitea/workflows/deploy-monitoring-test.yml` — test ortamı
|
||
|
||
Her iki workflow da şu sırayı izler: (1) `setup_uptime_kuma.py` çalıştır → `uk_tokens.yml` üret, (2) monitoring stack'i deploy et, (3) health-agent stack'ini deploy et.
|
||
|
||
Manuel deploy için:
|
||
|
||
```bash
|
||
# önce setup_uptime_kuma.py çalıştır
|
||
python scripts/setup_uptime_kuma.py
|
||
|
||
# tek stack: portainer + loki + promtail + health-agent
|
||
docker stack deploy \
|
||
--with-registry-auth \
|
||
-c docker-stack-monitoring.yml \
|
||
iklimco-monitoring
|
||
```
|
||
|
||
Health-agent `iklimco-net` overlay ağına bağlı olmalı ve Docker socket'a salt okunur erişimi olmalıdır.
|
||
|
||
---
|
||
|
||
## Log Formatı
|
||
|
||
Agent JSON formatında log üretir. Grafana Explore (Loki datasource, `{service="iklimco-monitoring_health-agent"}`) veya `docker service logs iklimco-monitoring_health-agent` ile izlenebilir. Her log girdisi şu alanları içerir:
|
||
|
||
- `check` — monitor adı
|
||
- `status` — `up` veya `down`
|
||
- `msg` — Uptime Kuma'ya iletilen mesaj
|
||
- `ping_ms` — check süresi
|
||
- `source` — `health-agent` veya `health-agent/events`
|
||
- `error` — yalnızca hata durumunda; exception detayı
|