{
  "title": "معماری تحویل کانتینر",
  "slug": "team/devops/container-delivery-architecture",
  "url": "/docs/team/devops/container-delivery-architecture",
  "frontmatter": {
    "layout": "doc",
    "title": "معماری تحویل کانتینر",
    "description": "معماری جامع ساخت، ثبت، انتشار و استقرار تصاویر کانتینر در پلتفرم NONS",
    "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": "معماری تحویل کانتینر",
      "content": "**Container Delivery Architecture**\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. Container Registry Strategy",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۱.۱ ارائه‌دهنده رسمی",
      "content": "| مؤلفه | تصمیم |\n|-------|--------|\n| ارائه‌دهنده | **GitHub Container Registry (ghcr.io)** |\n| دلیل | هم‌خوانی با GitHub به عنوان بستر CI/CD و Source Control |\n| جایگزین | Docker Hub (رد شد — محدودیت نرخ pull برای CI) |\n| مهاجرت آینده | در صورت نیاز به Multi-Cloud، به ECR یا GCR انتقال داده شود |"
    },
    {
      "level": 3,
      "heading": "۱.۲ نام‌گذاری مخازن (Repository Naming)",
      "content": "```\nghcr.io/nons/{service-name}\n```\n\n| مؤلفه | قانون |\n|-------|-------|\n| Prefix | `ghcr.io/nons/` |\n| Service Name | دقیقاً مطابق نام دایرکتوری سرویس در `services/` |\n| Private Images | همه تصاویر به صورت **Private** ایجاد می‌شوند |\n| Public Images | فقط تصاویر پایه و ابزارهای عمومی می‌توانند Public باشند |\n\nمثال‌ها:\n\n```\nghcr.io/nons/auth-service\nghcr.io/nons/gateway\nghcr.io/nons/core\nghcr.io/nons/postgres-init\n```"
    },
    {
      "level": 3,
      "heading": "۱.۳ قوانین Namespace Ownership",
      "content": "| Namespace | مالک | سطح دسترسی |\n|-----------|------|-----------|\n| `ghcr.io/nons/` | Devops Team | Admin |\n| `ghcr.io/nons/*` | Backend Team | Write (Push) |\n| سایر | ممنوع | — |"
    },
    {
      "level": 3,
      "heading": "۱.۴ احراز هویت Registry",
      "content": "| مرحله | مکانیسم |\n|-------|---------|\n| CI Push | Personal Access Token (PAT) با scopes: `write:packages`, `delete:packages` |\n| Developer Push | GitHub CLI (`gh auth login`) یا PAT |\n| K3s Pull | `imagePullSecrets` با Pull Token |\n| K3d Pull | `k3d image import` (بدون نیاز به registry خارجی) |\n\n**روش ایجاد Token برای CI/CD:**\n\n```bash"
    },
    {
      "level": 1,
      "heading": "GitHub Secrets",
      "content": "REGISTRY_USERNAME=${{ github.actor }}\nREGISTRY_TOKEN=${{ secrets.GITHUB_TOKEN }}\n```\n\n**روش ایجاد Token برای K3s:**\n\n```bash\nkubectl create secret docker-registry ghcr-pull \\\n  --docker-server=ghcr.io \\\n  --docker-username=$GITHUB_ACTOR \\\n  --docker-password=$GITHUB_PAT \\\n  --namespace nons-platform\n```"
    },
    {
      "level": 3,
      "heading": "۱.۵ Retention Policy",
      "content": "| نوع تصویر | مدت نگهداری | خودکار |\n|-----------|------------|--------|\n| Release Tags (`v*`) | نامحدود | ❌ |\n| Commit SHA Tags | ۹۰ روز | ✅ |\n| Branch Tags | ۳۰ روز پس از حذف برنچ | ✅ |\n| Latest | ۱ نسخه | ✅ |"
    },
    {
      "level": 3,
      "heading": "۱.۶ تصاویر مجاز و ممنوع",
      "content": "| مجاز | ممنوع |\n|------|-------|\n| `ghcr.io/nons/*` | Docker Hub (برای تصاویر اختصاصی سرویس) |\n| تصاویر پایه عمومی (Alpine, Node, Go) | تصاویر با منبع نامشخص |\n| تصاویر اسکن‌شده امنیتی | تصاویر با آسیب‌پذیری HIGH |\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. Image Build Strategy",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۲.۱ استاندارد OCI",
      "content": "همه تصاویر کانتینر باید با استاندارد **OCI Image Format** ساخته شوند.\n\n| ابزار | وضعیت |\n|-------|-------|\n| Docker CLI (`docker build`) | ✅ فعلی |\n| BuildKit | ✅ توصیه شده (فعلاً اختیاری) |\n| Ko (Go images) | بررسی آینده |\n| Podman | امکان جایگزینی در فاز ۵ |"
    },
    {
      "level": 3,
      "heading": "۲.۲ Image Versioning Policy",
      "content": "| تگ | معنی | مثال | Immutable |\n|----|------|------|-----------|\n| `{major}.{minor}.{patch}` | Release SemVer | `1.2.0` | ✅ بله |\n| `{version}-rc.{n}` | Release Candidate | `1.2.0-rc.1` | ✅ بله |\n| `{version}-beta.{n}` | Beta | `1.2.0-beta.1` | ✅ بله |\n| `sha-{commit}` | هر commit به برنچ اصلی | `sha-a1b2c3d4` | ✅ بله |\n| `latest` | آخرین Release | `latest` | ❌ خیر (متحرک) |\n| `{branch-name}` | برنچ توسعه | `main`, `develop` | ❌ خیر (متحرک) |\n\n**قوانین:**\n\n1. **همه تگ‌ها به جز `latest` و `{branch-name}` باید Immutable باشند.**\n2. **تگ `latest` فقط روی آخرین Release پایدار مجاز است** (هرگز روی `alpha` یا `beta`).\n3. **تگ `sha-{commit}` باید برای هر commit به `main`/`master` ایجاد شود.**\n4. **بازنویسی تگ Release ممنوع است** — اگر اشتباه شد، تگ جدید با PATCH بعدی ایجاد شود."
    },
    {
      "level": 3,
      "heading": "۲.۳ Commit SHA Tagging",
      "content": "```bash\nIMAGE_TAG=\"sha-${GITHUB_SHA::8}\"\ndocker build -t ghcr.io/nons/auth-service:${IMAGE_TAG} .\ndocker push ghcr.io/nons/auth-service:${IMAGE_TAG}\n```"
    },
    {
      "level": 3,
      "heading": "۲.۴ Release Tagging",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "Create Git Tag",
      "content": "git tag auth-service/v1.2.0\ngit push origin auth-service/v1.2.0"
    },
    {
      "level": 1,
      "heading": "Build & Push",
      "content": "docker build -t ghcr.io/nons/auth-service:1.2.0 .\ndocker push ghcr.io/nons/auth-service:1.2.0"
    },
    {
      "level": 1,
      "heading": "Also update 'latest'",
      "content": "docker tag ghcr.io/nons/auth-service:1.2.0 ghcr.io/nons/auth-service:latest\ndocker push ghcr.io/nons/auth-service:latest\n```"
    },
    {
      "level": 3,
      "heading": "۲.۵ Multi-Architecture (Future Consideration)",
      "content": "| معماری | وضعیت | زمان |\n|---------|-------|------|\n| `linux/amd64` | ✅ فعلی | اکنون |\n| `linux/arm64` | ⏳ بررسی | فاز ۵ |\n| Apple Silicon | ⏳ بررسی | فاز ۵ |\n\n```bash"
    },
    {
      "level": 1,
      "heading": "Future: Multi-arch build",
      "content": "docker buildx build \\\n  --platform linux/amd64,linux/arm64 \\\n  -t ghcr.io/nons/auth-service:1.2.0 \\\n  --push .\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. Deployment Artifact Strategy",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۳.۱ زنجیره Artifact",
      "content": "```text\nSource Code (Git)\n    ↓\nBuild (CI)\n    ↓\nContainer Image (ghcr.io)  ←── Helm Chart (deploy/helm/)\n    ↓                                  ↓\nimage.tag: \"1.2.0\"  ←──────  values.yaml\n    ↓\nkubectl apply / helm upgrade\n    ↓\nRunning Pod\n```"
    },
    {
      "level": 3,
      "heading": "۳.۲ رابطه Source Code و Image",
      "content": "| Source Change | Image Build | Tag |\n|--------------|-------------|-----|\n| Commit به `main` | ✅ خودکار | `sha-{commit}` |\n| Pull Request | ✅ خودکار | `sha-{commit}` + `pr-{number}` |\n| Git Tag `v*` | ✅ خودکار | `{version}` |\n| Manual Trigger | ✅ دستی | مطابق هدف |"
    },
    {
      "level": 3,
      "heading": "۳.۳ رابطه Image و Helm Chart",
      "content": "Helm Chart سرویس شامل `values.yaml` است که `image.repository` و `image.tag` را تعریف می‌کند:\n\n```yaml"
    },
    {
      "level": 1,
      "heading": "deploy/helm/auth-service/values.yaml",
      "content": "image:\n  repository: ghcr.io/nons/auth-service\n  tag: latest\n  pullPolicy: IfNotPresent\n```\n\n**قوانین:**\n\n| محیط | image.tag | نحوه تنظیم |\n|------|-----------|-----------|\n| توسعه محلی (K3d) | `latest` | `--set image.tag=latest` + `k3d image import` |\n| Staging | `sha-{commit}` | CI خودکار |\n| Production | `{version}` | Release workflow دستی |"
    },
    {
      "level": 3,
      "heading": "۳.۴ Image Promotion بین محیط‌ها",
      "content": "```text\nBuild (CI)\n  ↓\nRegistry: ghcr.io/nons/auth-service:sha-a1b2c3d4\n  ↓\n[Staging]  helm upgrade --set image.tag=sha-a1b2c3d4\n  ↓  (validation passed)\n[Production] helm upgrade --set image.tag=sha-a1b2c3d4\n  ↓\n[Release] git tag + docker tag + push {version}\n```"
    },
    {
      "level": 3,
      "heading": "۳.۵ Environment-Specific Values",
      "content": "| محیط | فایل Values | نحوه استفاده |\n|------|------------|-------------|\n| Local | `deploy/environments/local/values.yaml` | پیش‌فرض K3d |\n| Staging | `deploy/environments/staging/values.yaml` | CI/CD |\n| Production | `deploy/environments/production/values.yaml` | Release Workflow |\n\n```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": "۴. Security Considerations",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۴.۱ Registry Authentication",
      "content": "| مؤلفه | مکانیسم |\n|-------|---------|\n| Push از CI | `GITHUB_TOKEN` |\n| Pull از K3s | `imagePullSecrets` با `ghcr-pull` secret |\n| Pull از K3d | `k3d image import` (محلی) |\n| Developer Pull | `docker login ghcr.io` با PAT |"
    },
    {
      "level": 3,
      "heading": "۴.۲ Secret Handling",
      "content": "| راز | کجا ذخیره شود | کجا هرگز ذخیره نشود |\n|-----|---------------|--------------------|\n| Registry Token | GitHub Secrets / K8s Secrets | Image layer, env file |\n| PAT | GitHub Secrets | Image, git log |\n| Pull Secret | K8s Secret (namespace) | Code, Helm values in git |"
    },
    {
      "level": 3,
      "heading": "۴.۳ Image Provenance",
      "content": "| مکانیسم | وضعیت |\n|---------|-------|\n| Docker Content Trust | ❌ غیرفعال (بررسی در فاز ۵) |\n| Cosign (Signature) | ❌ بررسی در فاز ۵ |\n| SBOM | ❌ بررسی در فاز ۵ |\n| SLSA Level | ❌ هدف: Level 2 در فاز ۵ |"
    },
    {
      "level": 3,
      "heading": "۴.۴ Supply Chain Security Roadmap",
      "content": "| قابلیت | فاز | تأثیر |\n|--------|-----|-------|\n| Image Signing (Cosign) | فاز ۵ | تأیید اصالت تصاویر |\n| Vulnerability Scanning | فاز ۵ | اسکن خودکار در CI |\n| SBOM Generation | فاز ۵ | شفافیت وابستگی‌ها |\n| Policy Enforcement | فاز ۵ | ممنوعیت تصاویر اسکن‌نشده |\n| Multi-Arch Build | فاز ۵ | پشتیبانی arm64 |\n| GitOps (ArgoCD/Flux) | فاز ۵ | استقرار خودکار declarative |\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. خلاصه",
      "content": "| حوزه | تصمیم اصلی |\n|------|-----------|\n| Registry | `ghcr.io/nons/*` — همه Private |\n| Image Tag | SemVer برای Release, `sha-{commit}` برای هر commit |\n| Immutable Tags | همه تگ‌ها به جز `latest` و `{branch}` |\n| Helm Integration | `image.tag` در `values.yaml` + override به ازای محیط |\n| Pull از K3s | `imagePullSecrets` |\n| Pull از K3d | `k3d image import` (بدون registry خارجی) |\n| Retention | Release: نامحدود \\| SHA: ۹۰ روز \\| Branch: ۳۰ روز |\n| Security | مرحله‌ای — فاز ۵ برای امضا و اسکن |"
    }
  ]
}