Triển khai Harbor OCI Registry
Kho lưu trữ an toàn cho Docker images và Helm charts trong doanh nghiệp.
Bối cảnh & Lý do triển khai
Docker Hub có giới hạn pull rate (100 pull/6h cho anonymous), không bảo mật cho image nội bộ chứa code/config nhạy cảm, và phụ thuộc internet. Harbor là private OCI registry: lưu image nội bộ, scan vulnerability tự động trước khi deploy, kiểm soát ai được pull/push image gì.
| Mục | Nội dung |
|---|---|
| Ứng dụng trong DN | Lưu trữ Docker image nội bộ, artifact management, compliance image scanning trước production deploy |
| Tác dụng chính | Private registry với RBAC, Trivy vulnerability scan tự động, Gitea CI push/pull, image signing |
| Nếu không triển khai | CI/CD phải pull từ Docker Hub (rate limit, privacy risk), không có image security gate |
| Các service phụ thuộc vào đây | Gitea CI/CD runners push/pull images; tất cả VM dùng image từ Harbor thay Docker Hub |
Danh sách máy chủ & IP liên quan
Bảng dưới liệt kê các máy chủ mà bài này tạo hoặc kết nối tới. Địa chỉ, VMID, VLAN và node lấy từ bảng quy hoạch chung của lab, dùng thống nhất cho cả bộ bài lab.
| Máy chủ | IP | VLAN · Node | Vai trò trong bài này |
|---|---|---|---|
| harbor (Harbor Registry) · VM239 | 10.11.45.39 | 45 (MGMT) · node2 | Máy chủ của bài — Ubuntu Server 24.04 LTS chạy Harbor 2.15.4 bằng offline installer kèm Trivy; HTTPS cổng 443, cổng 80 chuyển hướng, dữ liệu tại /data. |
| node2 (Proxmox VE) | 10.11.45.211 | 45 (MGMT) · cluster HOATRANHUB | Node Proxmox chứa VM239; tạo VM tại đây. |
| step-ca (step-CA PKI) · VM242 | 10.11.25.42 | 25 (SEC) · node1 | Cấp chứng chỉ TLS cho Harbor (provisioner acme), gia hạn qua systemd timer; phát root CA cho Docker client (bài 13). |
| gitea (Gitea + Actions) · VM240 | 10.11.45.40 | 45 (MGMT) · node2 | Actions runner dùng robot account gitea-ci để build rồi push/pull image (bài 22); webhook Harbor không kích hoạt được Gitea Actions nên không dùng cho CI. |
| mattermost (Mattermost) · VM272 | 10.11.65.57 | 65 (SRV) · node1 | Nhận thông báo push/scan của Harbor vào kênh #deployments qua incoming webhook; relay trên VM239 gọi HTTPS cổng 443 (mục 8.3, bài 37). |
| authentik (Authentik SSO) · VM234 | 10.11.25.40 | 25 (SEC) · node1 | Nhà cung cấp OIDC cho Harbor: provider harbor-oidc, endpoint cổng 9443, Redirect URI /c/oidc/callback (bài 14). |
| pihole (Pi-hole DNS) · VM247 | 10.11.45.53 | 45 (MGMT) · node3 | Phân giải harbor.hoatranlabs.local về 10.11.45.39 (Admin UI hoặc script ở bài 12) và là DNS của VM. |
Gateway của mỗi VLAN là địa chỉ .1. Tên DNS nội bộ do Pi-hole phân giải (bài 12). Tên in đậm là hostname; FQDN = hostname + .hoatranlabs.local.
Tổng Quan
Harbor là OCI-compliant container registry cấp enterprise, hỗ trợ:
| Tính năng | Chi tiết |
|---|---|
| OCI Registry | Docker images, Helm charts, OPA/Rego policies |
| Vulnerability Scanning | Trivy (built-in), tích hợp tự động scan khi push |
| RBAC | Projects, roles, robot accounts cho CI/CD |
| Replication | Đồng bộ images với registry khác (Docker Hub, GHCR...) |
| Webhook | Gửi thông báo push/scan vào Mattermost qua relay nhỏ (mục 8.3) |
| Authentik SSO | OIDC login thay thế username/password nội bộ |
| Quota | Giới hạn dung lượng per-project |
Luồng hoạt động trong lab:
Developer → git push → Gitea (VM240)
→ Gitea Actions Runner → docker build
→ docker push harbor.hoatranlabs.local/project/image:tag
→ Harbor scan với Trivy → notify webhook
→ Deploy lên PVE/K8s
Cổng mở:
| Cổng | Giao thức | Mô tả |
|---|---|---|
| 443/TCP | HTTPS | Harbor UI + API + Registry |
| 80/TCP | HTTP | Redirect sang 443 |
| 8099/TCP | HTTP | Relay webhook Harbor → Mattermost (mục 8.3), chỉ Harbor gọi, có token |
Phiên bản phần mềm sử dụng (đã xác minh 2026-10-15):
| Thành phần | Phiên bản | Ghi chú |
|---|---|---|
| Ubuntu Server | 24.04.5 LTS (noble) | ISO ubuntu-24.04.5-live-server-amd64.iso; hỗ trợ chuẩn tới 04/2029 |
| Docker Engine | 29.9.1 (docker-ce 5:29.9.1-1~ubuntu.24.04~noble) | Repo chính thức download.docker.com/linux/ubuntu noble stable; Harbor yêu cầu Docker Engine > 20.10 |
| Docker Compose plugin / Buildx | 5.6.0 / 0.38.0 | Lệnh docker compose; Harbor yêu cầu Compose > 2.3 |
| Harbor | 2.15.4 | Thay bản 2.11.0 cũ (đã ra ngoài ba nhánh được duy trì, nhiều lỗ hổng High đã vá ở 2.13.6/2.14.5/2.15.3) |
| Trivy / Trivy adapter | 0.75.0 / 0.39.1 | Đi kèm Harbor 2.15.4 theo release notes |
| step-cli | 0.31.0 | Gói step-cli_0.31.0-1_amd64.deb, lệnh thực tế step-cli (có symlink step) |
| PostgreSQL, Redis, nginx | Đi kèm trong container Harbor | Không cài trên host nên không phụ thuộc gói của Ubuntu 24.04 |
Tạo VM239 Trên PVE
Tạo VM · Cài Ubuntu Server 24.04 LTS · Cài Docker
2.1 Tạo VM
Cách 1: Web UI Proxmox (GUI)
- VM ID:
239 - Name:
harbor - Bỏ tick Start after created
- Storage:
local(hoặc nơi chứa ISO) - ISO Image:
ubuntu-24.04.5-live-server-amd64.iso - Guest OS Type:
Linux, Version:6.x - 2.6 Kernel
- Machine:
q35 - SCSI Controller:
VirtIO SCSI single - BIOS:
SeaBIOS - Qemu Agent: ☑
- Bus/Device:
SCSI 0, Storage:vm-ceph(thường làvm-ceph) - Disk size:
100 GiB, Cache:Write back, Discard: ☑
- Sockets:
1, Cores:4, Type:x86-64-v2-AES
- Memory (MiB):
4096
- Bridge:
vmbr0, VLAN Tag:45, Model:VirtIO (paravirtualized), Firewall: ☐
Cách 2: CLI (qm create)
qm create 239 \
--name harbor \
--memory 4096 \
--balloon 0 \
--cores 4 \
--cpu host \
--net0 virtio,bridge=vmbr0,tag=45 \
--scsi0 vm-ceph:100,discard=on,ssd=1 \
--scsihw virtio-scsi-pci \
--ide2 local:iso/ubuntu-24.04.5-live-server-amd64.iso,media=cdrom \
--boot "order=ide2;scsi0" \
--ostype l26 \
--agent enabled=1 \
--onboot 1 \
--startup order=6,up=60
2.2 Cài Ubuntu Server 24.04 LTS
Hostname: harbor
Username: sysadmin
IP: 10.11.45.39/24
Gateway: 10.11.45.1
DNS: 10.11.45.53
Disk: toàn bộ 100 GB, ext4 (40 GB / + 55 GB /data + 5 GB swap)
Packages: OpenSSH server
ubuntu-24.04.5-live-server-amd64.iso (bản point mới nhất của dòng 24.04 trên releases.ubuntu.com, kiểm 2026-10-15; hỗ trợ chuẩn tới 04/2029). Tên card mạng trên VM q35 thường là ens18 hoặc enp6s18, kiểm bằng ip -br link; nếu cloud-init ghi netplan thì file là /etc/netplan/50-cloud-init.yaml./data, nên tách partition riêng 55 GB để dễ quản lý dung lượng sau này.
create-lab-vms.sh (bài 07) với LAB_DATA_STORAGE=vm-bulk thì VM239 có scsi0 = 30 GB trên SSD vm-ceph (hệ điều hành + Docker + image Harbor ≈ 10 GB) và đĩa dữ liệu scsi1 = 60 GB trên HDD vm-bulk dành cho registry (thin provisioning; ước tính dùng thật ≈ 25 GB). Số 100 GB (40 GB / + 55 GB /data + 5 GB swap) ở bài này là trần danh nghĩa/khuyến nghị cho môi trường thật. VM từ template không qua trình cài đặt Ubuntu nên bỏ bước chia phân vùng, gắn scsi1 thành /data (thư mục data_volume của Harbor) TRƯỚC khi chạy ./install.sh:
lsblk -d -o NAME,SIZE,FSTYPE,MODEL # đĩa dữ liệu: khoảng 60G, FSTYPE trống, thường là /dev/sdb; kiểm tên thiết bị trước khi định dạng
sudo mkfs.ext4 -m 0 -L harbor-data /dev/sdb
sudo mkdir -p /data
sudo chattr +i /data # chưa mount thì Harbor không ghi nhầm vào đĩa hệ điều hành
echo "UUID=$(sudo blkid -s UUID -o value /dev/sdb) /data ext4 defaults,noatime,nofail 0 2" | sudo tee -a /etc/fstab
sudo systemctl daemon-reload && sudo mount -a && df -h /data
2.3 Cài Docker
Dùng repo Docker chính thức cho Ubuntu 24.04 (suite noble, dạng deb822 docker.sources + Signed-By, không dùng apt-key). Chạy bằng quyền root (sudo -i).
# Cập nhật hệ thống
# (Ubuntu 24.04: needrestart có thể hiện hộp thoại chọn dịch vụ cần khởi động lại; đặt biến này để tự xử lý)
export NEEDRESTART_MODE=a
apt update && apt upgrade -y
# Gỡ gói Docker không chính thức nếu có (docker.io, docker-compose-v2, podman-docker... của Ubuntu)
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
apt-get remove -y "$pkg" 2>/dev/null || true
done
# Cài Docker CE từ repo chính thức (suite noble)
apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
tee /etc/apt/sources.list.d/docker.sources > /dev/null << EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# Cài qemu-guest-agent
apt install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent
# Xác nhận (kiểm 2026-10-15 trên repo noble: docker-ce 29.9.1, Compose plugin 5.6.0, Buildx 0.38.0)
docker --version && docker compose version
Suites: được shell thay bằng noble nhờ heredoc không đặt nháy (<< EOF); mở /etc/apt/sources.list.d/docker.sources kiểm tra lại trước khi apt update. Docker chỉ hỗ trợ iptables-nft/iptables-legacy, và cổng container đã publish (443, 80...) có thể đi vòng qua luật ufw, nên lọc truy cập ở FortiGate (mục 9.2) thay vì chỉ dựa vào ufw.
Cấu Hình TLS Từ step-CA (VM242)
Tự Động Gia Hạn Cert
# Cài step CLI 0.31.0 (gói .deb của Smallstep)
wget https://github.com/smallstep/cli/releases/download/v0.31.0/step-cli_0.31.0-1_amd64.deb
apt install -y ./step-cli_0.31.0-1_amd64.deb
rm -f step-cli_0.31.0-1_amd64.deb
# Gói .deb 0.31.0 chỉ cài /usr/bin/step-cli (đã kiểm nội dung gói); tạo lệnh `step` để mọi lệnh bên dưới và service gia hạn (/usr/local/bin/step) chạy như cũ
ln -sf /usr/bin/step-cli /usr/local/bin/step
step version
# Bootstrap step-CA trust
step ca bootstrap \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--fingerprint <fingerprint-cua-step-CA>
# Lấy fingerprint từ VM242: step certificate fingerprint /etc/step-ca/certs/root_ca.crt
# Tạo thư mục chứa cert
mkdir -p /etc/ssl/harbor
# Cấp certificate
step ca certificate "harbor.hoatranlabs.local" \
/etc/ssl/harbor/harbor.crt \
/etc/ssl/harbor/harbor.key \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--provisioner acme \
--san harbor.hoatranlabs.local \
--san 10.11.45.39
chmod 600 /etc/ssl/harbor/harbor.key
# Copy root CA cert cho Docker daemon trust
step ca root /usr/local/share/ca-certificates/hoatranlabs-root.crt
update-ca-certificates
3.1 Tự Động Gia Hạn Cert
cat > /etc/systemd/system/harbor-cert-renew.service << 'EOF'
[Unit]
Description=Renew Harbor TLS certificate from step-CA
After=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/local/bin/step ca renew \
/etc/ssl/harbor/harbor.crt \
/etc/ssl/harbor/harbor.key \
--force \
--ca-url https://step-ca.hoatranlabs.local:9000
# Harbor chỉ sao chép cert vào /data/secret/cert khi chạy ./prepare, nên phải prepare lại rồi mới restart proxy (nginx)
ExecStartPost=/bin/bash -c "cd /opt/harbor && ./prepare --with-trivy && docker compose restart proxy"
EOF
cat > /etc/systemd/system/harbor-cert-renew.timer << 'EOF'
[Unit]
Description=Renew Harbor TLS certificate daily
[Timer]
OnCalendar=*-*-* 03:00:00
RandomizedDelaySec=1800
Persistent=true
[Install]
WantedBy=timers.target
EOF
systemctl daemon-reload
systemctl enable --now harbor-cert-renew.timer
Tải Và Cài Harbor
Tải Harbor Offline Installer · Cấu Hình harbor.yml · Chạy Installer
4.1 Tải Harbor Offline Installer
RELEASES.md của Harbor, dự án chỉ duy trì ba nhánh minor mới nhất (hiện là 2.13, 2.14, 2.15), nên 2.11.x không còn nhận bản vá. Các bản 2.13.6, 2.14.5 và 2.15.3 (06/10/2026) vá nhiều lỗ hổng mức High (path traversal ở endpoint distribution, system robot tự nâng quyền admin, robot cover-all-projects, auth-proxy "admin") và SSRF ở webhook. 2.15.4 (09/10/2026) là bản "Latest" tại thời điểm viết; hãy xem https://github.com/goharbor/harbor/releases để biết bản mới hơn. Chưa kiểm được trên máy thật.
HARBOR_VERSION="2.15.4"
cd /tmp
# Tải offline installer (bao gồm tất cả Docker images, ~750 MB) và file md5sum của bản phát hành
wget https://github.com/goharbor/harbor/releases/download/v${HARBOR_VERSION}/harbor-offline-installer-v${HARBOR_VERSION}.tgz
wget https://github.com/goharbor/harbor/releases/download/v${HARBOR_VERSION}/md5sum
# Kiểm tra toàn vẹn (md5sum chỉ phát hiện tải lỗi, KHÔNG chứng minh nguồn gốc)
grep "harbor-offline-installer-v${HARBOR_VERSION}.tgz" md5sum | md5sum -c -
# Giải nén
tar xzf harbor-offline-installer-v${HARBOR_VERSION}.tgz -C /opt/
cd /opt/harbor
Xác minh nguồn gốc (tùy chọn nhưng nên làm): các bản gần đây của Harbor không còn file chữ ký .asc (đã kiểm: v2.15.4 trả 404 cho .asc, trong khi v2.11.0 có) mà đính kèm bundle Sigstore harbor-offline-installer-v${HARBOR_VERSION}.tgz.sigstore.json. Cài cosign theo https://docs.sigstore.dev/cosign/system_config/installation/ rồi chạy (định danh bên dưới suy ra từ chứng chỉ Fulcio nằm trong bundle của v2.15.4, workflow publish_release.yml trên GitHub Actions; Harbor chưa công bố lệnh này trong tài liệu nên cần kiểm lại trên máy thật):
cd /tmp
wget https://github.com/goharbor/harbor/releases/download/v${HARBOR_VERSION}/harbor-offline-installer-v${HARBOR_VERSION}.tgz.sigstore.json
cosign verify-blob harbor-offline-installer-v${HARBOR_VERSION}.tgz \
--bundle harbor-offline-installer-v${HARBOR_VERSION}.tgz.sigstore.json \
--certificate-identity "https://github.com/goharbor/harbor/.github/workflows/publish_release.yml@refs/tags/v${HARBOR_VERSION}" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
# Kỳ vọng: Verified OK
4.2 Cấu Hình harbor.yml
cp harbor.yml.tmpl harbor.yml
Chỉnh sửa /opt/harbor/harbor.yml:
# ====================================================
# Harbor Configuration — hoatranlabs.local lab
# Version: 2.15.4 (file mẫu harbor.yml.tmpl của 2.15 có _version: 2.15.0)
# ====================================================
_version: 2.15.0
hostname: harbor.hoatranlabs.local
# HTTP (chỉ dùng để redirect sang HTTPS)
http:
port: 80
# HTTPS
https:
port: 443
certificate: /etc/ssl/harbor/harbor.crt
private_key: /etc/ssl/harbor/harbor.key
# Harbor admin password (đổi ngay sau lần đầu login)
harbor_admin_password: Admin@Harbor2024!
# Database (PostgreSQL nội bộ Harbor)
database:
password: Harbor@DB2024!
max_idle_conns: 50
max_open_conns: 1000
conn_max_lifetime: 5m
conn_max_idle_time: 0
# Data volume: partition riêng 55 GB (lab: đĩa scsi1 60 GB trên HDD vm-bulk gắn tại /data, xem mục 2.2)
data_volume: /data
# Trivy vulnerability scanner
trivy:
ignore_unfixed: false
skip_update: false
offline_scan: false
security_check: vuln
insecure: false
# github_token: xxx # tùy chọn: tăng giới hạn tải DB Trivy (mặc định tmpl 2.15 để comment)
timeout: 5m0s
# JobService
jobservice:
max_job_workers: 10
job_loggers:
- STD_OUTPUT
- FILE
logger_sweeper_duration: 1 # days
# Log
log:
level: info
local:
rotate_count: 50
rotate_size: 200M
location: /var/log/harbor
# External URL (dùng khi có proxy hoặc load balancer)
external_url: https://harbor.hoatranlabs.local
# Proxy cache (tùy chọn — dùng cho pull-through cache)
# proxy:
# http_proxy:
# https_proxy:
# no_proxy:
# Upload limit
upload_purging:
enabled: true
age: 168h
interval: 24h
dryrun: false
# Webhook tới địa chỉ nội bộ (relay 10.11.45.39:8099 ở mục 8.3).
# Harbor 2.15.3 chặn mặc định webhook tới IP private (GHSA-2phj-cp9f-qq6w); 2.15.4 đặt lại mặc định true.
# Giữ true tường minh để relay hoạt động; chỉ nên dùng khi mọi project admin đều đáng tin.
network:
allow_private_network_access: true
harbor.yml.tmpl (ví dụ notification.webhook_job_max_retry, content_trust.legacy_signer_pull_enabled, cache, trivy.db_repository); khi chưa cần thì giữ mặc định của file mẫu. Khóa network.allow_private_network_access và giá trị mặc định lấy từ harbor.yml.tmpl nhánh v2.15.4; cần kiểm lại trên máy thật sau ./prepare.
4.3 Chạy Installer
cd /opt/harbor
# Cài với Trivy scanner
./install.sh --with-trivy
# Xác nhận tất cả containers đang chạy
docker compose ps
Kết quả mong đợi — tất cả containers ở trạng thái healthy:
NAME STATUS PORTS
harbor-core healthy
harbor-db healthy
harbor-jobservice healthy
harbor-log running
harbor-portal healthy
redis healthy
registry healthy
registryctl healthy
trivy-adapter healthy
nginx healthy 0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp
Cấu Hình Sau Cài Đặt
Đổi Admin Password · Tạo Projects · Tạo Robot Account Cho Gitea CI/CD
5.1 Đổi Admin Password
Truy cập https://harbor.hoatranlabs.local, đăng nhập với admin / Admin@Harbor2024!, đổi mật khẩu ngay.
5.2 Tạo Projects
# Tạo project "infrastructure" cho images nền tảng
curl -u admin:Admin@Harbor2024! -X POST https://harbor.hoatranlabs.local/api/v2.0/projects \
-H "Content-Type: application/json" \
-d '{
"project_name": "infrastructure",
"public": false,
"metadata": {
"public": "false",
"enable_content_trust": "false",
"prevent_vul": "true",
"severity": "high",
"auto_scan": "true"
}
}'
# Tạo project "apps" cho ứng dụng nội bộ
curl -u admin:Admin@Harbor2024! -X POST https://harbor.hoatranlabs.local/api/v2.0/projects \
-H "Content-Type: application/json" \
-d '{
"project_name": "apps",
"public": false,
"metadata": {
"public": "false",
"auto_scan": "true"
}
}'
5.3 Tạo Robot Account Cho Gitea CI/CD
# Robot account với quyền push/pull tất cả projects
curl -u admin:Admin@Harbor2024! \
-X POST https://harbor.hoatranlabs.local/api/v2.0/robots \
-H "Content-Type: application/json" \
-d '{
"name": "gitea-ci",
"description": "Gitea Actions CI/CD robot account",
"duration": 365,
"level": "system",
"permissions": [
{
"kind": "project",
"namespace": "*",
"access": [
{"action": "push", "resource": "repository"},
{"action": "pull", "resource": "repository"},
{"action": "read", "resource": "artifact"},
{"action": "create", "resource": "tag"},
{"action": "delete", "resource": "tag"}
]
}
]
}'
robot$gitea-ci token vào Gitea Secrets: Settings → Secrets → HARBOR_PASS
user:update của system robot. Sau khi tạo, vào Administration → Robot Accounts → gitea-ci kiểm tra quyền thực tế (push/pull trên infrastructure, apps); nếu docker login/push bị từ chối thì cấp quyền theo từng project. Cần kiểm lại trên máy thật.
Tích Hợp Authentik SSO (OIDC)
Tạo OAuth2 Provider Trên Authentik (VM234) · Cấu Hình OIDC Trong Harbor
6.1 Tạo OAuth2 Provider Trên Authentik (VM234)
Đăng nhập Authentik Admin: https://authentik.hoatranlabs.local:9443/if/admin/
- Name:
harbor-oidc - Client type: Confidential
- Client ID:
harbor(hoặc auto-generate) - Redirect URIs:
https://harbor.hoatranlabs.local/c/oidc/callback - Signing Key: chọn key của Authentik
- Scopes:
openid,profile,email,groups,offline_access
- Name:
Harbor Registry - Slug:
harbor - Provider:
harbor-oidc
# Ghi lại các giá trị:
CLIENT_ID="<từ-authentik>"
CLIENT_SECRET="<từ-authentik>"
AUTHENTIK_ISSUER="https://authentik.hoatranlabs.local:9443/application/o/harbor/"
6.2 Cấu Hình OIDC Trong Harbor
Đăng nhập Harbor Admin → Administration → Configuration → Authentication:
Auth Mode: OIDC
OIDC Provider Name: Authentik
OIDC Endpoint: https://authentik.hoatranlabs.local:9443/application/o/harbor/
OIDC Client ID: <CLIENT_ID>
OIDC Client Secret: <CLIENT_SECRET>
Group Claim Name: groups
OIDC Scope: openid,profile,email,groups,offline_access
Verify Certificate: OFF (Harbor core chạy trong container, không dùng trust store của host nên không tin root CA step-CA; theo tài liệu Harbor, bỏ chọn khi provider dùng chứng chỉ CA nội bộ)
Automatic onboarding: ON
Username Claim: preferred_username
Lưu lại → đăng xuất → ở trang đăng nhập bấm nút LOGIN WITH Authentik để kiểm tra (Harbor ghép tên ở ô OIDC Provider Name vào nhãn nút; nếu để trống ô đó thì nút ghi LOGIN VIA OIDC PROVIDER; hành vi này đã mô tả cho 2.11, cần kiểm lại trên 2.15.4 ở máy thật).
Phân Phối Root CA Cho Docker Clients
Tất cả VM cần pull/push image từ Harbor phải trust root CA của step-CA:
# Script chạy trên mỗi VM client
HARBOR_HOST="harbor.hoatranlabs.local"
CA_CERT_URL="https://step-ca.hoatranlabs.local:9000/roots.pem"
# Tạo thư mục cert cho Docker
mkdir -p /etc/docker/certs.d/${HARBOR_HOST}/
# Download và lưu root CA (dùng -k vì client chưa tin root CA ở lần đầu; roots.pem là chứng chỉ công khai)
curl -fsSLk ${CA_CERT_URL} \
-o /etc/docker/certs.d/${HARBOR_HOST}/ca.crt
# Đối chiếu fingerprint với root CA trên VM242: step certificate fingerprint /etc/step-ca/certs/root_ca.crt
openssl x509 -in /etc/docker/certs.d/${HARBOR_HOST}/ca.crt -noout -fingerprint -sha256
# Cài vào system trust store
cp /etc/docker/certs.d/${HARBOR_HOST}/ca.crt \
/usr/local/share/ca-certificates/hoatranlabs-root.crt
update-ca-certificates
# Restart Docker daemon
systemctl restart docker
# Test login
docker login harbor.hoatranlabs.local \
-u robot\$gitea-ci \
-p <robot-token>
# Test pull
docker pull harbor.hoatranlabs.local/infrastructure/ubuntu:24.04
Cấu Hình Vulnerability Scanning
Bật Auto-Scan Khi Push · Cập Nhật Trivy Database · Webhook Thông Báo Scan Kết Quả
8.1 Bật Auto-Scan Khi Push
Đây là cài đặt theo từng project: Harbor Admin → Projects → chọn project (infrastructure, apps) → Configuration:
Automatically scan images on push: ON
(Hai project ở mục 5.2 đã được bật sẵn bằng auto_scan: "true".)
8.2 Cập Nhật Trivy Database
# Trivy tự cập nhật database khi scan
# Để update thủ công:
docker exec trivy-adapter trivy image --download-db-only
# Lịch cập nhật DB hàng ngày (Harbor tự xử lý nếu skip_update=false)
8.3 Webhook Thông Báo Scan Kết Quả
Webhook của Harbor chỉ POST JSON sự kiện (loại HTTP, payload Default gồm type, occur_at, operator, event_data) tới một endpoint, và ô Auth Header được gửi nguyên giá trị vào header Authorization. Vì vậy không trỏ thẳng được vào Gitea hay Mattermost:
- Gitea Actions không có endpoint nhận payload tùy ý (
workflow_dispatchcần body córef, còn.../repos/<org>/<repo>/topicslà API sửa topic của repo), nên webhook Harbor không kích hoạt được pipeline. CI vẫn là Gitea Actions chủ động build và đẩy image lên Harbor (bài 22). - Mattermost incoming webhook bắt buộc có trường
text(hoặcattachments). Payload Default của Harbor không có, còn loạiSLACKcủa Harbor chỉ gửi Block Kitblockskhông cótext, nên cả hai đều bị Mattermost trả lỗi 400 "No text specified".
Cách khả thi: chạy một relay nhỏ ngay trên VM239, nhận JSON của Harbor rồi đổi thành {"text": ...} và gửi vào Mattermost incoming webhook của kênh #deployments (tạo ở bài 37 mục 3.3).
- Cài relay trên VM239 (Python 3.12 có sẵn trên Ubuntu 24.04, relay chỉ dùng thư viện chuẩn nên không cần
pip/venv; VM239 đã tin root CA step-CA ở mục 3 nên gọi được HTTPS tới Mattermost):
sudo mkdir -p /opt/harbor-mm-relay
sudo tee /opt/harbor-mm-relay/relay.py << 'EOF'
#!/usr/bin/env python3
# Nhận webhook của Harbor (kind HTTP, payload Default) -> gửi {"text": ...} vào Mattermost incoming webhook
import json
import os
import urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
MM_URL = os.environ["MM_WEBHOOK_URL"]
TOKEN = "Bearer " + os.environ["RELAY_TOKEN"] # Harbor gửi nguyên "Auth Header" vào header Authorization
BIND = (os.environ.get("RELAY_BIND", "10.11.45.39"), int(os.environ.get("RELAY_PORT", "8099")))
def render(ev):
data = ev.get("event_data", {})
res = (data.get("resources") or [{}])[0]
url = res.get("resource_url") or data.get("repository", {}).get("repo_full_name", "?")
kind = ev.get("type", "?")
if kind == "PUSH_ARTIFACT":
return f":package: **Harbor** — image mới `{url}` (push bởi {ev.get('operator', '?')})"
if kind == "SCANNING_COMPLETED":
ov = next(iter(res.get("scan_overview", {}).values()), {})
s = ov.get("summary", {})
by_sev = ", ".join(f"{k}: {v}" for k, v in s.get("summary", {}).items()) or "không có lỗ hổng"
return (f":mag: **Harbor** — quét xong `{url}`: mức cao nhất **{ov.get('severity', '?')}**, "
f"tổng {s.get('total', 0)} ({s.get('fixable', 0)} có bản vá) — {by_sev}")
if kind in ("SCANNING_FAILED", "SCANNING_STOPPED"):
return f":x: **Harbor** — {kind} cho `{url}`"
return f":information_source: **Harbor** — {kind} `{url}`"
class Relay(BaseHTTPRequestHandler):
def do_POST(self):
if self.headers.get("Authorization") != TOKEN:
return self.reply(401)
try:
ev = json.loads(self.rfile.read(int(self.headers.get("Content-Length", 0))) or b"{}")
req = urllib.request.Request(MM_URL, json.dumps({"text": render(ev)}).encode(),
{"Content-Type": "application/json"})
urllib.request.urlopen(req, timeout=2).read()
except Exception as exc: # trả 502 để Harbor gửi lại
self.log_error("loi: %s", exc)
return self.reply(502)
self.reply(200)
def reply(self, code):
self.send_response(code)
self.end_headers()
ThreadingHTTPServer(BIND, Relay).serve_forever()
EOF
# Cấu hình: URL incoming webhook #deployments, token dùng chung với Harbor (openssl rand -hex 24), IP lắng nghe
sudo tee /etc/harbor-mm-relay.env << 'EOF'
MM_WEBHOOK_URL=https://mattermost.hoatranlabs.local/hooks/<id-deployments>
RELAY_TOKEN=<token-ngẫu-nhiên>
RELAY_BIND=10.11.45.39
EOF
sudo chmod 600 /etc/harbor-mm-relay.env
sudo tee /etc/systemd/system/harbor-mm-relay.service << 'EOF'
[Unit]
Description=Harbor webhook to Mattermost relay
After=network-online.target
[Service]
EnvironmentFile=/etc/harbor-mm-relay.env
ExecStart=/usr/bin/python3 /opt/harbor-mm-relay/relay.py
User=nobody
Restart=on-failure
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now harbor-mm-relay
harbor-jobservice gọi relay qua IP của VM239 (10.11.45.39:8099). Nếu sau này bật UFW trên VM239 thì cần ufw allow from 172.16.0.0/12 to any port 8099 proto tcp cho dải mạng Docker.
- Tạo webhook trong Harbor: Harbor Admin → Project: apps → Webhooks → New Webhook:
Webhook Name: mattermost-deployments
Notify Type: HTTP (Payload Format: Default)
Event Type: Artifact pushed, Scanning finished, Scanning failed
Endpoint URL: http://10.11.45.39:8099/harbor
Auth Header: Bearer <token-ngẫu-nhiên> # đúng giá trị RELAY_TOKEN
Verify Remote Certificate: bỏ chọn (relay chạy HTTP)
Harbor chỉ giữ phần scheme/host/path của URL (bỏ query string), nên token đặt ở Auth Header chứ không đặt trên URL.
10.11.45.39:8099, kiểm tra network.allow_private_network_access: true trong harbor.yml (mục 4.2), chạy lại ./prepare --with-trivy rồi docker compose up -d. Tùy chọn này tắt hoàn toàn lớp bảo vệ SSRF nên chỉ dùng khi các project admin đều đáng tin, và nên chặn 169.254.169.254 ở tầng mạng (theo release notes).
- Kiểm tra:
curl -i -X POST http://10.11.45.39:8099/harbor \
-H "Authorization: Bearer <token-ngẫu-nhiên>" -H "Content-Type: application/json" \
-d '{"type":"PUSH_ARTIFACT","operator":"test","event_data":{"resources":[{"resource_url":"harbor.hoatranlabs.local/apps/test:1"}]}}'
# Kỳ vọng: HTTP 200 và tin nhắn "image mới ..." xuất hiện trong #deployments
# Lỗi: xem log relay; Harbor tự gửi lại khi endpoint trả lỗi (notification.webhook_job_max_retry trong harbor.yml)
sudo journalctl -u harbor-mm-relay -n 30 --no-pager
Sau đó push một image vào project apps (bài 22): kênh #deployments nhận thông báo "image mới" rồi "quét xong" kèm mức lỗ hổng cao nhất của Trivy.
DNS Và Firewall
DNS Pi-hole (VM247) · Firewall Rules
9.1 DNS Pi-hole (VM247)
# SSH vào VM247
ssh [email protected]
# Thêm A record (Pi-hole chạy trong Docker, bài 12):
# Admin UI → Settings → Local DNS Records: harbor.hoatranlabs.local → 10.11.45.39
# hoặc chạy script ở bài 12 (đã có sẵn record harbor):
/opt/pihole/scripts/add_dns_records.sh
# Restart DNS
docker exec pihole pihole reloaddns
9.2 Firewall Rules
# Tất cả VLAN nội bộ truy cập Harbor registry
ALLOW TCP 10.11.0.0/16 10.11.45.39 443 # HTTPS Harbor UI + push/pull
ALLOW TCP 10.11.0.0/16 10.11.45.39 80 # HTTP → redirect HTTPS
# Relay webhook (mục 8.3) trên VM239 gọi Mattermost (VLAN_MGMT → VLAN_SRV)
ALLOW TCP 10.11.45.39 10.11.65.57 443 # Harbor → Mattermost incoming webhook
# Chặn truy cập từ Internet (Harbor là internal only)
DENY any WAN 10.11.45.39 any
Backup Harbor
cat > /opt/harbor/backup-harbor.sh << 'SCRIPT'
#!/bin/bash
set -e
BACKUP_DIR="/backup/harbor"
DATE=$(date +%Y%m%d-%H%M)
mkdir -p "$BACKUP_DIR"
echo "[$(date)] Backing up Harbor database..."
# Database backup (phải dump khi container harbor-db còn chạy, trước khi stop)
docker exec harbor-db pg_dumpall -U postgres > "$BACKUP_DIR/harbor-db-$DATE.sql"
echo "[$(date)] Stopping Harbor for backup..."
cd /opt/harbor
docker compose stop
echo "[$(date)] Backing up Harbor data..."
# Images và config. Lab (scsi0 30 GB, registry 60 GB trên scsi1): --exclude=/data/registry bỏ blob image khỏi tar vì
# 7 bản tar của registry không vừa đĩa hệ điều hành; image dựng lại được từ CI (Gitea), còn muốn giữ nguyên registry thì
# backup cả VM239 bằng PBS (bài 04), đĩa scsi1 nằm trong bản backup đó. Có chỗ chứa đủ thì xóa tùy chọn --exclude (cần kiểm lại trên máy thật)
tar czf "$BACKUP_DIR/harbor-data-$DATE.tar.gz" --exclude=/data/registry /data /opt/harbor/harbor.yml
echo "[$(date)] Starting Harbor..."
docker compose start
# Giữ 7 bản gần nhất
find "$BACKUP_DIR" -name "harbor-*.tar.gz" -mtime +7 -delete
find "$BACKUP_DIR" -name "harbor-db-*.sql" -mtime +7 -delete
echo "[$(date)] Backup done: $DATE"
SCRIPT
chmod +x /opt/harbor/backup-harbor.sh
# Cron job 4:00 sáng
(crontab -l 2>/dev/null; echo "0 4 * * * /opt/harbor/backup-harbor.sh >> /var/log/harbor-backup.log 2>&1") \
| crontab -
Troubleshooting
Harbor Containers Không Healthy · Push Image Lỗi: "x509: certificate signed by unknown authority" · OIDC Login Không Hoạt Động
11.1 Harbor Containers Không Healthy
# Kiểm tra toàn bộ containers
# (docker compose dùng tên service: core, postgresql, trivy-adapter...; docker exec dùng tên container: harbor-core, harbor-db, trivy-adapter...)
cd /opt/harbor
docker compose ps
docker compose logs core --tail=50
docker compose logs postgresql --tail=50
# Harbor core thường fail nếu DB chưa sẵn sàng → đợi thêm 30s
docker compose restart core
11.2 Push Image Lỗi: "x509: certificate signed by unknown authority"
# Trên client VM — kiểm tra cert đã được trust chưa
ls /etc/docker/certs.d/harbor.hoatranlabs.local/
openssl s_client -connect harbor.hoatranlabs.local:443 \
-CAfile /etc/docker/certs.d/harbor.hoatranlabs.local/ca.crt </dev/null 2>/dev/null | grep "Verify return code"
# Kỳ vọng: Verify return code: 0 (ok)
# Nếu chưa có cert folder:
mkdir -p /etc/docker/certs.d/harbor.hoatranlabs.local/
cp /usr/local/share/ca-certificates/hoatranlabs-root.crt \
/etc/docker/certs.d/harbor.hoatranlabs.local/ca.crt
systemctl restart docker
11.3 OIDC Login Không Hoạt Động
# Kiểm tra Authentik application slug có khớp redirect URI không
# Harbor redirect: https://harbor.hoatranlabs.local/c/oidc/callback
# Authentik redirect phải cho phép URI trên
# Test OIDC discovery endpoint
curl -sk https://authentik.hoatranlabs.local:9443/application/o/harbor/.well-known/openid-configuration | python3 -m json.tool
# Harbor logs
docker compose logs core | grep -i oidc
11.4 Trivy Không Scan Được
# Kiểm tra Trivy adapter
docker compose logs trivy-adapter --tail=30
# Update Trivy DB thủ công
docker exec trivy-adapter trivy image --download-db-only
# Nếu lỗi kết nối Internet (air-gapped):
# Tải DB offline từ máy có Internet:
# https://github.com/aquasecurity/trivy-db/releases
# Copy vào container và set TRIVY_SKIP_DB_UPDATE=true
11.5 Harbor Chiếm Quá Nhiều Disk
# Kiểm tra dung lượng /data
df -h /data
du -sh /data/*
# GC (Garbage Collection) để xóa unreferenced blobs
# Harbor Admin → Administration → Clean Up → Garbage Collection → GC Now
# Hoặc qua API:
curl -u admin:<pass> -X POST https://harbor.hoatranlabs.local/api/v2.0/system/gc/schedule \
-H "Content-Type: application/json" \
-d '{"schedule": {"type": "Manual"}}'
Giữ registry nhỏ trong lab (đĩa dữ liệu scsi1 60 GB; ước tính bài 07 mục 8.6 dùng thật ≈ 25 GB). Theo tài liệu Harbor, ba việc sau đi cùng nhau; tên menu cần kiểm lại trên Harbor 2.15.4 của bạn:
- Tag Retention (gỡ tag cũ): Projects → chọn project → Policy → Tag Retention → Add Rule, ví dụ Repositories matching
**, "retain the most recently pushed # artifacts" =10, Tags matching**; đặt Schedule hằng tuần, bấm Dry Run trước rồi mới Run Now (rule đã chạy không hoàn tác được; tối đa 15 rule mỗi project). Retention chỉ gỡ tag, chưa giải phóng đĩa. - Garbage Collection (thu hồi blob không còn tham chiếu): Administration → Clean Up → Garbage Collection, chọn lịch Weekly (nửa đêm thứ Bảy), tick Allow garbage collection on untagged artifacts, Save; bấm DRY RUN để xem dung lượng sẽ thu hồi. Đặt lịch retention chạy trước GC.
- Project Quotas (chặn một project ăn hết
/data): Administration → Project Quotas → chọn project → Edit, ví dụapps20 GiB vàinfrastructure15 GiB. Quota tính riêng từng project nên blob dùng chung bị tính lặp.
Checklist Hoàn Thành
- VM239 tạo trên node2, tag VLAN 45, IP 10.11.45.39, disk 100 GB
- Ubuntu Server 24.04 LTS cài đặt,
/datapartition riêng 55 GB - Docker CE cài thành công từ repo
noble(docker compose versionchạy được) - step-CA cert cấp cho
harbor.hoatranlabs.local, systemd timer gia hạn tự động -
harbor.ymlcấu hình với hostname, TLS, data_volume, Trivy -
./install.sh --with-trivychạy thành công, 10 containers healthy - Truy cập
https://harbor.hoatranlabs.localthành công, đổi admin password - Project
infrastructurevàappstạo thành công, auto-scan ON - Robot account
gitea-citạo thành công, token lưu vào Gitea Secrets - Authentik OIDC Provider tạo, cấu hình Harbor authentication → OIDC
- Đăng nhập Harbor qua Authentik thành công
- Root CA phân phối lên tất cả VM client
-
docker login harbor.hoatranlabs.localtừ client thành công - Trivy scan hoạt động khi push image
- Relay
harbor-mm-relaychạy, webhookmattermost-deploymentsgửi thông báo push/scan vào#deployments(mục 8.3) - DNS record
harbor.hoatranlabs.local → 10.11.45.39thêm vào Pi-hole - Firewall rules VLAN nội bộ → port 443 allowed
- Backup script
/opt/harbor/backup-harbor.shvà cron job thiết lập
Tài liệu tham khảo (đã dùng khi cập nhật lên Ubuntu 24.04, kiểm 2026-10-15):
- Docker Engine trên Ubuntu (repo apt, deb822): https://docs.docker.com/engine/install/ubuntu/
- Harbor: yêu cầu cài đặt https://goharbor.io/docs/main/install-config/installation-prereqs/ · chạy installer https://goharbor.io/docs/main/install-config/run-installer-script/ · bản phát hành https://github.com/goharbor/harbor/releases · chính sách nhánh được duy trì https://github.com/goharbor/harbor/blob/main/RELEASES.md
- step-cli: https://github.com/smallstep/cli/releases
- Ubuntu 24.04 ISO: https://releases.ubuntu.com/24.04/
Tài liệu: HOATRANLABS Infrastructure — Harbor OCI Registry v2.15.4 trên Ubuntu 24.04 LTS
Cập nhật: 2026-10-15