Docker Hub عمومی، rate limit، و «هر image بدون policy» برای production کافی نیست. تیم‌ها به یک registry خصوصی نیاز دارند که:

push → scan → (اختیاری) block pull
sign → فقط artifact معتبر
replicate → DR / multi-region
RBAC → تیم‌ها و CI جدا

Harbor همان repository است:

Our mission is to be the trusted cloud native repository for Kubernetes

و تعریف رسمی:

An open source registry that secures artifacts with policies and role-based access control, ensures images are scanned and free from vulnerabilities, and signs images as trusted.

CNCF Graduated — ژوئن ۲۰۲۰ (ورود به CNCF ژوئیه ۲۰۱۸؛ ریشه VMware ۲۰۱۶). Docs فعلی تا 2.15.0 / latest. کاربران: CERN، OVHcloud، Dynatrace، Trend Micro، JD و ده‌ها سازمان دیگر.

مشکل: registry بدون policy

Docker Distribution خام:
  push / pull — تمام

Harbor:
  Projects + quotas + RBAC
  Trivy scan-on-push
  Cosign / Notation signatures
  Replication + proxy cache
  Audit + retention + GC

Harbor فقط «جایی برای نگه داشتن image» نیست — control plane سیاست artifact در مسیر Kubernetes و Docker است.

Harbor چیست؟

Harbor یک OCI-compatible registry است که روی Docker Distribution ساخته شده و لایهٔ enterprise اضافه می‌کند:

• امنیت و تحلیل آسیب‌پذیری
• امضا و اعتبارسنجی محتوا
• multi-tenant با Project و quota
• API گسترده + Web UI
• replication به Harbor و registryهای دیگر
• یکپارچگی identity (OIDC / LDAP) و RBAC
• مدیریت Helm charts و سایر OCI artifacts

Site: goharbor.io
Docs: goharbor.io/docs
Repo: github.com/goharbor/harbor
CLI: Harbor CLI (مستندات جدا در سایت)

License: Apache 2.0

تاریخچه و CNCF

معماری میکروسرویس‌ها

Ingress / TLS
      │
      ▼
┌─────────┐   ┌──────────┐   ┌────────────┐
│ Portal  │   │   Core   │──►│  Registry  │──► S3 / PVC / filesystem
│  (UI)   │──►│ API+Auth │   │ (Distribution)
└─────────┘   └────┬─────┘   └────────────┘
                   │
            ┌──────┴──────┐
            ▼             ▼
      ┌───────────┐  ┌─────────┐
      │ JobService│  │  Trivy  │  (optional scanner)
      │ scan/repl │  └─────────┘
      │ GC/…      │
      └─────┬─────┘
            │
     ┌──────┴──────┐
     ▼             ▼
 PostgreSQL      Redis
 (metadata)      (cache / queue)

جریان push نمونه:

1. Client → Core (authenticate / authorize)
2. Blobها → Registry → storage
3. Metadata → PostgreSQL
4. JobService → Trivy scan (اگر policy)
5. نتیجه CVE در DB؛ policy می‌تواند pull آسیب‌پذیر را منع کند
6. Replication (اگر rule) به‌صورت async

قابلیت‌های اصلی

Security و vulnerability

• Scan-on-push — هر push اسکن شود
• Prevent vulnerable images from running — pull با severity مشخص block شود
• Scannerهای pluggable: Trivy (پیش‌فرض)، Clair، Anchore و adapters سازگار
• گزارش CVE در UI و API

Content signing و validation

• Cosign (Sigstore) — مسیر توصیه‌شده مدرن
• Notation
• Notary v1 قدیمی — deprecated؛ به Cosign مهاجرت کنید
• Policy: فقط artifact امضاشده قابل pull

Management

• Multi-tenant Projects — isolation تیم‌ها
• Quotas روی storage / تعداد artifact
• RBAC در سطح project و system
• Web UI + REST API
• Audit log

Replication

• Push یا pull بین Harbor ↔ Harbor و بسیاری registryهای دیگر
• Event-based یا scheduled
• مناسب DR، multi-region، air-gap staging

Proxy cache

• Project از نوع Proxy Cache = pull-through mirror برای Docker Hub، GHCR، …
• کاهش rate limit و ترافیک خارجی
• cache محلی برای base imageهای پرتکرار

Identity

• Local DB users
• OIDC (Okta، Keycloak، Entra ID، …)
• LDAP/AD در سناریوهای سازمانی

Projects، Roles، Robot Accounts

Project

واحد tenancy:

library / team-a / team-b
  └── repositories
        └── artifacts (images, charts, signatures, SBOMs, …)

Visibility: public یا private. Metadata flags برای scan، content trust، severity blocking.

نقش‌های انسانی (مفهومی)

Robot Accounts

برای CI/CD — نه کاربر admin:

• Project-scoped — فقط یک project
• System-scoped — چند project / عملیات replication

# استفاده در CI
docker login harbor.example.com -u 'robot$project+ci' -p '<token>'

بهترین عمل:

• حداقل permission (مثلاً فقط push به ci، فقط pull برای deploy)
• expiration و rotation
• جدا کردن robot اسکنر از robot deploy
• هرگز admin credential در pipeline

مستندات: Robot Accounts.

Supply chain عملی: build → scan → sign → pull

CI build
  → docker/buildah push → Harbor
  → Trivy scan-on-push
  → cosign sign (key یا keyless)
  → policy: unsigned / critical CVE → deny pull
  → cluster pull (kubelet / [containerd](/blog/containerd-container-runtime-guide/))
  → optional: [Dragonfly](/blog/dragonfly-p2p-image-distribution-guide/) P2P + preheat

با cert-manager TLS برای Ingress Harbor؛ با Argo CD فقط imageهایی که از project «signed+scanned» می‌آیند deploy شوند (image updater / policy).

Retention، GC، Storage

• Tag retention rules — نگه داشتن N آخرین tag / بر اساس regex
• Garbage Collection — پاک‌سازی blobهای بدون مرجع (JobService)
• Storage backend: filesystem، PVC، S3 / MinIO / GCS / Azure Blob

بدون retention+GC، registry بدون محدودیت رشد می‌کند.

نصب

پیش‌نیاز

• Linux با Docker / docker-compose یا Kubernetes + Helm
• DNS و HTTPS (production اجباری برای docker login امن)
• منابع کافی برای Core + DB + Redis + Registry + Trivy

Docker Compose installer

طبق Install docs:

1. Download Harbor installer (online/offline)
2. Configure HTTPS
3. ویرایش harbor.yml
4. ./install.sh (با گزینه‌های Trivy و غیره)

مناسب lab و تک‌node؛ برای HA بهتر است Kubernetes.

Helm روی Kubernetes (HA)

helm repo add harbor https://helm.goharbor.io
helm repo update

helm install harbor harbor/harbor \
  --namespace harbor \
  --create-namespace \
  --set expose.type=ingress \
  --set expose.ingress.hosts.core=harbor.example.com \
  --set externalURL=https://harbor.example.com \
  --set persistence.persistentVolumeClaim.registry.size=100Gi \
  --set trivy.enabled=true

Production:

• PostgreSQL و Redis خارجی (managed)
• Object storage برای registry
• چند replica برای core / portal / jobservice طبق chart
• Ingress + TLS
• Backup منظم DB + object store

راهنمای CNCF: Deploying Harbor on Kubernetes using Helm.

اولین login

# UI
https://harbor.example.com

# Docker
docker login harbor.example.com
docker tag myapp:1.0 harbor.example.com/library/myapp:1.0
docker push harbor.example.com/library/myapp:1.0

Replication و DR

# مفهومی — در UI/API تعریف می‌شود
# Source: harbor-prod / project library
# Destination: harbor-dr
# Trigger: event (push) یا cron

نکات:

• برای pull/push بین instanceها معمولاً system robot با permission مناسب
• Replication ≠ backup کامل — DB و config را جدا backup کنید
• با Dragonfly می‌توان بعد از replicate، preheat به Seed Peerها زد تا rollout سرد نباشد

Proxy Cache در برابر Replication

هر دو اغلب با هم استفاده می‌شوند: proxy برای public bases؛ replication برای promotion dev → staging → prod.

مقایسه با جایگزین‌ها

Harbor جایگزین Kubernetes نیست — منبع حقیقت image قبل از schedule شدن Pod است.

امنیت Harbor خودش

چون همه pipeline از اینجا رد می‌شود، compromise خطرناک است:

1. Admin را از CI حذف کنید — فقط robot محدود
2. OIDC + MFA برای انسان‌ها
3. Audit را monitor کنید (replication rule مشکوک = exfiltration)
4. UI/API فقط از شبکه داخلی / VPN / SSO
5. TLS اجباری؛ internal TLS بین componentها در صورت نیاز
6. Secretها و signing keys در Vault — نه در ConfigMap
7. به‌روزرسانی منظم (CVE خود Harbor و Trivy DB)
8. NetworkPolicy / Cilium برای محدود کردن egress JobService

Observability و troubleshooting

kubectl -n harbor get pods
kubectl -n harbor logs -l component=core --tail=100
kubectl -n harbor logs -l component=jobservice --tail=100

Prometheus metrics و health endpoints را در monitoring استک بگذارید.

ارتباط با stack شما

Developer / CI
  → Harbor (scan + sign + RBAC)
  → optional Dragonfly preheat / P2P
  → kubelet + [containerd](/blog/containerd-container-runtime-guide/) pull
  → Pod

GitOps: [Argo CD](/blog/argo-project-kubernetes-gitops-cicd/)
TLS: [cert-manager](/blog/cert-manager-kubernetes-tls-certificates/)
DNS: [CoreDNS](/blog/coredns-kubernetes-dns-guide/)
Policy/net: [Cilium](/blog/cilium-ebpf-kubernetes-networking/)
Platform API: [Crossplane](/blog/crossplane-kubernetes-control-plane-guide/) (provision Harbor deps)

Dapr و اپ‌ها image را از Harbor می‌گیرند؛ Harbor لایه supply chain artifact است نه application runtime.

Best practices

1. یک project per تیم یا per محیط (app-prod, app-dev)
2. Robot با کمترین privilege + expiry
3. Scan-on-push + block برای Critical در prod project
4. Cosign sign در CI؛ verify در admission (اختیاری Kyverno/OPA) و/یا Harbor policy
5. Proxy cache برای Docker Hub
6. Replication به DR Harbor
7. Retention هفتگی + GC برنامه‌ریزی‌شده
8. DB و object storage backup تست‌شده
9. externalURL و TLS درست از روز اول
10. Trivy DB را به‌روز نگه دارید

چه زمانی Harbor؟

✅ استفاده کنید

• نیاز به self-hosted registry با compliance
• چند تیم / چند محیط با RBAC
• اجباری کردن scan و signature
• Replication و proxy cache
• On-prem / air-gapped / hybrid cloud

⚠️ شاید نه

• تک‌developer بدون نیاز policy → GHCR یا مشابه کافی است
• تیم صفر برای ops HA (DB، storage، backup)
• فقط CDN توزیع layer در مقیاس عظیم بدون registry policy → اول Dragonfly را جدا ارزیابی کنید (معمولاً با Harbor)

جمع‌بندی

Harbor جایی است که «چه artifactی اجازه ورود به cluster دارد» اجرا می‌شود — نه فقط در wiki نوشته می‌شود.

قدم بعدی

1. Demo server یا Helm نصب روی cluster dev (docs)
2. یک Project + robot CI بسازید و image push کنید
3. Scan-on-push و مشاهده گزارش Trivy
4. Cosign sign و policy امضا
5. Proxy cache برای docker.io و یک replication به instance دوم
6. اتصال containerd/Kubernetes به Harbor + (اختیاری) Dragonfly

منابع

• Harbor — goharbor.io
• Installation and Configuration
• Robot Accounts
• GitHub — goharbor/harbor
• CNCF: Deploying Harbor with Helm
• CNCF Harbor project

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