8a924f6091
Some checks failed
CD - Build & Deploy / build-and-push (push) Has been cancelled
CD - Build & Deploy / package-helm (push) Has been cancelled
CD - Build & Deploy / deploy-staging (push) Has been cancelled
CD - Build & Deploy / deploy-production (push) Has been cancelled
CD - Build & Deploy / release (push) Has been cancelled
CI / test (3.11) (push) Has been cancelled
CI / test (3.12) (push) Has been cancelled
CI / security (push) Has been cancelled
- Implemented Clean Architecture with Domain, Application, Infrastructure, Presentation layers - Added comprehensive project structure following SOLID principles - Created Kubernetes deployment with Helm charts (HPA, PDB, NetworkPolicy) - Configured ArgoCD for automated deployment (production + staging) - Implemented CI/CD pipeline with GitHub Actions - Added comprehensive documentation (handbook, architecture, coding standards) - Configured PostgreSQL, Redis, Celery for backend services - Created modern landing page with Persian fonts (Vazirmatn) - Added Docker multi-stage build for production - Configured development tools (pytest, black, flake8, mypy, isort) - Added pre-commit hooks for code quality - Implemented Makefile for common operations
450 lines
9.0 KiB
Markdown
450 lines
9.0 KiB
Markdown
# راهنمای Deployment روی Kubernetes با Helm
|
||
|
||
این راهنما نحوه deploy کردن پلتفرم Peikarband روی Kubernetes با استفاده از Helm Chart را توضیح میدهد.
|
||
|
||
## پیشنیازها
|
||
|
||
### 1. ابزارهای مورد نیاز
|
||
|
||
```bash
|
||
# Kubectl (v1.24+)
|
||
kubectl version --client
|
||
|
||
# Helm (v3.10+)
|
||
helm version
|
||
|
||
# Docker (برای build local)
|
||
docker --version
|
||
```
|
||
|
||
### 2. دسترسی به Kubernetes Cluster
|
||
|
||
```bash
|
||
# تست دسترسی
|
||
kubectl cluster-info
|
||
kubectl get nodes
|
||
```
|
||
|
||
### 3. Namespace ها
|
||
|
||
```bash
|
||
# ساخت namespace ها
|
||
kubectl create namespace production
|
||
kubectl create namespace staging
|
||
```
|
||
|
||
## ساختار Helm Chart
|
||
|
||
```
|
||
helm/peikarband/
|
||
├── Chart.yaml # Metadata
|
||
├── values.yaml # Default values
|
||
├── values-production.yaml # Production overrides
|
||
├── templates/
|
||
│ ├── _helpers.tpl # Helper templates
|
||
│ ├── deployment.yaml # Deployment
|
||
│ ├── service.yaml # Service
|
||
│ ├── ingress.yaml # Ingress
|
||
│ ├── configmap.yaml # ConfigMap
|
||
│ ├── serviceaccount.yaml
|
||
│ ├── hpa.yaml # Horizontal Pod Autoscaler
|
||
│ ├── pdb.yaml # Pod Disruption Budget
|
||
│ ├── networkpolicy.yaml
|
||
│ └── NOTES.txt
|
||
└── .helmignore
|
||
```
|
||
|
||
## مراحل Deployment
|
||
|
||
### 1. آمادهسازی Secrets
|
||
|
||
ابتدا باید secrets مورد نیاز را ایجاد کنید:
|
||
|
||
```bash
|
||
# Database credentials
|
||
kubectl create secret generic peikarband-secrets \
|
||
--from-literal=db-username=peikarband \
|
||
--from-literal=db-password=STRONG_PASSWORD_HERE \
|
||
--from-literal=redis-password=REDIS_PASSWORD_HERE \
|
||
-n production
|
||
|
||
# برای staging
|
||
kubectl create secret generic peikarband-secrets \
|
||
--from-literal=db-username=peikarband \
|
||
--from-literal=db-password=STAGING_PASSWORD \
|
||
--from-literal=redis-password=REDIS_PASSWORD \
|
||
-n staging
|
||
```
|
||
|
||
### 2. Build و Push Docker Image
|
||
|
||
#### روش اول: با GitHub Actions (توصیه میشود)
|
||
|
||
```bash
|
||
# فقط یک tag بزنید و GitHub Actions خودکار build و deploy میکند
|
||
git tag -a v0.1.0 -m "Release v0.1.0"
|
||
git push origin v0.1.0
|
||
```
|
||
|
||
#### روش دوم: Build دستی
|
||
|
||
```bash
|
||
# Build image
|
||
docker build -t peikarband/landing:0.1.0 .
|
||
|
||
# Tag for registry
|
||
docker tag peikarband/landing:0.1.0 registry.example.com/peikarband/landing:0.1.0
|
||
|
||
# Push
|
||
docker push registry.example.com/peikarband/landing:0.1.0
|
||
```
|
||
|
||
### 3. Validate Helm Chart
|
||
|
||
قبل از deploy، chart را validate کنید:
|
||
|
||
```bash
|
||
# Lint
|
||
helm lint helm/peikarband
|
||
|
||
# Dry-run
|
||
helm install peikarband-test ./helm/peikarband \
|
||
--dry-run \
|
||
--debug \
|
||
--namespace production
|
||
|
||
# Template rendering
|
||
helm template peikarband ./helm/peikarband > rendered.yaml
|
||
```
|
||
|
||
### 4. Deploy به Staging
|
||
|
||
```bash
|
||
helm upgrade --install peikarband-staging ./helm/peikarband \
|
||
--namespace staging \
|
||
--create-namespace \
|
||
--set image.repository=registry.example.com/peikarband/landing \
|
||
--set image.tag=0.1.0 \
|
||
--set ingress.hosts[0].host=staging.peikarband.ir \
|
||
--set replicaCount=2 \
|
||
--wait \
|
||
--timeout 5m
|
||
```
|
||
|
||
### 5. تست Staging
|
||
|
||
```bash
|
||
# چک کردن pods
|
||
kubectl get pods -n staging
|
||
|
||
# چک کردن logs
|
||
kubectl logs -f deployment/peikarband-staging -n staging
|
||
|
||
# Port forward برای تست local
|
||
kubectl port-forward svc/peikarband-staging 3000:3000 -n staging
|
||
|
||
# تست health check
|
||
curl http://localhost:8000/ping
|
||
```
|
||
|
||
### 6. Deploy به Production
|
||
|
||
```bash
|
||
helm upgrade --install peikarband-prod ./helm/peikarband \
|
||
--namespace production \
|
||
--create-namespace \
|
||
--set image.repository=registry.example.com/peikarband/landing \
|
||
--set image.tag=0.1.0 \
|
||
--values helm/peikarband/values-production.yaml \
|
||
--wait \
|
||
--timeout 10m
|
||
```
|
||
|
||
## پیکربندیهای مهم
|
||
|
||
### 1. تغییر تعداد Replicas
|
||
|
||
```bash
|
||
# با Helm
|
||
helm upgrade peikarband-prod ./helm/peikarband \
|
||
--namespace production \
|
||
--reuse-values \
|
||
--set replicaCount=5
|
||
|
||
# یا با kubectl
|
||
kubectl scale deployment peikarband-prod --replicas=5 -n production
|
||
```
|
||
|
||
### 2. Update Image Version
|
||
|
||
```bash
|
||
helm upgrade peikarband-prod ./helm/peikarband \
|
||
--namespace production \
|
||
--reuse-values \
|
||
--set image.tag=0.2.0
|
||
```
|
||
|
||
### 3. تغییر Resources
|
||
|
||
```bash
|
||
helm upgrade peikarband-prod ./helm/peikarband \
|
||
--namespace production \
|
||
--reuse-values \
|
||
--set resources.limits.cpu=2000m \
|
||
--set resources.limits.memory=2Gi
|
||
```
|
||
|
||
### 4. فعال/غیرفعال کردن Autoscaling
|
||
|
||
```bash
|
||
# فعال کردن
|
||
helm upgrade peikarband-prod ./helm/peikarband \
|
||
--namespace production \
|
||
--reuse-values \
|
||
--set autoscaling.enabled=true \
|
||
--set autoscaling.minReplicas=3 \
|
||
--set autoscaling.maxReplicas=10
|
||
|
||
# غیرفعال کردن
|
||
helm upgrade peikarband-prod ./helm/peikarband \
|
||
--namespace production \
|
||
--reuse-values \
|
||
--set autoscaling.enabled=false \
|
||
--set replicaCount=3
|
||
```
|
||
|
||
## Ingress و SSL/TLS
|
||
|
||
### نصب cert-manager (برای Let's Encrypt)
|
||
|
||
```bash
|
||
# نصب cert-manager
|
||
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
|
||
|
||
# ساخت ClusterIssuer
|
||
cat <<EOF | kubectl apply -f -
|
||
apiVersion: cert-manager.io/v1
|
||
kind: ClusterIssuer
|
||
metadata:
|
||
name: letsencrypt-prod
|
||
spec:
|
||
acme:
|
||
server: https://acme-v02.api.letsencrypt.org/directory
|
||
email: admin@peikarband.ir
|
||
privateKeySecretRef:
|
||
name: letsencrypt-prod
|
||
solvers:
|
||
- http01:
|
||
ingress:
|
||
class: nginx
|
||
EOF
|
||
```
|
||
|
||
### پیکربندی DNS
|
||
|
||
```bash
|
||
# A Record برای domain اصلی
|
||
peikarband.ir. A YOUR_CLUSTER_IP
|
||
|
||
# CNAME برای www
|
||
www.peikarband.ir. CNAME peikarband.ir.
|
||
```
|
||
|
||
## Monitoring و Logs
|
||
|
||
### 1. مشاهده Logs
|
||
|
||
```bash
|
||
# تمام pods
|
||
kubectl logs -f deployment/peikarband-prod -n production
|
||
|
||
# یک pod خاص
|
||
kubectl logs -f peikarband-prod-xxxxx-yyyyy -n production
|
||
|
||
# تمام logs (از همه pods)
|
||
kubectl logs -l app.kubernetes.io/name=peikarband -n production --tail=100
|
||
```
|
||
|
||
### 2. مشاهده Events
|
||
|
||
```bash
|
||
kubectl get events -n production --sort-by='.lastTimestamp'
|
||
```
|
||
|
||
### 3. چک کردن Resource Usage
|
||
|
||
```bash
|
||
# CPU و Memory
|
||
kubectl top pods -n production
|
||
|
||
# Metrics از deployment
|
||
kubectl top deployment peikarband-prod -n production
|
||
```
|
||
|
||
### 4. HPA Status
|
||
|
||
```bash
|
||
kubectl get hpa -n production
|
||
kubectl describe hpa peikarband-prod -n production
|
||
```
|
||
|
||
## Rollback
|
||
|
||
### 1. مشاهده History
|
||
|
||
```bash
|
||
# Helm releases
|
||
helm history peikarband-prod -n production
|
||
|
||
# Kubernetes rollout history
|
||
kubectl rollout history deployment/peikarband-prod -n production
|
||
```
|
||
|
||
### 2. Rollback با Helm
|
||
|
||
```bash
|
||
# به نسخه قبلی
|
||
helm rollback peikarband-prod -n production
|
||
|
||
# به نسخه خاص
|
||
helm rollback peikarband-prod 3 -n production
|
||
```
|
||
|
||
### 3. Rollback با Kubectl
|
||
|
||
```bash
|
||
# به نسخه قبلی
|
||
kubectl rollout undo deployment/peikarband-prod -n production
|
||
|
||
# به نسخه خاص
|
||
kubectl rollout undo deployment/peikarband-prod --to-revision=2 -n production
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
### Pod در حالت Pending
|
||
|
||
```bash
|
||
# بررسی events
|
||
kubectl describe pod POD_NAME -n production
|
||
|
||
# چک کردن resources
|
||
kubectl describe nodes
|
||
```
|
||
|
||
### Pod در حالت CrashLoopBackOff
|
||
|
||
```bash
|
||
# مشاهده logs
|
||
kubectl logs POD_NAME -n production --previous
|
||
|
||
# مشاهده events
|
||
kubectl describe pod POD_NAME -n production
|
||
```
|
||
|
||
### Image Pull Error
|
||
|
||
```bash
|
||
# چک کردن imagePullSecrets
|
||
kubectl get secrets -n production
|
||
|
||
# بررسی pod
|
||
kubectl describe pod POD_NAME -n production
|
||
```
|
||
|
||
### Health Check Failing
|
||
|
||
```bash
|
||
# تست مستقیم health endpoint
|
||
kubectl exec -it POD_NAME -n production -- curl localhost:8000/ping
|
||
|
||
# بررسی liveness/readiness probes
|
||
kubectl describe pod POD_NAME -n production
|
||
```
|
||
|
||
## Clean Up
|
||
|
||
### حذف Release
|
||
|
||
```bash
|
||
# حذف کامل
|
||
helm uninstall peikarband-prod -n production
|
||
|
||
# با نگه داشتن history
|
||
helm uninstall peikarband-prod -n production --keep-history
|
||
```
|
||
|
||
### حذف Namespace
|
||
|
||
```bash
|
||
kubectl delete namespace production
|
||
```
|
||
|
||
## Best Practices
|
||
|
||
### 1. Always use specific image tags
|
||
```yaml
|
||
image:
|
||
tag: "v0.1.0" # ✅ Good
|
||
# tag: "latest" # ❌ Bad
|
||
```
|
||
|
||
### 2. Set resource limits
|
||
```yaml
|
||
resources:
|
||
limits:
|
||
cpu: 1000m
|
||
memory: 1Gi
|
||
requests:
|
||
cpu: 250m
|
||
memory: 512Mi
|
||
```
|
||
|
||
### 3. Enable autoscaling برای production
|
||
```yaml
|
||
autoscaling:
|
||
enabled: true
|
||
minReplicas: 3
|
||
maxReplicas: 10
|
||
```
|
||
|
||
### 4. استفاده از Pod Disruption Budget
|
||
```yaml
|
||
podDisruptionBudget:
|
||
enabled: true
|
||
minAvailable: 1
|
||
```
|
||
|
||
### 5. NetworkPolicy برای امنیت
|
||
```yaml
|
||
networkPolicy:
|
||
enabled: true
|
||
```
|
||
|
||
## CI/CD Integration
|
||
|
||
### GitHub Actions
|
||
|
||
workflow ما به صورت خودکار:
|
||
|
||
1. ✅ Build Docker image
|
||
2. ✅ Push به registry
|
||
3. ✅ Package Helm chart
|
||
4. ✅ Deploy به staging (on push to main)
|
||
5. ✅ Deploy به production (on tag)
|
||
6. ✅ Create GitHub release
|
||
|
||
### Manual Trigger
|
||
|
||
```bash
|
||
# از طریق GitHub UI: Actions → CD → Run workflow
|
||
```
|
||
|
||
## Support
|
||
|
||
برای مشکلات و سوالات:
|
||
- 📧 Email: support@peikarband.ir
|
||
- 💬 Telegram: @peikarband_support
|
||
- 📚 Docs: https://docs.peikarband.ir
|
||
|