# 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ı