System & Network Harbor OCI Registry
Bài 21 · Giai đoạn 4 — DevOps & Quản lý

Triển khai Harbor OCI Registry

Kho lưu trữ an toàn cho Docker images và Helm charts trong doanh nghiệp.

VM239 Ubuntu 24.04 Giai đoạn: DevOps & Quản lý

Bối cảnh & Lý do triển khai

Vị trí trong chuỗi bài: Bài 21 thuộc Giai đoạn 4 — DevOps & Quản lý, nối tiếp Bài 20. Headscale VPN và đứng trước Bài 22. Gitea CI/CD.
Mức độ cần thiết: 🟡 Quan trọng — Private registry cho CI/CD pipeline nội bộ

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ụcNội dung
Ứng dụng trong DNLưu trữ Docker image nội bộ, artifact management, compliance image scanning trước production deploy
Tác dụng chínhPrivate registry với RBAC, Trivy vulnerability scan tự động, Gitea CI push/pull, image signing
Nếu không triển khaiCI/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 đâyGitea CI/CD runners push/pull images; tất cả VM dùng image từ Harbor thay Docker Hub
Cụm: HOATRANHUB — PVE 9.2.20 Node: node2 (10.11.45.211) — VLAN: VLAN_MGMT tag 45 VM: 239 | IP: 10.11.45.39/24 | GW: 10.11.45.1 | DNS: 10.11.45.53 Tài nguyên: 4 vCPU · 4 GB RAM · 100 GB (vm-ceph) Domain: harbor.hoatranlabs.local

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ủIPVLAN · NodeVai trò trong bài này
harbor (Harbor Registry) · VM23910.11.45.3945 (MGMT) · node2Má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.21145 (MGMT) · cluster HOATRANHUBNode Proxmox chứa VM239; tạo VM tại đây.
step-ca (step-CA PKI) · VM24210.11.25.4225 (SEC) · node1Cấ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) · VM24010.11.45.4045 (MGMT) · node2Actions 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) · VM27210.11.65.5765 (SRV) · node1Nhậ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) · VM23410.11.25.4025 (SEC) · node1Nhà 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) · VM24710.11.45.5345 (MGMT) · node3Phâ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.

01

Tổng Quan

Harbor là OCI-compliant container registry cấp enterprise, hỗ trợ:

Tính năngChi tiết
OCI RegistryDocker images, Helm charts, OPA/Rego policies
Vulnerability ScanningTrivy (built-in), tích hợp tự động scan khi push
RBACProjects, roles, robot accounts cho CI/CD
ReplicationĐồng bộ images với registry khác (Docker Hub, GHCR...)
WebhookGửi thông báo push/scan vào Mattermost qua relay nhỏ (mục 8.3)
Authentik SSOOIDC login thay thế username/password nội bộ
QuotaGiớ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ổngGiao thứcMô tả
443/TCPHTTPSHarbor UI + API + Registry
80/TCPHTTPRedirect sang 443
8099/TCPHTTPRelay 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ầnPhiên bảnGhi chú
Ubuntu Server24.04.5 LTS (noble)ISO ubuntu-24.04.5-live-server-amd64.iso; hỗ trợ chuẩn tới 04/2029
Docker Engine29.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 / Buildx5.6.0 / 0.38.0Lệnh docker compose; Harbor yêu cầu Compose > 2.3
Harbor2.15.4Thay 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 adapter0.75.0 / 0.39.1Đi kèm Harbor 2.15.4 theo release notes
step-cli0.31.0Gó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 HarborKhông cài trên host nên không phụ thuộc gói của Ubuntu 24.04
02

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)

1
Đăng nhập Proxmox Web UI → chọn Node: node2 → nhấn Create VM (góc trên phải)
2
General:
  • VM ID: 239
  • Name: harbor
  • Bỏ tick Start after created
3
OS:
  • 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
4
System:
  • Machine: q35
  • SCSI Controller: VirtIO SCSI single
  • BIOS: SeaBIOS
  • Qemu Agent: ☑
5
Disks:
  • Bus/Device: SCSI 0, Storage: vm-ceph (thường là vm-ceph)
  • Disk size: 100 GiB, Cache: Write back, Discard: ☑
6
CPU:
  • Sockets: 1, Cores: 4, Type: x86-64-v2-AES
7
Memory:
  • Memory (MiB): 4096
8
Network:
  • Bridge: vmbr0, VLAN Tag: 45, Model: VirtIO (paravirtualized), Firewall: ☐
9
Confirm: Xem lại → Finish → Start VM → Console để bắt đầu cài Ubuntu.
Proxmox Create VM → tab Confirm: VM 239 harbor trên node2, 4 core, 4096 MiB, đĩa vm-ceph 100 GiB, VLAN tag 45 (VLAN_MGMT).
Proxmox Create VM → tab Confirm: VM 239 harbor trên node2, 4 core, 4096 MiB, đĩa vm-ceph 100 GiB, VLAN tag 45 (VLAN_MGMT).

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 (noble): dùng ISO 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.
Lưu ý phân vùng: Harbor lưu images tại /data, nên tách partition riêng 55 GB để dễ quản lý dung lượng sau này.
Ubuntu Server 24.04 installer → Storage configuration: đĩa 100 GB chia 40 GB /, 55 GB /data (ext4) và 5 GB swap.
Ubuntu Server 24.04 installer → Storage configuration: đĩa 100 GB chia 40 GB /, 55 GB /data (ext4) và 5 GB swap.
Dung lượng đĩa trong lab: dựng bằng 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
Dòng 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.
03

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
04

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

Vì sao nâng từ 2.11.0 lên 2.15.4: theo 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 2.15 còn các khóa mới trong 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
Terminal /opt/harbor: docker compose ps sau ./install.sh --with-trivy: 10 container (harbor-core, harbor-db, harbor-jobservice, harbor-log, harbor-portal, redis, registry, registryctl, trivy-adapter, nginx) healthy, nginx map 80->8080 và 443->8443; cột SERVICE là core, postgresql, proxy...
Terminal /opt/harbor: docker compose ps sau ./install.sh --with-trivy: 10 container (harbor-core, harbor-db, harbor-jobservice, harbor-log, harbor-portal, redis, registry, registryctl, trivy-adapter, nginx) healthy, nginx map 80->8080 và 443->8443; cột SERVICE là core, postgresql, proxy...
05

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.

Trình duyệt https://harbor.hoatranlabs.local: trang đăng nhập Harbor với khóa HTTPS hợp lệ (cert step-CA), trước khi đổi mật khẩu admin.
Trình duyệt https://harbor.hoatranlabs.local: trang đăng nhập Harbor với khóa HTTPS hợp lệ (cert step-CA), trước khi đổi mật khẩu admin.

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"
    }
  }'
Harbor UI → Projects: hai project infrastructure và apps ở Access Level Private, vừa tạo bằng API.
Harbor UI → Projects: hai project infrastructure và apps ở Access Level Private, vừa tạo bằng API.

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"}
        ]
      }
    ]
  }'
Lưu robot$gitea-ci token vào Gitea Secrets: Settings → Secrets → HARBOR_PASS
Harbor → Administration → Robot Accounts: robot$gitea-ci (system level) trạng thái Enabled, hết hạn sau 365 ngày.
Harbor → Administration → Robot Accounts: robot$gitea-ci (system level) trạng thái Enabled, hết hạn sau 365 ngày.
Bản 2.15.3 sửa lỗi bảo mật liên quan phạm vi robot "cover all projects" (GHSA-xq2m-cj8w-56v5) và quyền 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.
06

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/

1
Applications → Providers → Create → OAuth2/OpenID Provider
2
Điền:
  • 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
3
Applications → Create:
  • 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/"
Authentik Admin → Applications → Providers → harbor-oidc: Client ID, Client Secret (che), Redirect URI https://harbor.hoatranlabs.local/c/oidc/callback và Issuer .../application/o/harbor/ cần ghi lại để cấu hình Harbor.
Authentik Admin → Applications → Providers → harbor-oidc: Client ID, Client Secret (che), Redirect URI https://harbor.hoatranlabs.local/c/oidc/callback và Issuer .../application/o/harbor/ cần ghi lại để cấu hình 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
Harbor → Administration → Configuration → Authentication: Auth Mode OIDC, provider Authentik, Group Claim Name groups, Verify Certificate OFF, Automatic onboarding ON.
Harbor → Administration → Configuration → Authentication: Auth Mode OIDC, provider Authentik, Group Claim Name groups, Verify Certificate OFF, Automatic onboarding ON.

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).

Trang đăng nhập Harbor có nút đăng nhập bằng OIDC (LOGIN WITH Authentik, tên theo ô OIDC Provider Name); sau khi xác thực qua Authentik, tên user hiện ở góc trên phải.
Trang đăng nhập Harbor có nút đăng nhập bằng OIDC (LOGIN WITH Authentik, tên theo ô OIDC Provider Name); sau khi xác thực qua Authentik, tên user hiện ở góc trên phải.
07

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
Terminal client: docker login harbor.hoatranlabs.local (user robot$gitea-ci) báo Login Succeeded, docker pull harbor.hoatranlabs.local/infrastructure/ubuntu:24.04 chạy được (image đã có sẵn trong project).
Terminal client: docker login harbor.hoatranlabs.local (user robot$gitea-ci) báo Login Succeeded, docker pull harbor.hoatranlabs.local/infrastructure/ubuntu:24.04 chạy được (image đã có sẵn trong project).
08

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_dispatch cần body có ref, còn .../repos/<org>/<repo>/topics là 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ặc attachments). Payload Default của Harbor không có, còn loại SLACK của Harbor chỉ gửi Block Kit blocks khô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).

  1. 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
Container 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.
  1. 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.

Từ Harbor 2.15.3, webhook tới địa chỉ private/loopback bị chặn mặc định (SSRF, GHSA-2phj-cp9f-qq6w); 2.15.4 đặt lại mặc định cho phép. Nếu webhook báo lỗi gửi tới 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).
  1. 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.

09

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
10

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 -
11

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:

  1. 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.
  2. 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.
  3. Project Quotas (chặn một project ăn hết /data): Administration → Project Quotas → chọn project → Edit, ví dụ apps 20 GiB và infrastructure 15 GiB. Quota tính riêng từng project nên blob dùng chung bị tính lặp.
12

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, /data partition riêng 55 GB
  • Docker CE cài thành công từ repo noble (docker compose version chạy được)
  • step-CA cert cấp cho harbor.hoatranlabs.local, systemd timer gia hạn tự động
  • harbor.yml cấu hình với hostname, TLS, data_volume, Trivy
  • ./install.sh --with-trivy chạy thành công, 10 containers healthy
  • Truy cập https://harbor.hoatranlabs.local thành công, đổi admin password
  • Project infrastructure và apps tạo thành công, auto-scan ON
  • Robot account gitea-ci tạ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.local từ client thành công
  • Trivy scan hoạt động khi push image
  • Relay harbor-mm-relay chạy, webhook mattermost-deployments gửi thông báo push/scan vào #deployments (mục 8.3)
  • DNS record harbor.hoatranlabs.local → 10.11.45.39 thêm vào Pi-hole
  • Firewall rules VLAN nội bộ → port 443 allowed
  • Backup script /opt/harbor/backup-harbor.sh và 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):

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

Zalo