Argo Project: GitOps و CI/CD بومی Kubernetes — راهنمای کامل Argo CD، Workflows، Rollouts و Events

اگر Kubernetes دارید ولی هنوز deploy با kubectl apply دستی، Jenkins جدا، و «کدام نسخه روی prod است؟» سوال باز است — شما GitOps ندارید، فقط container orchestration.

Argo Project (معمولاً Argo) مجموعه‌ای از ابزارهای Open Source و Kubernetes-native است که کل چرخه delivery را روی همان cluster می‌آورد:

Get More Done with Kubernetes — workflows, cluster management, and GitOps.

چهار ستون اصلی:

ابزار	نقش یک‌خطی
Argo CD	GitOps CD — sync از Git به cluster
Argo Workflows	موتور workflow — CI، ETL، ML pipeline
Argo Rollouts	deploy پیشرفته — canary، blue-green
Argo Events	اتوماسیون event-driven — webhook به action

پروژه زیر چتر CNCF (Argo CD graduated) با maintainers از Red Hat، Intuit، Akuity و جامعه enterprise بزرگ — از Adobe تا Alibaba.

مشکل: delivery پراکنده

مدل سنتی:
Developer → git push → Jenkins (VM جدا)
                    → docker build
                    → kubectl apply (کی؟ کجا؟)
                    → «روی prod چی داریم؟» 🤷

مشکل	پیامد
Git ≠ وضعیت cluster	configuration drift
deploy دستی	خطای انسانی، بدون audit
CI و CD جدا	دو سیستم، دو مدل امنیت
rolling update ساده K8s	بدون canary واقعی و analysis
trigger دستی	automation شکسته

Argo همه را حول Git + CRD + controller متحد می‌کند.

فلسفه GitOps

اصولی که Argo CD پیاده می‌کند (مستندات رسمی):

Declarative — وضعیت مطلوب در Git (YAML/Helm/Kustomize)
Versioned — تاریخچه، rollback، PR review
Automated — controller تفاوت را sync می‌کند
Auditable — هر تغییر commit + event log

┌─────────────┐     watch      ┌──────────────┐     apply     ┌─────────────┐
│  Git Repo   │ ────────────► │   Argo CD    │ ────────────► │  Kubernetes │
│ (source of  │               │  controller  │               │   cluster   │
│   truth)    │ ◄──────────── │  + UI/API    │ ◄──────────── │  (live)     │
└─────────────┘   compare/diff └──────────────┘   reconcile   └─────────────┘
                      OutOfSync → Sync

معماری اکوسystem Argo

نمای کلی چهار ابزار

                    External Events
              (Git push, S3, Kafka, Cron, ...)
                           │
                           ▼
                   ┌───────────────┐
                   │  Argo Events  │
                   │ EventSource + │
                   │    Sensor     │
                   └───────┬───────┘
                           │ trigger
                           ▼
                   ┌───────────────┐
                   │Argo Workflows │  ← CI: build, test, scan
                   │ Workflow/DAG  │  ← ML/batch jobs
                   └───────┬───────┘
                           │ update image tag در GitOps repo
                           ▼
                   ┌───────────────┐
                   │   Argo CD     │  ← sync manifest
                   │  Application  │
                   └───────┬───────┘
                           │ deploy
                           ▼
                   ┌───────────────┐
                   │ Argo Rollouts │  ← canary / blue-green
                   │   Rollout CR  │     + AnalysisRun
                   └───────────────┘

۱. Argo CD — GitOps Continuous Delivery

چیست؟

Argo CD یک controller Kubernetes است که:

Application CRD را watch می‌کند
manifest را از Git (یا Helm، Kustomize، Jsonnet، plugin) می‌خواند
با وضعیت live cluster مقایسه می‌کند
Sync خودکار یا دستی انجام می‌دهد
UI وب برای دیدن tree منابع، health، diff

پشتیبانی manifest

نوع	پشتیبانی
Plain YAML/JSON	✅
Helm	✅ (native)
Kustomize	✅ (native)
Jsonnet	✅
Config Management Plugin	✅ (سفارشی)
چند cluster	✅

مفاهیم کلیدی

مفهوم	توضیح
Application	یک app = یک repo path + destination cluster/namespace
AppProject	محدودیت RBAC، منابع مجاز، clusterهای مجاز
Sync Policy	manual / automated + prune + selfHeal
Health	وضعیت Deployment، STS، CRDها
OutOfSync	live ≠ Git — drift
Rollback	بازگشت به commit قبلی در Git

ویژگی‌های مهم

SSO: OIDC، GitHub، GitLab، LDAP، SAML
Webhook از GitHub/GitLab برای sync سریع‌تر
PreSync / Sync / PostSync hooks
Prometheus metrics
CLI: argocd برای automation

نصب سریع

kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# پسورد admin اولیه
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d && echo

# port-forward UI
kubectl port-forward svc/argocd-server -n argocd 8080:443

Application نمونه

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-api
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/gitops-repo.git
    targetRevision: main
    path: apps/my-api/overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

App of Apps

الگوی رایج: یک Application والد که بقیه Applicationها را از Git deploy می‌کند — کل platform (شامل خود Argo، monitoring، ingress) GitOps می‌شود.

۲. Argo Workflows — موتور Workflow

چیست؟

Argo Workflows workflow engine بومی Kubernetes است:

هر step = یک container در Pod
workflow به‌صورت DAG یا steps تعریف می‌شود
artifact بین stepها (S3، GCS، MinIO، Artifactory)
WorkflowTemplate برای reuse
CronWorkflow برای زمان‌بندی

Use caseها

سناریو	مثال
CI pipeline	clone → test → build image → push → update Git
ML / data	train → evaluate → register model
ETL	extract → transform → load
backup	snapshot → upload S3
امنیت	scan image با Trivy/Kubescape

WorkflowTemplate نمونه (CI ساده)

apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
  name: ci-build
  namespace: argo
spec:
  entrypoint: pipeline
  templates:
    - name: pipeline
      steps:
        - - name: checkout
            template: git-clone
        - - name: test
            template: run-tests
        - - name: build-push
            template: kaniko-build
    - name: git-clone
      container:
        image: alpine/git:latest
        command: [sh, -c]
        args: ["git clone https://github.com/org/app.git /work"]
    - name: run-tests
      container:
        image: node:20
        command: [sh, -c]
        args: ["cd /work && npm ci && npm test"]
    - name: kaniko-build
      container:
        image: gcr.io/kaniko-project/executor:latest
        args:
          - --dockerfile=Dockerfile
          - --context=/work
          - --destination=registry.example.com/app:{{workflow.parameters.tag}}

دست‌به‌دستی با Argo CD

جریان رایج (CNCF blog):

Workflows image را build و push می‌کند
tag جدید را در GitOps repo commit می‌کند
Argo CD تغییر را detect و sync می‌کند

Git = نقطه handoff بین CI و CD.

۳. Argo Rollouts — Progressive Delivery

چیست؟

Argo Rollouts جایگزین Deployment برای releaseهای پیشرفته:

Canary — درصد ترافیک تدریجی
Blue-Green — switch یک‌باره پس از validation
AnalysisRun — متریک Prometheus/Datadog/Job قبل از promote
Traffic management — Ingress، Istio، SMI، ALB

چرا نه Deployment معمولی؟

Deployment rolling update دارد ولی:

کنترل دقیق درصد traffic ندارد
automated rollback بر اساس metric ندارد
pause و manual gate محدود است

Rollout نمونه (canary)

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: my-app
spec:
  replicas: 5
  strategy:
    canary:
      steps:
        - setWeight: 20
        - pause: { duration: 5m }
        - setWeight: 50
        - pause: { duration: 5m }
        - setWeight: 100
      analysis:
        templates:
          - templateName: success-rate
        startingStep: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: registry.example.com/app:v2

Argo CD می‌تواند Rollout را مثل Deployment sync کند — GitOps + canary در یک جریان.

۴. Argo Events — Event-Driven Automation

چیست؟

Argo Events اتصال رویداد خارجی به action در Kubernetes:

مؤلفه	نقش
EventSource	گوش دادن: webhook، S3، Kafka، calendar، GitHub
Sensor	فیلتر event → trigger Workflow / K8s resource / Lambda
EventBus	NATS برای توزیع event (معمولاً)

جریان CI خودکار

git push → GitHub webhook → EventSource
                              → Sensor
                              → Workflow (CI)
                              → commit به GitOps
                              → Argo CD sync

بدون Jenkins webhook configuration جدا برای هر pipeline — همه CRD در cluster.

چه زمانی از Argo استفاده کنیم؟

✅ مناسب

Kubernetes مرکز platform شماست
می‌خواهید GitOps واقعی (نه فقط Git storage)
چند environment (dev/staging/prod) از یک repo
Canary / blue-green با metric
CI روی K8s — بدون نگهداری Jenkins VM
ML pipeline یا batch job سنگین
تیم از قبل Helm/Kustomize بلد است

❌ کمتر مناسب

وضعیت	جایگزین
بدون Kubernetes	Argo فقط K8s
تیم کوچک، deploy ماهی یک‌بار	ساده‌تر: `kubectl` + script
فقط CI، بدون K8s deploy	GitHub Actions / GitLab CI
فقط GitOps ساده	Flux CD سبک‌تر
learning curve کم می‌خواهید	managed: Akuity، Codefresh

مقایسه با ابزارهای دیگر

معیار	Argo CD	Flux	Jenkins	GitHub Actions
GitOps native	✅ عالی	✅ عالی	❌	محدود
UI	✅ غنی	محدود	✅	✅
CI built-in	❌ (با Workflows)	❌	✅	✅
Canary	با Rollouts	Flagger	plugin	محدود
Multi-cluster	✅	✅	N/A	N/A
Kubernetes-only	✅	✅	❌	❌
پیچیدگی	بالا	متوسط	بالا	کم

Argo برنده می‌شود وقتی می‌خواهید یک اکوسystem یکپارچه روی K8s: CD + CI workflow + events + progressive delivery.

Flux برنده می‌شود وقتی فقط GitOps CD می‌خواهید و UI کمتر مهم است.

Argo در کنار stack شما

اگر از مقالات قبلی P30Light استفاده کرده‌اید:

┌─────────────────────────────────────────────────────────┐
│                    Git (GitOps repo)                     │
└───────────────────────────┬─────────────────────────────┘
                            │
         ┌──────────────────┼──────────────────┐
         ▼                  ▼                  ▼
   Argo CD sync      MkDocs CI (Workflow)   Helm/Kustomize
         │                  │                  │
         ▼                  ▼                  ▼
┌─────────────────────────────────────────────────────────┐
│              Kubernetes Cluster                          │
│  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐ │
│  │ KubeVirt│  │ Kube-OVN │  │ Astro   │  │ Apps     │ │
│  │   VMs   │  │   CNI    │  │  site   │  │ (Rollout)│ │
│  └─────────┘  └──────────┘  └─────────┘  └──────────┘ │
└─────────────────────────────────────────────────────────┘

deploy p30light.ir (Astro static) یا MkDocs با Argo CD
CI build با Argo Workflows (مثل مقاله MkDocs CI/CD)
شبکه multi-tenant با Kube-OVN؛ Argo Application per tenant

نصب platform کامل (outline)

ترتیب پیشنهادی

Argo CD — پایه GitOps
Argo Rollouts — اگر canary نیاز دارید
Argo Workflows — CI/batch
Argo Events — trigger خودکار

Argo Rollouts

kubectl create namespace argo-rollouts
kubectl apply -n argo-rollouts -f \
  https://github.com/argoproj/argo-rollouts/releases/latest/download/install.yaml

# kubectl plugin
curl -LO https://github.com/argoproj/argo-rollouts/releases/latest/download/kubectl-argo-rollouts-linux-amd64
chmod +x kubectl-argo-rollouts-linux-amd64
sudo mv kubectl-argo-rollouts-linux-amd64 /usr/local/bin/kubectl-argo-rollouts

Argo Workflows

kubectl create namespace argo
kubectl apply -n argo -f \
  https://github.com/argoproj/argo-workflows/releases/latest/download/install.yaml

# نصب argo CLI
# https://github.com/argoproj/argo-workflows/releases

Argo Events

kubectl create namespace argo-events
kubectl apply -f \
  https://raw.githubusercontent.com/argoproj/argo-events/stable/manifests/install.yaml

سپس EventSource + Sensor برای GitHub webhook تعریف کنید.

مدیریت خود Argo با GitOps

بهترین practice: App of Apps — همه componentهای Argo خودشان از طریق Argo CD deploy شوند.

امنیت و عملیات

موضوع	توصیه
RBAC	AppProject per team؛ least privilege
Secrets	External Secrets / Sealed Secrets — نه plain در Git
SSO	Dex built-in در Argo CD
Network	argocd-server پشت ingress + TLS
Audit	فعال‌سازی audit log
Drift	`selfHeal: true` با احتیاط در prod
Repo access	deploy key read-only برای CD

عملیات روزمره

# Argo CD CLI
argocd login argocd.example.com
argocd app list
argocd app sync my-api
argocd app diff my-api
argocd app rollback my-api

# Rollouts
kubectl argo rollouts get rollout my-app
kubectl argo rollouts promote my-app

# Workflows
argo submit -n argo --from workflowtemplate/ci-build -p tag=v1.2.3
argo list -n argo
argo logs -n argo @latest

جمع‌بندی

بدون Argo	با Argo
kubectl دستی	Git = truth
Jenkins جدا	Workflows روی K8s
rolling ساده	canary + analysis
webhook پراکنده	Events یکپارچه
«چی deploy شده؟»	UI + Git history

Argo Project فقط یک ابزار CD نیست — پلتفرم delivery برای تیم‌هایی است که Kubernetes را محور قرار داده‌اند. شروع با Argo CD منطقی است؛ Workflows، Rollouts و Events را وقتی نیاز واقعی دارید اضافه کنید.

قدم بعدی

Argo CD را روی staging نصب کنید (getting started)
یک Application برای app ساده (nginx) بسازید
automated sync + selfHeal را تست کنید
یک WorkflowTemplate CI برای همان app
در صورت نیاز production — Rollout canary با Prometheus metric

منابع:

منتشر شده در P30Light — بخش زیرساخت سرور و Cloud Native.