mirror of
https://github.com/taylanbakircioglu/haproxy-openmanager.git
synced 2026-09-22 18:43:26 +00:00
docs: Add CONFIG.md and UPGRADE_GUIDE.md with public-friendly URLs
- Add configuration guide for environment variables - Add agent upgrade guide - Use example.com instead of company-specific URLs - No sensitive information included
This commit is contained in:
taylanbakircioglu
@@ -0,0 +1,276 @@
|
||||
# Configuration Guide - HAProxy OpenManager
|
||||
|
||||
## 📋 Yapılandırma Dosyaları
|
||||
|
||||
### Dosya Yapısı
|
||||
|
||||
```
|
||||
haproxy-openmanager/
|
||||
├── .env.template # ✅ Template (GIT'e commit edilir)
|
||||
├── .env # ❌ Gerçek config (GIT'e commit EDİLMEZ)
|
||||
├── .gitignore # .env dosyalarını korur
|
||||
└── CONFIG.md # Bu dosya
|
||||
```
|
||||
|
||||
## 🎯 Quick Start
|
||||
|
||||
### 1. Template'den Config Oluşturma
|
||||
|
||||
```bash
|
||||
# Template'i kopyala
|
||||
cp .env.template .env
|
||||
|
||||
# Gerçek değerleri düzenle
|
||||
nano .env
|
||||
```
|
||||
|
||||
### 2. Örnek Yapılandırmalar
|
||||
|
||||
#### Development (Local)
|
||||
```bash
|
||||
# .env dosyası
|
||||
PUBLIC_URL=http://localhost:8000
|
||||
MANAGEMENT_BASE_URL=http://localhost:8000
|
||||
DEBUG=True
|
||||
LOG_LEVEL=DEBUG
|
||||
```
|
||||
|
||||
#### Staging
|
||||
```bash
|
||||
# .env dosyası veya K8s ConfigMap
|
||||
PUBLIC_URL=https://haproxy-staging.company.com
|
||||
MANAGEMENT_BASE_URL=https://haproxy-staging.company.com
|
||||
DEBUG=False
|
||||
LOG_LEVEL=INFO
|
||||
```
|
||||
|
||||
#### Production (OpenShift)
|
||||
```bash
|
||||
# K8s ConfigMap: k8s/manifests/07-configmaps.yaml
|
||||
data:
|
||||
PUBLIC_URL: 'https://haproxy-manager.example.com'
|
||||
MANAGEMENT_BASE_URL: 'https://haproxy-manager.example.com'
|
||||
DEBUG: 'False'
|
||||
LOG_LEVEL: 'INFO'
|
||||
```
|
||||
|
||||
## 🔐 Güvenlik
|
||||
|
||||
### Hassas Bilgiler
|
||||
|
||||
`.env` dosyası hassas bilgiler içerir:
|
||||
- ❌ Database şifreleri
|
||||
- ❌ Secret key'ler
|
||||
- ❌ API token'ları
|
||||
|
||||
**Bu yüzden**:
|
||||
- ✅ `.env` → `.gitignore`'da (commit edilmez)
|
||||
- ✅ `.env.template` → Git'e commit edilir (örnek değerler)
|
||||
- ✅ Production'da: Kubernetes Secrets kullan
|
||||
|
||||
### .gitignore Kontrolü
|
||||
|
||||
```bash
|
||||
# .env dosyalarının ignore edildiğini kontrol et
|
||||
grep "^\.env" .gitignore
|
||||
|
||||
# Çıktı olmalı:
|
||||
# .env
|
||||
# .env.local
|
||||
# .env.development.local
|
||||
# .env.test.local
|
||||
# .env.production.local
|
||||
```
|
||||
|
||||
## 📚 Environment Variable Detayları
|
||||
|
||||
### PUBLIC_URL
|
||||
|
||||
**Ne İşe Yarar**: Agent kurulum script'lerinde kullanılır
|
||||
|
||||
**Örnekler**:
|
||||
```bash
|
||||
# Development
|
||||
PUBLIC_URL=http://localhost:8000
|
||||
|
||||
# Production
|
||||
PUBLIC_URL=https://haproxy-manager.company.com
|
||||
|
||||
# OpenShift
|
||||
PUBLIC_URL=https://haproxy-manager.example.com
|
||||
```
|
||||
|
||||
**Nasıl Kullanılır**:
|
||||
1. Agent Management sayfasından "Generate Install Script"
|
||||
2. Script içinde `{{MANAGEMENT_URL}}` bu değerle değiştirilir
|
||||
3. Agent bu URL'ye bağlanarak backend'i dinler
|
||||
|
||||
### REACT_APP_API_URL
|
||||
|
||||
**Ne İşe Yarar**: Frontend'in backend'e bağlanacağı URL
|
||||
|
||||
**Özel Durum**:
|
||||
```bash
|
||||
# Boş bırakılırsa → Auto-detect (production için önerilen)
|
||||
REACT_APP_API_URL=
|
||||
|
||||
# Development için explicit
|
||||
REACT_APP_API_URL=http://localhost:8000
|
||||
```
|
||||
|
||||
**Auto-detect Mantığı**:
|
||||
```javascript
|
||||
// frontend/src/utils/api.js
|
||||
if (process.env.REACT_APP_API_URL) {
|
||||
return process.env.REACT_APP_API_URL;
|
||||
}
|
||||
|
||||
// Production'da same-origin kullan
|
||||
if (window.location) {
|
||||
return `${window.location.protocol}//${window.location.hostname}`;
|
||||
}
|
||||
```
|
||||
|
||||
## 🚀 Deployment Senaryoları
|
||||
|
||||
### Docker Compose
|
||||
|
||||
```bash
|
||||
# 1. .env dosyası oluştur
|
||||
cp .env.template .env
|
||||
|
||||
# 2. Değerleri düzenle
|
||||
nano .env
|
||||
|
||||
# 3. Başlat
|
||||
docker-compose up -d
|
||||
|
||||
# 4. Kontrol et
|
||||
docker-compose logs backend | grep "PUBLIC_URL"
|
||||
```
|
||||
|
||||
### Kubernetes/OpenShift
|
||||
|
||||
```bash
|
||||
# 1. ConfigMap'i düzenle
|
||||
vim k8s/manifests/07-configmaps.yaml
|
||||
|
||||
# 2. Apply
|
||||
kubectl apply -f k8s/manifests/
|
||||
|
||||
# 3. Kontrol et
|
||||
kubectl get configmap backend-config -n haproxy-manager -o yaml
|
||||
```
|
||||
|
||||
### Manuel (Development)
|
||||
|
||||
```bash
|
||||
# 1. Backend
|
||||
cd backend
|
||||
cp ../.env.template .env
|
||||
export $(cat .env | xargs)
|
||||
uvicorn main:app --reload
|
||||
|
||||
# 2. Frontend (başka terminal)
|
||||
cd frontend
|
||||
export REACT_APP_API_URL=http://localhost:8000
|
||||
npm start
|
||||
```
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Agent Script'inde Yanlış URL
|
||||
|
||||
**Sorun**: Agent script hala eski URL içeriyor
|
||||
|
||||
**Çözüm**:
|
||||
```bash
|
||||
# 1. Backend'deki değeri kontrol et
|
||||
docker exec haproxy-openmanager-backend env | grep PUBLIC_URL
|
||||
|
||||
# 2. Container'ı yeniden başlat
|
||||
docker-compose restart backend
|
||||
|
||||
# 3. Yeni script oluştur
|
||||
# UI'dan tekrar "Generate Install Script"
|
||||
```
|
||||
|
||||
### Frontend Backend'e Bağlanamıyor
|
||||
|
||||
**Sorun**: CORS hatası veya connection refused
|
||||
|
||||
**Çözüm**:
|
||||
```bash
|
||||
# 1. Frontend config'i kontrol et
|
||||
docker exec haproxy-openmanager-frontend env | grep REACT_APP_API_URL
|
||||
|
||||
# 2. Browser console'da kontrol et
|
||||
# [API Config] Base URL: http://localhost:8000
|
||||
|
||||
# 3. Network sekmesinde request URL'i kontrol et
|
||||
```
|
||||
|
||||
## 📖 En İyi Pratikler
|
||||
|
||||
### ✅ YAPILMASI GEREKENLER
|
||||
|
||||
1. **Her ortam için ayrı değerler**
|
||||
```
|
||||
Dev: PUBLIC_URL=http://localhost:8000
|
||||
Staging: PUBLIC_URL=https://staging.company.com
|
||||
Prod: PUBLIC_URL=https://prod.company.com
|
||||
```
|
||||
|
||||
2. **Template'i güncelle**
|
||||
- Yeni variable eklendiğinde `.env.template`'e ekle
|
||||
- Dokümantasyon ile birlikte
|
||||
|
||||
3. **Secrets kullan (Production)**
|
||||
```yaml
|
||||
# K8s Secret
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: backend-secret
|
||||
data:
|
||||
SECRET_KEY: <base64-encoded>
|
||||
```
|
||||
|
||||
### ❌ YAPILMAMASI GEREKENLER
|
||||
|
||||
1. **`.env` dosyasını commit etmeyin**
|
||||
```bash
|
||||
# Yanlış!
|
||||
git add .env
|
||||
|
||||
# Doğru!
|
||||
git add .env.template
|
||||
```
|
||||
|
||||
2. **Production secret'larını template'e koymayın**
|
||||
```bash
|
||||
# .env.template içinde YANLIŞLAR:
|
||||
SECRET_KEY=actual-production-secret-12345 ❌
|
||||
DATABASE_URL=postgresql://admin:realpass@prod-db ❌
|
||||
|
||||
# Doğru:
|
||||
SECRET_KEY=your-secret-key-change-this-in-production ✅
|
||||
DATABASE_URL=postgresql://user:pass@host:5432/db ✅
|
||||
```
|
||||
|
||||
3. **Hardcoded URL kullanmayın**
|
||||
```python
|
||||
# Yanlış!
|
||||
MANAGEMENT_URL = "https://my-server.com" ❌
|
||||
|
||||
# Doğru!
|
||||
MANAGEMENT_URL = os.getenv("PUBLIC_URL") ✅
|
||||
```
|
||||
|
||||
## 🆘 Yardım
|
||||
|
||||
Sorularınız için:
|
||||
- 📘 Bu dosya: `CONFIG.md`
|
||||
- 📗 Ana dokümantasyon: `README.md`
|
||||
- 📙 Template: `.env.template`
|
||||
|
||||
@@ -0,0 +1,172 @@
|
||||
# Agent Upgrade Guide - Dashboard Stats Fix
|
||||
|
||||
## Problem
|
||||
Dashboard showing 0 metrics after agent auto-upgrade due to missing environment variables (`SOCAT_BIN`, `STATS_SOCKET_PATH`) when agent restarts in daemon mode.
|
||||
|
||||
## Solution
|
||||
Implemented **lazy initialization** in both `get_haproxy_stats_csv()` and `get_server_statuses()` functions. These functions now initialize their dependencies on first call, making them completely independent of global variable initialization.
|
||||
|
||||
## Deployment Steps
|
||||
|
||||
### Step 1: Wait for Pipeline ⏳
|
||||
```bash
|
||||
# Pipeline is currently running after git push
|
||||
# Check status: https://[your-azure-devops]/pipeline
|
||||
# Wait for deployment to complete (~3-5 minutes)
|
||||
```
|
||||
|
||||
### Step 2: Verify Backend Deployment ✅
|
||||
```bash
|
||||
# Check backend logs for successful deployment
|
||||
kubectl logs -f deployment/backend -n haproxy-manager | head -20
|
||||
|
||||
# Expected: New pod started with latest code
|
||||
```
|
||||
|
||||
### Step 3: Update Agent Version in UI 🔄
|
||||
|
||||
**Option A: Automatic Script Sync (Recommended)**
|
||||
```bash
|
||||
# Get admin token
|
||||
TOKEN=$(curl -k -s -X POST "https://haproxy-manager.example.com/api/auth/login" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username": "admin", "password": "admin123"}' | jq -r '.access_token')
|
||||
|
||||
# Sync scripts from files to database (creates version 1.0.0)
|
||||
curl -k -X POST "https://haproxy-manager.example.com/api/agents/sync-scripts-from-files" \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
|
||||
# Expected: {"status": "success", "synced": ["linux", "macos"]}
|
||||
```
|
||||
|
||||
**Option B: Manual UI Update**
|
||||
1. Go to **Agent Management** page
|
||||
2. Click **Settings** → **Agent Versions**
|
||||
3. For **Linux** platform:
|
||||
- Click **Edit Script**
|
||||
- Version: Keep current or increment (e.g., 1.0.3)
|
||||
- Changelog: Add "Fixed stats collection after upgrade"
|
||||
- Click **Save** (this syncs file content to database)
|
||||
4. Repeat for **macOS** platform
|
||||
|
||||
### Step 4: Upgrade Agents 🚀
|
||||
|
||||
**Option A: UI (Single Agent)**
|
||||
1. Go to **Agent Management** page
|
||||
2. Select agent (e.g., `demo-agent`)
|
||||
3. Click **Upgrade** button
|
||||
4. Wait 30 seconds for agent to restart
|
||||
|
||||
**Option B: API (Batch Upgrade)**
|
||||
```bash
|
||||
# Get all agents
|
||||
curl -k -s -X GET "https://haproxy-manager.example.com/api/agents" \
|
||||
-H "Authorization: Bearer $TOKEN" | jq '.agents[] | {id, name, version}'
|
||||
|
||||
# Upgrade specific agent (replace {agent_id})
|
||||
curl -k -X POST "https://haproxy-manager.example.com/api/agents/{agent_id}/upgrade" \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
### Step 5: Verify Stats Collection 📊
|
||||
|
||||
**Backend Logs** (30 seconds after upgrade):
|
||||
```bash
|
||||
kubectl logs -f deployment/backend -n haproxy-manager | grep -E "haproxy_stats_csv|demo-agent"
|
||||
|
||||
# Expected logs:
|
||||
# ✅ "Has haproxy_stats_csv: True"
|
||||
# ✅ "CSV preview: IyBweG..." (base64 data)
|
||||
# ✅ "STATS: Parsed 15 rows for cluster demo-cluster1"
|
||||
```
|
||||
|
||||
**Agent Logs** (on agent server):
|
||||
```bash
|
||||
sudo tail -f /var/log/haproxy-agent/agent.log | grep STATS
|
||||
|
||||
# Expected logs:
|
||||
# ✅ "STATS: Initialized socat: /usr/bin/socat"
|
||||
# ✅ "STATS: Using default socket path: /var/run/haproxy/admin.sock"
|
||||
# ✅ "STATS: Fetched CSV: 2121 bytes, 9 lines, base64: 2828 chars"
|
||||
```
|
||||
|
||||
**Dashboard UI**:
|
||||
1. Open **Dashboard** page
|
||||
2. Refresh page (F5)
|
||||
3. Check metrics:
|
||||
- ✅ Frontend/Backend filters populated
|
||||
- ✅ Overview metrics showing real data (not 0)
|
||||
- ✅ Charts showing data points
|
||||
- ✅ "Waiting for Agent Data" warning gone
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Backend still shows "Has haproxy_stats_csv: False"
|
||||
|
||||
**Cause**: Agent hasn't upgraded yet or using old script version
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check agent version on agent server
|
||||
grep "AGENT_VERSION" /usr/local/bin/haproxy-agent | head -1
|
||||
|
||||
# Force agent restart
|
||||
sudo systemctl restart haproxy-agent
|
||||
|
||||
# Check logs immediately
|
||||
sudo tail -20 /var/log/haproxy-agent/agent.log
|
||||
```
|
||||
|
||||
### Issue: "STATS: socat not available"
|
||||
|
||||
**Cause**: socat not installed
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Install socat
|
||||
sudo yum install -y socat # RHEL/CentOS
|
||||
sudo apt install -y socat # Debian/Ubuntu
|
||||
|
||||
# Restart agent
|
||||
sudo systemctl restart haproxy-agent
|
||||
```
|
||||
|
||||
### Issue: "STATS: Socket not found: /var/run/haproxy/admin.sock"
|
||||
|
||||
**Cause**: HAProxy stats socket not configured
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check HAProxy config for stats socket
|
||||
grep "stats socket" /etc/haproxy/haproxy.cfg
|
||||
|
||||
# Add if missing (in global section):
|
||||
# stats socket /var/run/haproxy/admin.sock mode 666 level admin
|
||||
|
||||
# Reload HAProxy
|
||||
sudo systemctl reload haproxy
|
||||
```
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] Pipeline completed successfully
|
||||
- [ ] Backend pod restarted with new code
|
||||
- [ ] Agent scripts synced to database (version visible in UI)
|
||||
- [ ] Agents upgraded to new version
|
||||
- [ ] Backend logs show "Has haproxy_stats_csv: True"
|
||||
- [ ] Agent logs show STATS messages
|
||||
- [ ] Dashboard showing real metrics
|
||||
- [ ] Charts populated with data
|
||||
- [ ] No "Waiting for Agent Data" warning
|
||||
|
||||
## Next Upgrades
|
||||
|
||||
This fix is **permanent**. Future agent upgrades will NOT break stats collection because:
|
||||
|
||||
1. ✅ Functions are self-contained with lazy initialization
|
||||
2. ✅ No dependency on global variable initialization order
|
||||
3. ✅ Works in any restart scenario (systemd, daemon mode, upgrade)
|
||||
4. ✅ Backward compatible with existing agents
|
||||
|
||||
**No manual intervention needed for future upgrades!** 🎉
|
||||
|
||||
Reference in New Issue
Block a user