{
  "title": "حاکمیت استقرار Kubernetes",
  "slug": "team/devops/kubernetes-deployment-governance",
  "url": "/docs/team/devops/kubernetes-deployment-governance",
  "frontmatter": {
    "layout": "doc",
    "title": "حاکمیت استقرار Kubernetes",
    "description": "قوانین مالکیت، نام‌گذاری، ارتقاء و بازگشت استقرار در Kubernetes",
    "version": "1.0.0",
    "status": "APPROVED",
    "author": "Antigravity",
    "owner": "Devops Team",
    "created_at": "2026-06-15",
    "updated_at": "2026-06-15",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "حاکمیت استقرار Kubernetes",
      "content": "**Kubernetes Deployment Governance**\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. مدل مالکیت استقرار",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۱.۱ Ownership Matrix",
      "content": "| سرویس | Namespace | تیم مالک | Helm Release Name |\n|-------|-----------|---------|-------------------|\n| Gateway (Traefik) | `nons-system` | Devops | `nons-gateway` |\n| Auth Service | `nons-platform` | Backend | `nons-auth-service` |\n| PostgreSQL | `nons-platform` | Devops | `nons-postgres` |\n| Redis | `nons-platform` | Devops | `nons-redis` |\n| NATS | `nons-platform` | Devops | `nons-nats` |\n| Kratos | `nons-platform` | Backend | `nons-kratos` |\n| Hydra | `nons-platform` | Backend | `nons-hydra` |\n| Core (Go) | `nons-platform` | Backend | `nons-core` |\n| MongoDB | `nons-platform` | Backend | `nons-mongo` (آینده) |\n| TigerBeetle | `nons-platform` | Backend | `nons-tigerbeetle` (آینده) |"
    },
    {
      "level": 3,
      "heading": "۱.۲ قوانین Ownership",
      "content": "| قانون | توضیح |\n|-------|-------|\n| هر سرویس یک تیم مالک دارد | تیم مالک مسئول استقرار، مانیتورینگ و رفع باگ است |\n| Namespace اشتراکی | سرویس‌های platform در `nons-platform`، زیرساخت در `nons-system` |\n| تیم Devops مالک زیرساخت | Gateway، دیتابیس‌ها، messaging — مگر اینکه سرویس تخصصی باشد |\n| تیم Backend مالک سرویس | تمام سرویس‌های تخصصی (auth, order, payment, ...) |\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. قوانین Namespace",
      "content": "| Namespace | هدف | سطح دسترسی | RBAC |\n|-----------|-----|-----------|------|\n| `nons-system` | زیرساخت (Gateway) | Devops Only | Admin, View |\n| `nons-platform` | سرویس‌های اصلی | Backend + Devops | Admin, Edit, View |\n| `nons-services` | سرویس‌های آینده | Backend + Devops | Admin, Edit, View |\n| `nons-monitoring` | Monitoring Stack (آینده) | Devops Only | Admin, View |\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. Helm Release Naming",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۳.۱ الگوی نام",
      "content": "```\nnons-{service-name}\n```\n\n| مؤلفه | قانون | مثال |\n|-------|-------|------|\n| پیشوند | `nons-` | `nons-auth-service` |\n| نام سرویس | دقیقاً مطابق دایرکتوری سرویس | `auth-service` |\n| خط تیره | جداکننده کلمات | `auth-service` |\n| حرف بزرگ | ممنوع | `nons-auth-service` ✅ \\| `nons-Auth-Service` ❌ |"
    },
    {
      "level": 3,
      "heading": "۳.۲ ثبت Helm Release",
      "content": "```bash\nhelm install nons-auth-service ./deploy/helm/auth-service \\\n  -n nons-platform \\\n  -f ./deploy/environments/local/values.yaml\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. استراتژی ارتقاء (Upgrade Strategy)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۴.۱ Rolling Update",
      "content": "| پارامتر | مقدار | دلیل |\n|---------|-------|------|\n| استراتژی | `RollingUpdate` | پیش‌فرض — بدون Downtime |\n| maxUnavailable | 0 | جلوگیری از قطعی کامل |\n| maxSurge | 1 | یک پاد اضافه قبل از حذف قدیمی |\n| minReadySeconds | 10 | زمان انتظار برای آماده‌شدن پاد جدید |\n\n```yaml\nstrategy:\n  type: RollingUpdate\n  rollingUpdate:\n    maxUnavailable: 0\n    maxSurge: 1\n  minReadySeconds: 10\n```"
    },
    {
      "level": 3,
      "heading": "۴.2 امنیت ارتقاء",
      "content": "| قانون | توضیح |\n|-------|-------|\n| Health Check | readinessProbe + livenessProbe برای همه deployments |\n| Pre-stop Hook | SIGTERM + graceful shutdown (حداقل ۱۰ ثانیه) |\n| Pod Disruption Budget | حداقل ۱ پاد همیشه در دسترس (برای multi-replica) |\n| Resource Limits | CPU/Memory limits برای همه کانتینرها |\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. استراتژی بازگشت (Rollback Strategy)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۵.۱ Helm Rollback",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "مشاهده تاریخچه",
      "content": "helm history nons-auth-service -n nons-platform"
    },
    {
      "level": 1,
      "heading": "بازگشت به Revision قبلی",
      "content": "helm rollback nons-auth-service <REVISION> -n nons-platform"
    },
    {
      "level": 1,
      "heading": "بازگشت با timeout بیشتر",
      "content": "helm rollback nons-auth-service <REVISION> -n nons-platform --timeout 5m\n```"
    },
    {
      "level": 3,
      "heading": "۵.۲ Kubectl Rollout",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "بازگشت Deployment",
      "content": "kubectl rollout undo deployment/nons-auth-service -n nons-platform"
    },
    {
      "level": 1,
      "heading": "بازگشت به Revision مشخص",
      "content": "kubectl rollout undo deployment/nons-auth-service -n nons-platform --to-revision=<REVISION>"
    },
    {
      "level": 1,
      "heading": "بررسی وضعیت Rollout",
      "content": "kubectl rollout status deployment/nons-auth-service -n nons-platform\n```"
    },
    {
      "level": 3,
      "heading": "۵.۳ قوانین Rollback",
      "content": "| قانون | توضیح |\n|-------|-------|\n| بازگشت فوری | در صورت Failed health check بعد از upgrade |\n| حداکثر زمان | ۵ دقیقه timeout برای rollback |\n| بررسی پس از بازگشت | Health check + log check بعد از rollback |\n| ثبت علت | مستندسازی دلیل بازگشت در incident report |\n| Revision limit | نگهداری حداقل ۱۰ revision اخیر در Helm |\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. انتظارات سازگاری نسخه (Version Compatibility)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۶.۱ قوانین",
      "content": "| مؤلفه | قانون |\n|-------|-------|\n| سرویس A ← سرویس B | MAJOR سرویس B باید با MAJOR مورد انتظار سرویس A مطابقت داشته باشد |\n| Helm Chart ← Image | Chart در `values.yaml` محدوده `image.tag` را مشخص نمی‌کند — محیط تعیین می‌کند |\n| Proto ← Binding | نسخه Binding با نسخه Proto هماهنگ است (توسط Buf) |\n| API Version | همیشه در مسیر URL: `/v1/`, `/v2/` |"
    },
    {
      "level": 3,
      "heading": "۶.۲ Breaking Change Detection",
      "content": "| مکانیسم | ابزار | زمان |\n|---------|-------|------|\n| Proto Compatibility | `buf breaking` | هر PR روی `contracts/` |\n| API Compatibility | تست‌های integration | هر PR |\n| SemVer Enforcement | Code Review | هر PR |\n\n---"
    },
    {
      "level": 2,
      "heading": "۷. استقرار به ازای محیط",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۷.۱ Development (K3d)",
      "content": "```bash\nk3d image import nons-auth-service:latest -c nons\nhelm upgrade --install nons-auth-service ./deploy/helm/auth-service \\\n  --set image.tag=latest \\\n  --set image.pullPolicy=Never \\\n  -n nons-platform \\\n  -f ./deploy/environments/local/values.yaml\n```"
    },
    {
      "level": 3,
      "heading": "۷.۲ Staging",
      "content": "```bash\nhelm upgrade --install nons-auth-service ./deploy/helm/auth-service \\\n  --set image.tag=sha-a1b2c3d4 \\\n  -n nons-platform \\\n  -f ./deploy/environments/staging/values.yaml\n```"
    },
    {
      "level": 3,
      "heading": "۷.۳ Production",
      "content": "```bash\nhelm upgrade --install nons-auth-service ./deploy/helm/auth-service \\\n  --set image.tag=1.2.0 \\\n  -n nons-platform \\\n  -f ./deploy/environments/production/values.yaml\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۸. RBAC و دسترسی",
      "content": "| نقش | دسترسی | تیم |\n|-----|---------|-----|\n| Cluster Admin | Full cluster | Devops Team |\n| Namespace Admin | Full namespace | Backend Team (در namespace خود) |\n| Deployer | `helm install/upgrade/rollback` | CI/CD Pipeline (ServiceAccount) |\n| Viewer | `kubectl get/logs/describe` | همه تیم‌ها |\n\n---"
    },
    {
      "level": 2,
      "heading": "۹. خلاصه",
      "content": "| حوزه | تصمیم |\n|------|--------|\n| Helm Release Name | `nons-{service-name}` |\n| Namespaces | `nons-system`, `nons-platform`, `nons-services`, `nons-monitoring` |\n| Upgrade Strategy | RollingUpdate (maxUnavailable: 0, maxSurge: 1) |\n| Rollback | `helm rollback` + `kubectl rollout undo` |\n| Revision History | حداقل ۱۰ revision |\n| Breaking Change | `buf breaking` + تست integration + Code Review |\n| Environment Values | `deploy/environments/{env}/values.yaml` |"
    }
  ]
}