Add Harbor/Ceph runbooks and align single-node Ceph docs with abr deployment.

Document registry ingress split, image mirroring, loop OSD setup, and platform integration paths.
2026-07-01 00:22:06 +03:30
parent 8d1855b89c
commit ee5bd0a291
21 changed files with 2124 additions and 2 deletions
@@ -0,0 +1,195 @@
+# راهنمای Harbor — `registry.abrban.com`
+
+این سند معماری فعلی، نصب، مدیریت روزمره و عیب‌یابی **Harbor** روی کلاستر abr را پوشش می‌دهد.
+
+- چارت/values: [`backend/helm/cloudhost-harbor/`](backend/helm/cloudhost-harbor/)
+- اسکریپت نصب: [`backend/helm/cloudhost-harbor/scripts/install-harbor-registry.sh`](backend/helm/cloudhost-harbor/scripts/install-harbor-registry.sh)
+
+---
+
+## معماری فعلی (خلاصه)
+
+```
+registry.abrban.com (Traefik + TLS wildcard)
+├── /                    → harbor-portal   (UI)
+├── /api/, /service/, /c/ → harbor-core   (API + auth)
+├── /v2/proxy-dockerhub/ → harbor-registry (ایمیج‌های mirror‌شده Ceph/Rook)
+├── /v2/rook/            → harbor-registry
+└── /v2/*                → registry قدیمی (ایمیج‌های platform: backend, nixpacks, …)
+```
+
+| کامپوننت | نقش |
+|----------|-----|
+| **Harbor** | UI، proxy-cache، ذخیره ایمیج‌های جدید |
+| **registry قدیمی** (`Deployment/registry`) | هنوز بالاست؛ ایمیج‌های platform قبل از Harbor اینجاست |
+| **registry-egress-proxy** | secret با `HTTP_PROXY` / `HTTPS_PROXY` برای pull از docker.io/quay از داخل کلاستر |
+| **registry-pull-secret** | auth kubelet برای pull از `registry.abrban.com` |
+
+> Harbor و registry قدیمی **هم‌زمان** روی یک hostname هستند؛ مسیر `/v2/` با Ingress split می‌شود.
+
+---
+
+## پیش‌نیازها
+
+- Secret `abrban-wildcard-tls` در namespace `cloudhost`
+- Secret `registry-egress-proxy` در namespace `cloudhost` (پروکسی egress)
+- Helm repo: `helm repo add harbor https://helm.goharbor.io`
+
+---
+
+## نصب / ارتقا
+
+```bash
+cd backend/helm/cloudhost-harbor
+./scripts/install-harbor-registry.sh
+```
+
+اسکریپت:
+1. Harbor را با values + proxy از `registry-egress-proxy` نصب می‌کند
+2. Ingress قدیمی `registry` را حذف می‌کند (بعد از نصب باید دستی دوباره route شود — بخش Ingress)
+3. `Deployment/registry` را scale به 0 می‌کند (برای rollback نگه داشته می‌شود)
+
+### Ingress بعد از نصب (الزامی)
+
+Harbor به **چند مسیر** نیاز دارد. Ingress نهایی باید شبیه این باشد:
+
+| Path | Service | Port |
+|------|---------|------|
+| `/` | `harbor-portal` | 80 |
+| `/api/`, `/service/`, `/c/`, `/chartrepo/` | `harbor-core` | 80 |
+| `/v2/proxy-dockerhub/`, `/v2/rook/` | `harbor-registry` | 5000 |
+| `/v2/` (بقیه) | `registry` (قدیمی) | 5000 |
+
+بدون split روی `/v2/`، یا UI 404 می‌دهد یا kubelet ایمیج platform را پیدا نمی‌کند.
+
+---
+
+## دسترسی و credentialها
+
+| کاربرد | کاربر | منبع |
+|--------|-------|------|
+| UI / API مدیریت | `admin` | `kubectl -n cloudhost get secret harbor-core -o jsonpath='{.data.HARBOR_ADMIN_PASSWORD}' \| base64 -d` |
+| push/pull داخلی به harbor-registry | `harbor_registry_user` | secret `harbor-core` → `REGISTRY_CREDENTIAL_PASSWORD` |
+| pull kubelet (ایمیج‌های platform) | `cloudhost` | secret `registry-pull-secret` (namespace `cloudhost`) |
+| pull kubelet (ایمیج‌های Rook/Ceph) | `harbor_registry_user` | secret `registry-pull-secret` (namespace `rook-ceph`) |
+
+URL: https://registry.abrban.com/
+
+---
+
+## پروژه‌های proxy-cache
+
+| پروژه | upstream | کاربرد |
+|-------|----------|--------|
+| `proxy-dockerhub` | docker.io | Rook، Ceph، bitnami، … |
+| `proxy-quay` | quay.io | cephcsi و … |
+| `proxy-k8s` | registry.k8s.io | CSI sidecarها |
+
+ایجاد از UI: **Administration → Registries → New Endpoint** سپس **Projects → New Project** با نوع Proxy Cache.
+
+> health check بعضی endpointها (مثلاً quay) از UI timeout می‌خورد؛ از داخل `harbor-core` با curl و proxy ممکن است OK باشد. در صورت نیاز endpoint را با type `docker-registry` بسازید.
+
+### proxy در Harbor
+
+پروکسی از secret `registry-egress-proxy` در ConfigMapهای `harbor-core` و `harbor-jobservice-env` تزریق می‌شود.
+
+**مهم:** Go (harbor-core/jobservice) به `http_proxy` / `https_proxy` **lowercase** هم نیاز دارد. اگر health check upstream `unhealthy` ماند، هر دو حالت uppercase و lowercase را در ConfigMap بگذارید و podها را restart کنید:
+
+```bash
+kubectl -n cloudhost rollout restart deploy/harbor-core deploy/harbor-jobservice
+```
+
+---
+
+## mirror دستی ایمیج (وقتی proxy-cache کار نمی‌کند)
+
+روی abr، pull مستقیم از docker.io/quay از kubelet ممکن نیست. ایمیج‌های حیاتی را با Job داخل کلاستر mirror کنید:
+
+**مقصد push:** `harbor-registry.cloudhost.svc.cluster.local:5000` (HTTP، با `harbor_registry_user`)
+
+**مثال مسیرها در registry:**
+
+| ایمیج upstream | مسیر در registry |
+|----------------|------------------|
+| `rook/ceph:v1.20.1` | `rook/ceph:v1.20.1` |
+| `quay.io/ceph/ceph:v19.2` | `proxy-dockerhub/ceph/ceph:v19.2` |
+
+```bash
+# لیست ایمیج‌های داخل harbor-registry
+kubectl -n cloudhost exec deploy/harbor-portal -- \
+  curl -s -u "harbor_registry_user:$(kubectl -n cloudhost get secret harbor-core -o jsonpath='{.data.REGISTRY_CREDENTIAL_PASSWORD}' | base64 -d)" \
+  http://harbor-registry:5000/v2/_catalog
+```
+
+> push مستقیم به `harbor-registry:5000` metadata در Harbor UI را به‌روز نمی‌کند؛ برای kubelet کافی است چون `/v2/` به harbor-registry route شده.
+
+---
+
+## مدیریت روزمره
+
+### وضعیت
+
+```bash
+kubectl -n cloudhost get pods | grep harbor
+kubectl -n cloudhost get ingress registry -o yaml | grep -A3 'path:'
+curl -sk -o /dev/null -w "%{http_code}\n" https://registry.abrban.com/
+curl -sk -u admin:<pass> https://registry.abrban.com/api/v2.0/systeminfo
+```
+
+### لاگ‌ها
+
+```bash
+kubectl -n cloudhost logs deploy/harbor-core --tail=50
+kubectl -n cloudhost logs deploy/harbor-jobservice --tail=50
+kubectl -n cloudhost logs deploy/harbor-registry -c registry --tail=50
+```
+
+### ارتقا Harbor
+
+```bash
+helm repo update harbor
+./scripts/install-harbor-registry.sh
+# Ingress split را دوباره تأیید کنید
+```
+
+### rollback به registry قدیمی
+
+```bash
+kubectl -n cloudhost scale deploy/registry --replicas=1
+# Ingress را فقط به service registry:5000 برگردانید
+helm uninstall harbor -n cloudhost
+```
+
+---
+
+## عیب‌یابی
+
+| علامت | علت محتمل | اقدام |
+|-------|-----------|--------|
+| `https://registry.abrban.com/` → 404 | Ingress فقط به `harbor-core` وصل است | `/` → `harbor-portal` |
+| `ImagePullBackOff` برای `cloudhost-backend` | `/v2/` به Harbor رفته، ایمیج platform آنجا نیست | `/v2/` (عمومی) → `registry` قدیمی |
+| `not found` برای `proxy-dockerhub/...` | ایمیج mirror نشده | Job skopeo یا proxy-cache |
+| push با 499/503 | Traefik timeout | push از داخل کلاستر به `harbor-registry:5000` |
+| registry endpoint `unhealthy` | proxy lowercase یا timeout health check | patch ConfigMap + restart؛ یا mirror دستی |
+| `authentication required` روی pull | pull secret اشتباه namespace | `cloudhost` vs `harbor_registry_user` در `rook-ceph` |
+
+### تست pull
+
+```bash
+# platform (cloudhost user)
+curl -sk -u "cloudhost:<pass>" https://registry.abrban.com/v2/cloudhost-backend/tags/list
+
+# rook/ceph (harbor_registry_user)
+curl -sk -u "harbor_registry_user:<pass>" https://registry.abrban.com/v2/rook/ceph/tags/list
+```
+
+---
+
+## چک‌لیست بعد از نصب
+
+- [ ] Portal روی `/` پاسخ 200
+- [ ] `/api/v2.0/systeminfo` پاسخ JSON
+- [ ] Ingress split `/v2/` درست است
+- [ ] پروژه‌های `proxy-dockerhub`, `proxy-k8s`, `proxy-quay` ساخته شده
+- [ ] `registry-pull-secret` در `cloudhost` و `rook-ceph` به‌روز است
+- [ ] ایمیج‌های Rook/Ceph mirror شده و pull تست شده