peikarband/peikarband/docs/deployment/kubernetes.md

راهنمای Deployment روی Kubernetes با Helm

این راهنما نحوه deploy کردن پلتفرم Peikarband روی Kubernetes با استفاده از Helm Chart را توضیح می‌دهد.

پیش‌نیازها

1. ابزارهای مورد نیاز

# Kubectl (v1.24+)
kubectl version --client

# Helm (v3.10+)
helm version

# Docker (برای build local)
docker --version

2. دسترسی به Kubernetes Cluster

# تست دسترسی
kubectl cluster-info
kubectl get nodes

3. Namespace ها

# ساخت 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 مورد نیاز را ایجاد کنید:

# 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 (توصیه می‌شود)

# فقط یک tag بزنید و GitHub Actions خودکار build و deploy می‌کند
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

روش دوم: Build دستی

# 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 کنید:

# 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

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

# چک کردن 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

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

# با 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

helm upgrade peikarband-prod ./helm/peikarband \
  --namespace production \
  --reuse-values \
  --set image.tag=0.2.0

3. تغییر Resources

helm upgrade peikarband-prod ./helm/peikarband \
  --namespace production \
  --reuse-values \
  --set resources.limits.cpu=2000m \
  --set resources.limits.memory=2Gi

4. فعال/غیرفعال کردن Autoscaling

# فعال کردن
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)

# نصب 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

# A Record برای domain اصلی
peikarband.ir.         A     YOUR_CLUSTER_IP

# CNAME برای www
www.peikarband.ir.     CNAME peikarband.ir.

Monitoring و Logs

1. مشاهده Logs

# تمام 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

kubectl get events -n production --sort-by='.lastTimestamp'

3. چک کردن Resource Usage

# CPU و Memory
kubectl top pods -n production

# Metrics از deployment
kubectl top deployment peikarband-prod -n production

4. HPA Status

kubectl get hpa -n production
kubectl describe hpa peikarband-prod -n production

Rollback

1. مشاهده History

# Helm releases
helm history peikarband-prod -n production

# Kubernetes rollout history
kubectl rollout history deployment/peikarband-prod -n production

2. Rollback با Helm

# به نسخه قبلی
helm rollback peikarband-prod -n production

# به نسخه خاص
helm rollback peikarband-prod 3 -n production

3. Rollback با Kubectl

# به نسخه قبلی
kubectl rollout undo deployment/peikarband-prod -n production

# به نسخه خاص
kubectl rollout undo deployment/peikarband-prod --to-revision=2 -n production

Troubleshooting

Pod در حالت Pending

# بررسی events
kubectl describe pod POD_NAME -n production

# چک کردن resources
kubectl describe nodes

Pod در حالت CrashLoopBackOff

# مشاهده logs
kubectl logs POD_NAME -n production --previous

# مشاهده events
kubectl describe pod POD_NAME -n production

Image Pull Error

# چک کردن imagePullSecrets
kubectl get secrets -n production

# بررسی pod
kubectl describe pod POD_NAME -n production

Health Check Failing

# تست مستقیم 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

# حذف کامل
helm uninstall peikarband-prod -n production

# با نگه داشتن history
helm uninstall peikarband-prod -n production --keep-history

حذف Namespace

kubectl delete namespace production

Best Practices

1. Always use specific image tags

image:
  tag: "v0.1.0"  # ✅ Good
  # tag: "latest"  # ❌ Bad

2. Set resource limits

resources:
  limits:
    cpu: 1000m
    memory: 1Gi
  requests:
    cpu: 250m
    memory: 512Mi

3. Enable autoscaling برای production

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10

4. استفاده از Pod Disruption Budget

podDisruptionBudget:
  enabled: true
  minAvailable: 1

5. NetworkPolicy برای امنیت

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

# از طریق GitHub UI: Actions → CD → Run workflow

Support

برای مشکلات و سوالات:

• 📧 Email: support@peikarband.ir
• 💬 Telegram: @peikarband_support
• 📚 Docs: https://docs.peikarband.ir