236 lines
6.4 KiB
Markdown
236 lines
6.4 KiB
Markdown
# Demo Nginx Documentation
|
||
|
||
Документация для demo-nginx deployment с автоматическим и ручным rollback.
|
||
|
||
---
|
||
|
||
## 📚 Available Documentation
|
||
|
||
### [ROLLBACK_MANUAL.md](./ROLLBACK_MANUAL.md)
|
||
**Comprehensive Manual Rollback Guide**
|
||
|
||
Полная документация по функции ручного rollback:
|
||
- 3 способа rollback (IMAGE_TAG, REVISION, GIT_COMMIT)
|
||
- Setup guide
|
||
- Troubleshooting со всеми fixes
|
||
- Best practices
|
||
- Examples
|
||
- FAQ
|
||
|
||
**When to use:** Нужна детальная информация или troubleshooting
|
||
|
||
---
|
||
|
||
### [ROLLBACK_QUICK_REF.md](./ROLLBACK_QUICK_REF.md)
|
||
**Quick Reference Card**
|
||
|
||
Краткая справка для быстрого использования:
|
||
- Quick start (2 минуты)
|
||
- 3 способа rollback
|
||
- Emergency procedure
|
||
- Verification commands
|
||
- Checklist
|
||
|
||
**When to use:** Быстрый rollback в production
|
||
|
||
---
|
||
|
||
## 🎯 Quick Links
|
||
|
||
### Rollback Feature
|
||
- **Full Guide:** [ROLLBACK_MANUAL.md](./ROLLBACK_MANUAL.md)
|
||
- **Quick Ref:** [ROLLBACK_QUICK_REF.md](./ROLLBACK_QUICK_REF.md)
|
||
- **Jenkinsfile:** [Jenkinsfile.rollback](../Jenkinsfile.rollback)
|
||
- **CI/CD Guide:** [../../../CICD_GUIDE.md](../../../CICD_GUIDE.md)
|
||
|
||
### Related Resources
|
||
- **Jenkins RBAC:** [apps/jenkins/rbac.yaml](../../jenkins/rbac.yaml)
|
||
- **Deployment:** [deployment.yaml](../deployment.yaml)
|
||
- **Main CI/CD:** [Jenkinsfile](../Jenkinsfile)
|
||
|
||
---
|
||
|
||
## 🚀 Quick Start
|
||
|
||
### Manual Rollback (2 minutes)
|
||
|
||
```
|
||
1. Jenkins → demo-nginx-rollback
|
||
2. IMAGE_TAG + main-21
|
||
3. SKIP_HEALTH_CHECK: true
|
||
4. Build
|
||
```
|
||
|
||
See [ROLLBACK_QUICK_REF.md](./ROLLBACK_QUICK_REF.md) for details.
|
||
|
||
---
|
||
|
||
### Emergency Rollback (30 seconds)
|
||
|
||
```bash
|
||
kubectl rollout undo deployment/demo-nginx -n demo-app
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Features Summary
|
||
|
||
### Manual Rollback
|
||
✅ 3 rollback methods (IMAGE_TAG, REVISION, GIT_COMMIT)
|
||
✅ GitOps sync (auto-commit to Git)
|
||
✅ Zero downtime (rolling updates)
|
||
✅ DRY_RUN mode (safe testing)
|
||
✅ Full RBAC permissions
|
||
✅ Input validation (auto-trim)
|
||
✅ Retry logic (5 attempts)
|
||
⚠️ Health check optional (use SKIP_HEALTH_CHECK=true)
|
||
|
||
### Automatic Rollback
|
||
✅ Triggered on deployment failure
|
||
✅ Saves previous state
|
||
✅ Kubernetes rollback
|
||
✅ Git revert
|
||
✅ Health checks
|
||
✅ Timeout protection
|
||
|
||
---
|
||
|
||
## 🐛 All Fixes Applied
|
||
|
||
| # | Issue | Fix | Status | Doc |
|
||
|---|-------|-----|--------|-----|
|
||
| 1 | Container name | Use `nginx` | ✅ | [Link](./ROLLBACK_MANUAL.md#issue-1-container-name-error--fixed) |
|
||
| 2 | Whitespace | Auto-trim | ✅ | [Link](./ROLLBACK_MANUAL.md#issue-2-whitespace-in-input--fixed) |
|
||
| 3 | RBAC | pods/exec perm | ✅ | [Link](./ROLLBACK_MANUAL.md#issue-3-rbac-permissions--fixed) |
|
||
| 4 | Health timing | SKIP option | ⚠️ | [Link](./ROLLBACK_MANUAL.md#issue-4-health-check-timing--workaround) |
|
||
| 5 | Bash loop | Explicit list | ✅ | [Link](./ROLLBACK_MANUAL.md#issue-5-bash-loop-syntax--fixed) |
|
||
|
||
---
|
||
|
||
## 💡 Recommended Reading Order
|
||
|
||
### For New Users:
|
||
1. Start → [ROLLBACK_QUICK_REF.md](./ROLLBACK_QUICK_REF.md)
|
||
2. Practice → Follow quick start
|
||
3. Deep Dive → [ROLLBACK_MANUAL.md](./ROLLBACK_MANUAL.md)
|
||
|
||
### For Troubleshooting:
|
||
1. Check → [ROLLBACK_MANUAL.md - Troubleshooting](./ROLLBACK_MANUAL.md#troubleshooting--fixes)
|
||
2. Verify → [ROLLBACK_QUICK_REF.md - Verification](./ROLLBACK_QUICK_REF.md#-verify-rollback)
|
||
3. Support → [ROLLBACK_MANUAL.md - Support](./ROLLBACK_MANUAL.md#support)
|
||
|
||
### For Emergency:
|
||
1. Fast → [ROLLBACK_QUICK_REF.md - Emergency](./ROLLBACK_QUICK_REF.md#-emergency-rollback-30-seconds)
|
||
2. Alternative → [ROLLBACK_MANUAL.md - Emergency](./ROLLBACK_MANUAL.md#emergency-rollback-procedure)
|
||
|
||
---
|
||
|
||
## 🎓 Key Concepts
|
||
|
||
### Rollback Methods Comparison
|
||
|
||
| Method | Speed | Precision | Use Case |
|
||
|--------|-------|-----------|----------|
|
||
| IMAGE_TAG | ⚡⚡⚡ | 🎯 High | Known build number |
|
||
| REVISION | ⚡⚡ | 🎯 Medium | Recent rollback |
|
||
| GIT_COMMIT | ⚡ | 🎯🎯 High | Exact code state |
|
||
|
||
### When to Use What
|
||
|
||
**Use IMAGE_TAG when:**
|
||
- You know the build number (main-21)
|
||
- Quick rollback needed
|
||
- Most common scenario
|
||
|
||
**Use REVISION_NUMBER when:**
|
||
- Need to go back N versions
|
||
- Don't remember exact tag
|
||
- Working with kubectl history
|
||
|
||
**Use GIT_COMMIT when:**
|
||
- Need exact code state
|
||
- Multiple changes in one build
|
||
- Precise rollback required
|
||
|
||
---
|
||
|
||
## 📈 Monitoring
|
||
|
||
### Check Rollback Status
|
||
|
||
```bash
|
||
# Deployment status
|
||
kubectl get deployment demo-nginx -n demo-app
|
||
|
||
# Pod status
|
||
kubectl get pods -n demo-app -l app=demo-nginx
|
||
|
||
# Rollout history
|
||
kubectl rollout history deployment/demo-nginx -n demo-app
|
||
|
||
# ArgoCD status
|
||
kubectl get application demo-nginx -n argocd
|
||
```
|
||
|
||
### Grafana Queries
|
||
|
||
```promql
|
||
# Rollback count
|
||
sum(increase(deployment_rollback_total[1h])) by (deployment)
|
||
|
||
# Rollback rate
|
||
rate(deployment_rollback_total[5m])
|
||
```
|
||
|
||
---
|
||
|
||
## ❓ FAQ
|
||
|
||
### Q: Какой метод rollback использовать?
|
||
**A:** Для большинства случаев используй IMAGE_TAG - самый быстрый и простой.
|
||
|
||
### Q: Health check всегда падает, это баг?
|
||
**A:** Нет, это timing issue во время rolling update. Используй `SKIP_HEALTH_CHECK: true` и проверь вручную через минуту.
|
||
|
||
### Q: Как быстро откатиться в emergency?
|
||
**A:** Используй `kubectl rollout undo` (30 секунд) или Jenkins с SKIP_HEALTH_CHECK (2 минуты).
|
||
|
||
### Q: Где полная документация?
|
||
**A:** [ROLLBACK_MANUAL.md](./ROLLBACK_MANUAL.md) - comprehensive guide со всеми details.
|
||
|
||
---
|
||
|
||
## 🆘 Support
|
||
|
||
**Need Help?**
|
||
|
||
1. Check [ROLLBACK_MANUAL.md - Troubleshooting](./ROLLBACK_MANUAL.md#troubleshooting--fixes)
|
||
2. Review [ROLLBACK_MANUAL.md - FAQ](./ROLLBACK_MANUAL.md#faq)
|
||
3. Check Jenkins console output
|
||
4. Verify RBAC permissions
|
||
5. Review pod status and logs
|
||
|
||
**Still stuck?**
|
||
- Jenkins logs: Jenkins → Build → Console Output
|
||
- K8s events: `kubectl get events -n demo-app`
|
||
- Pod logs: `kubectl logs -n demo-app -l app=demo-nginx`
|
||
|
||
---
|
||
|
||
## 📝 Documentation Updates
|
||
|
||
**Last Updated:** 2026-01-06
|
||
**Version:** 1.0
|
||
**Status:** Production Ready ✅
|
||
|
||
**Recent Changes:**
|
||
- ✅ Added comprehensive manual rollback guide
|
||
- ✅ Added quick reference card
|
||
- ✅ Documented all 5 fixes
|
||
- ✅ Added examples and best practices
|
||
- ✅ Production-ready feature
|
||
|
||
---
|
||
|
||
**Ready to rollback? Start with [Quick Reference](./ROLLBACK_QUICK_REF.md)! 🚀**
|