Khởi động nhanh: Chạy Harbor trên Kubernetes (5 phút)
Việc quản lý container image trên nhiều cluster staging và production sẽ nhanh chóng trở nên hỗn loạn nếu thiếu một registry chuyên dụng. Harbor giải quyết bài toán này bằng cách bổ sung khả năng quản trị chuẩn production cho OCI Distribution Registry. Với Helm chart chính thức, bạn có thể khởi tạo một instance hoạt động hoàn chỉnh chỉ trong khoảng 5 phút.
Đầu tiên, hãy thêm Helm repository của Harbor và tạo một namespace riêng biệt:
helm repo add harbor https://helm.goharbor.io
helm repo update
kubectl create namespace harbor
Tiếp theo, hãy định nghĩa một file values-quickstart.yaml tối giản. Cấu hình này sẽ bật ingress với TLS, phân bổ 50 GB persistent storage và kích hoạt công cụ quét Trivy:
expose:
type: ingress
tls:
enabled: true
certSource: auto
secret:
secretName: harbor-tls
ingress:
hosts:
core: registry.internal.example.com
externalURL: https://registry.internal.example.com
persistence:
enabled: true
resourcePolicy: keep
persistentVolumeClaim:
registry:
size: 50Gi
trivy:
enabled: true
harborAdminPassword: "SecureAdminPass123!"
Triển khai chart vào cluster của bạn:
helm install harbor harbor/harbor -f values-quickstart.yaml -n harbor
Theo dõi quá trình rollout cho đến khi tất cả các pod cốt lõi chuyển sang trạng thái Running:
kubectl get pods -n harbor -w
Khi đã sẵn sàng, hãy mở https://registry.internal.example.com trên trình duyệt. Đăng nhập bằng username admin và mật khẩu đã cấu hình ở trên.
Đi sâu vào kiến trúc: Các thành phần cốt lõi
Harbor không phải là một container proxy nguyên khối (monolithic). Nó hoạt động như một tập hợp microservice phân tán đứng sau API gateway:
- Harbor Core: Quản lý xác thực (authentication), phân quyền RBAC (authorization), webhook và cấp phát token OIDC.
- Registry & Controller: Được xây dựng dựa trên đặc tả OCI Distribution, chịu trách nhiệm xử lý các image layer blob thô, upload theo phân đoạn (chunked upload) và OCI artifact manifest.
- Jobservice: Hàng đợi tác vụ bất đồng bộ (asynchronous job queue) thực thi image replication, dọn dẹp bộ nhớ (garbage collection) theo lịch trình và các quy tắc giữ lại tag (tag retention rule).
- Trivy Security Scanner: Tải cơ sở dữ liệu lỗ hổng CVE để kiểm tra các layer của image mỗi khi có lượt push.
- Database (PostgreSQL) & Cache (Redis): Lưu trữ cấu hình dự án, audit log, quyền hạn người dùng và trạng thái phiên làm việc (session state) đang hoạt động.
Cấu hình quét lỗ hổng bảo mật tự động
Phát hiện lỗ hổng trước khi image được đưa vào cluster giúp tiết kiệm hàng giờ xử lý sự cố. Các đội ngũ phát triển thường xuyên push những image dựa trên bản phân phối gốc (base distro) đã cũ chứa hàng tá CVE nghiêm trọng. Harbor cho phép bạn áp dụng các chính sách scan-on-push trực tiếp qua REST API.
Bạn có thể cấu hình chính sách này cho project có tên core-services chỉ với một lệnh gọi API:
HARBOR_URL="https://registry.internal.example.com"
AUTH="admin:SecureAdminPass123!"
# Cấu hình project "core-services" tự động quét image khi push
curl -u "$AUTH" -X PUT "$HARBOR_URL/api/v2.0/projects/core-services" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"auto_scan": "true",
"prevent_vul": "true",
"severity": "high"
}
}'
Với prevent_vul: true và severity: high, Harbor sẽ chủ động chặn các yêu cầu pull đối với bất kỳ image nào chứa CVE mức độ cao (high) hoặc nghiêm trọng (critical) chưa được vá (điểm CVSS >= 7.0). Khi kubelet cố gắng pull một image bị cảnh báo, Harbor sẽ trả về lỗi HTTP 412 (Precondition Failed), ngăn chặn các container tiềm ẩn nguy cơ bảo mật khởi chạy trên môi trường production.
Sử dụng nâng cao: Cross-Registry Replication và Enterprise RBAC
Việc pull các image dung lượng 1.5 GB giữa các region khác nhau sẽ làm chậm quá trình tự động co giãn (autoscaling) của pod và phát sinh chi phí truyền tải mạng (WAN egress) đáng kể. Ví dụ: pull image từ registry trung tâm tại Mỹ về cluster ở châu Âu trong đợt tăng đột biến lưu lượng truy cập có thể gây trễ cold-start từ 30–60 giây cho mỗi node. Harbor giải quyết triệt để vấn đề này bằng các quy tắc replication tự động để đồng bộ (mirror) image giữa registry chính và các registry khu vực.
Thiết lập replication endpoint và rule
Bắt đầu bằng việc đăng ký data center phụ làm mục tiêu replication từ xa:
curl -u "$AUTH" -X POST "$HARBOR_URL/api/v2.0/registries" \
-H "Content-Type: application/json" \
-d '{
"name": "edge-us-west",
"type": "harbor",
"url": "https://edge-registry.uswest.internal.example.com",
"credential": {
"type": "basic",
"access_key": "robot$sync-agent",
"access_secret": "SecretTokenValue456!"
}
}'
Bây giờ, hãy tạo một policy replication dựa trên sự kiện (event-based). Mỗi tag image mới được push lên registry trung tâm sẽ kích hoạt đồng bộ hóa ngay lập tức sang instance ở biên (edge):
curl -u "$AUTH" -X POST "$HARBOR_URL/api/v2.0/replication/policies" \
-H "Content-Type: application/json" \
-d '{
"name": "replicate-core-to-edge",
"src_resource": { "filters": [{ "type": "name", "value": "core-services/**" }] },
"dest_registry": { "id": 1 },
"dest_namespace": "core-services",
"trigger": { "type": "event_based" },
"enabled": true
}'
Phân quyền RBAC chi tiết với OIDC và Robot Account
Tuyệt đối không chia sẻ thông tin đăng nhập cá nhân hoặc token cluster-admin với các hệ thống build tự động. Harbor cung cấp 5 cấp độ vai trò RBAC: Project Admin, Maintainer, Developer, Guest và Limited Guest.
Đối với các CI/CD runner như GitHub Actions hoặc GitLab CI, hãy cấp một robot account có phạm vi giới hạn với thời hạn hết hạn 90 ngày. Giới hạn phạm vi của tài khoản này chỉ cho các thao tác push và pull trong project được chỉ định:
curl -u "$AUTH" -X POST "$HARBOR_URL/api/v2.0/robots" \
-H "Content-Type: application/json" \
-d '{
"name": "ci-builder",
"description": "Token phân quyền cho release workflow",
"duration": 90,
"level": "project",
"permissions": [
{
"kind": "project",
"namespace": "core-services",
"access": [
{ "resource": "repository", "action": "push" },
{ "resource": "repository", "action": "pull" }
]
}
]
}'
Chèn token vừa tạo dưới dạng imagePullSecret trong Kubernetes hoặc biến secret của CI. Trong trường hợp bị lộ, token sẽ tự động hết hạn và không thể chỉnh sửa cấu hình registry hay truy cập vào các project khác.
Kinh nghiệm thực tế khi vận hành trên Production
Để đảm bảo Harbor hoạt động ổn định và đáng tin cậy dưới tải build lớn, bạn cần duy trì các thói quen vận hành thực tế sau:
- Tự động hóa quy tắc giữ lại tag (Tag Retention Rule): Các CI pipeline hoạt động liên tục có thể push hàng trăm bản build mỗi ngày, nhanh chóng làm đầy ổ đĩa bằng các artifact tạm thời. Hãy thiết lập retention policy để chỉ giữ lại 10 tag gần nhất cho các feature branch, đồng thời lưu giữ vô thời hạn các tag phát hành theo chuẩn semantic versioning (chẳng hạn như
v*.*.*). - Lên lịch Garbage Collection vào khung giờ thấp điểm: Thao tác xóa image trên giao diện UI chỉ xóa tham chiếu manifest; các layer blob thực tế vẫn tồn tại trên đĩa. Với một đội ngũ kỹ thuật khoảng 50 lập trình viên, việc chạy garbage collection hàng tuần (ví dụ: vào 02:00 UTC Chủ nhật) thường xuyên giải phóng từ 200 GB đến 400 GB dung lượng rác mà không làm gián đoạn các đợt deployment.
- Sử dụng backend lưu trữ tương thích S3: Các PersistentVolume tiêu chuẩn của Kubernetes khó mở rộng hiệu quả khi dung lượng registry vượt quá 2 TB. Thay vào đó, hãy chuyển hướng lưu trữ blob sang AWS S3, Cloudflare R2 hoặc MinIO bằng cách điều chỉnh mục
persistence.imageChartStoragetrong file Helm values. - Theo dõi độ trễ hàng đợi của Jobservice: Harbor xuất sẵn các Prometheus metric nguyên bản. Hãy thiết lập cảnh báo cho chỉ số
harbor_jobservice_task_queue_size > 25. Hàng đợi bị ứ đọng kéo dài thường là dấu hiệu cho thấy các Trivy scan worker hoặc replication job đang bị quá tải và cần được mở rộng theo chiều ngang (horizontal scaling).

