{
  "title": "معماری مدیریت اسرار",
  "slug": "team/devops/secret-management-architecture",
  "url": "/docs/team/devops/secret-management-architecture",
  "frontmatter": {
    "layout": "doc",
    "title": "معماری مدیریت اسرار",
    "description": "تعریف معماری رسمی مدیریت Secrets — مرز GitHub/Kubernetes/Vault، چرخه حیات و مالکیت",
    "version": "1.0.0",
    "status": "PRIVATE",
    "author": "Antigravity",
    "owner": "Devops Team",
    "created_at": "2026-06-16",
    "updated_at": "2026-06-16",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "معماری مدیریت اسرار",
      "content": "**Secret Management Architecture**\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. اصول معماری",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۱.۱ قوانین طلایی",
      "content": "1. **هیچ رازی در Repository ذخیره نمی‌شود** — نه در کد، نه در config، نه در Dockerfile.\n2. **هر راز یک منبع حقیقت واحد دارد** — GitHub Secrets برای CI، K8s Secrets برای Runtime.\n3. **دسترسی به رازها بر اساس Least Privilege** — هر سرویس فقط به رازهای خود دسترسی دارد.\n4. **چرخه حیات رازها مدیریت می‌شود** — ایجاد، چرخش، انقضا و حذف.\n5. **در محیط توسعه، مقادیر پیش‌فرض مجاز است** — اما `.env.example` فقط placeholder داشته باشد."
    },
    {
      "level": 3,
      "heading": "۱.۲ مدل لایه‌ای (Layered Model)",
      "content": "```\n+----------------------------+\n| GitHub Secrets             |  ← لایه CI: Tokenهای دسترسی به Registry، Deployment\n+----------------------------+\n| Kubernetes Secrets         |  ← لایه Runtime: Passwordها، API Keyها، Session Secrets\n+----------------------------+\n| External Secrets Operator  |  ← لایه Sync (فاز ۲): همگام‌سازی خودکار از Vault به K8s\n+----------------------------+\n| HashiCorp Vault            |  ← لایه نهایی (فاز ۳): منبع حقیقت تمام رازها\n+----------------------------+\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. مرزهای ذخیره‌سازی (Storage Boundaries)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۲.۱ چه اطلاعاتی در GitHub نگهداری می‌شود",
      "content": "| راز | Scope | GitHub Environment | توضیح |\n|-----|-------|-------------------|-------|\n| `REGISTRY_USERNAME` | CI | `staging`, `production` | <span v-pre>${{ github.actor }}</span> |\n| `REGISTRY_TOKEN` | CI | `staging`, `production` | PAT با scopes `write:packages`, `delete:packages` |\n| `K3S_KUBECONFIG` | CI | `production` | Kubeconfig برای استقرار روی K3s |\n| `WEBHOOK_SECRET` | CI | `production` | Token امن وب‌هوک Kratos |\n| `SLACK_WEBHOOK` | CI | `production` | Webhook برای اعلان خطاهای CI |\n\n**قوانین GitHub Secrets:**\n\n| قانون | توضیح |\n|-------|-------|\n| Environment Protection | Production نیازمند required reviewer + wait timer |\n| Shared Secrets ممنوع | هر سرویس Environment مجزا ندارد — از Repository secrets استفاده نشود |\n| Rotation | حداقل هر ۹۰ روز یکبار |\n| Audit | تغییرات از طریق GitHub Audit Log قابل ردیابی باشد |"
    },
    {
      "level": 3,
      "heading": "۲.۲ چه اطلاعاتی در Kubernetes نگهداری می‌شود",
      "content": "| Secret | Namespace | سرویس‌های مصرف‌کننده | Type |\n|--------|-----------|---------------------|------|\n| `postgres-credentials` | `nons-platform` | Kratos, Hydra, Core | `Opaque` |\n| `kratos-config` | `nons-platform` | Kratos | `Opaque` |\n| `hydra-config` | `nons-platform` | Hydra | `Opaque` |\n| `auth-service-env` | `nons-platform` | Auth Service | `Opaque` |\n| `ghcr-pull` | `nons-platform` | همه سرویس‌ها | `docker-registry` |\n| `nats-config` | `nons-platform` | Core, Auth Service | `Opaque` |\n\n**نمونه Manifest:**\n\n```yaml"
    },
    {
      "level": 1,
      "heading": "k8s Secret — فقط برای محیط توسعه",
      "content": "apiVersion: v1\nkind: Secret\nmetadata:\n  name: auth-service-env\n  namespace: nons-platform\ntype: Opaque\nstringData:\n  SESSION_SECRET: \"تولید شده توسط Devops — هرگز در Git\"\n  WEBHOOK_SECRET_TOKEN: \"تولید شده توسط Devops — هرگز در Git\"\n  OAUTH_CLIENT_SECRET: \"تولید شده توسط Devops — هرگز در Git\"\n```"
    },
    {
      "level": 3,
      "heading": "۲.۳ چه اطلاعاتی هرگز نباید داخل Repository قرار بگیرند",
      "content": "| مورد | خطر | جایگزین |\n|------|------|---------|\n| Passwordهای واقعی در `.env.example` | نشت به مخزن عمومی | استفاده از placeholders: `YOUR_PASSWORD_HERE` |\n| `KUBECONFIG` با دسترسی Production | دسترسی غیرمجاز به کلاستر | GitHub Secrets + CI |\n| `GHCR_PAT` | پوش تصویر غیرمجاز | GitHub Secrets + Environment protection |\n| Session Secret واقعی | جعل Session کاربران | K8s Secrets در زمان استقرار |\n| هر نوع API Key یا Token واقعی | سوءاستفاده سرویس‌های خارجی | Vault (فاز ۳) یا K8s Secrets |\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. الگوی مصرف Secrets در Helm",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۳.۱ تعریف در values.yaml",
      "content": "```yaml"
    },
    {
      "level": 1,
      "heading": "deploy/helm/auth-service/values.yaml",
      "content": "secret:\n  existingSecret: auth-service-env\n  keys:\n    sessionSecret: SESSION_SECRET\n    webhookToken: WEBHOOK_SECRET_TOKEN\n    oauthClientSecret: OAUTH_CLIENT_SECRET\n```"
    },
    {
      "level": 3,
      "heading": "۳.۲ مصرف در Deployment",
      "content": "```yaml"
    },
    {
      "level": 1,
      "heading": "deploy/helm/auth-service/templates/deployment.yaml",
      "content": "env:\n  - name: SESSION_SECRET\n    valueFrom:\n      secretKeyRef:\n        name: {{ .Values.secret.existingSecret }}\n        key: {{ .Values.secret.keys.sessionSecret }}\n  - name: WEBHOOK_SECRET_TOKEN\n    valueFrom:\n      secretKeyRef:\n        name: {{ .Values.secret.existingSecret }}\n        key: {{ .Values.secret.keys.webhookToken }}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. چرخه حیات Secrets (Secret Lifecycle)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۴.۱ ایجاد (Creation)",
      "content": "| مرحله | مسئول | ابزار |\n|-------|-------|-------|\n| تولید مقدار امن | Devops | `openssl rand -base64 32` |\n| ذخیره در GitHub Secrets | Devops | GitHub UI / `gh secret set` |\n| ذخیره در K8s Secrets | Devops / CI | `kubectl create secret` |\n| ارجاع در Helm Chart | Backend Team | `values.yaml` + `secretKeyRef` |"
    },
    {
      "level": 3,
      "heading": "۴.۲ چرخش (Rotation)",
      "content": "| راز | بازه چرخش | روش | تأثیر |\n|-----|----------|------|-------|\n| Database Passwords | هر ۱۸۰ روز | `ALTER USER ... PASSWORD` + rollout |短暂 Downtime |\n| Session Secrets | هر ۹۰ روز | تغییر + rollout تدریجی | Session logout کاربران |\n| Registry Token | هر ۹۰ روز | GitHub Token refresh | بدون تأثیر |\n| Webhook Token | هر ۹۰ روز | تغییر در Kratos + Auth Service | هماهنگی لازم است |\n| API Keys خارجی | بر اساس سیاست provider | دستی | وابسته به provider |"
    },
    {
      "level": 3,
      "heading": "۴.۳ انقضا و حذف (Expiration & Deletion)",
      "content": "| مرحله | اقدام | مسئول |\n|-------|-------|-------|\n| ۳۰ روز قبل | اعلان به تیم | Devops |\n| ۷ روز قبل | یادآوری + ایجاد راز جدید | Devops |\n| روز انقضا | انتقال به راز جدید + حذف راز قدیمی | Devops |\n| پس از حذف | تأیید عدم استفاده | Devops |\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. مالکیت Secrets (Secret Ownership)",
      "content": "| راز | تیم مالک | تیم‌های مصرف‌کننده |\n|-----|---------|-------------------|\n| `postgres-credentials` | Devops | Backend (همه سرویس‌ها) |\n| `kratos-config` | Backend | Backend |\n| `hydra-config` | Backend | Backend |\n| `auth-service-env` | Backend | Backend |\n| `ghcr-pull` | Devops | همه |\n| `nats-config` | Devops | Backend |\n| GitHub Environment Secrets | Devops | CI/CD |\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. نقشه راه آینده (Roadmap)",
      "content": "| قابلیت | فاز | وضعیت | توضیح |\n|--------|-----|-------|-------|\n| **External Secrets Operator** | فاز ۲ | 📅 برنامه‌ریزی‌شده | Sync خودکار از Vault به K8s Secrets |\n| **HashiCorp Vault** | فاز ۳ | 📅 برنامه‌ریزی‌شده | منبع حقیقت متمرکز تمام رازها |\n| **Secret Rotation Automation** | فاز ۳ | 📅 برنامه‌ریزی‌شده | چرخش خودکار بر اساس بازه زمانی |\n| **Audit Logging** | فاز ۳ | 📅 برنامه‌ریزی‌شده | ثبت همه دسترسی‌ها به رازها |\n| **Dynamic Secrets** | فاز ۴ | 🔭 ایده | تولید موقت راز برای هر سرویس |\n| **PKI Integration** | فاز ۴ | 🔭 ایده | صدور خودکار گواهی mTLS |\n\n---"
    },
    {
      "level": 2,
      "heading": "۷. خلاصه",
      "content": "| حوزه | تصمیم |\n|------|--------|\n| Storage Boundary | GitHub Secrets (CI) ← K8s Secrets (Runtime) ← Vault (آینده) |\n| محیط توسعه | مقادیر placeholder در `.env.example` + K8s Secrets محلی |\n| محیط Production | GitHub Environments + K8s Secrets واقعی |\n| Rotation | ۹۰ روز برای Tokenها، ۱۸۰ روز برای Passwordها |\n| Ownership | Devops مالک زیرساخت، Backend مالک سرویس |\n| Never in Repo | Passwordها، Tokenها، API Keyها، Session Secrets |"
    }
  ]
}