System & Network step-CA PKI
Bài 13 · Giai đoạn 2 — Hạ tầng nền tảng

Triển khai step-CA + PKI nội bộ

Hạ tầng khoá công khai nội bộ — cấp TLS certificate tự động.

VM242 Ubuntu 24.04 Giai đoạn: Hạ tầng nền tảng

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

Vị trí trong chuỗi bài: Bài 13 thuộc Giai đoạn 2 — Hạ tầng nền tảng, nối tiếp Bài 12. Pi-hole DNS và đứng trước Bài 14. Authentik SSO. Cần có sẵn / liên quan: 04. Triển khai PBS + PDM · 12. Pi-hole DNS · 15. Prometheus + Grafana.
Mức độ cần thiết: 🔴 Bắt buộc — Cần triển khai đầu tiên trước mọi service

Không có PKI nội bộ, có hai lựa chọn tệ: (1) dùng HTTP thuần — dữ liệu không mã hóa; (2) dùng self-signed cert — browser liên tục cảnh báo "không an toàn", user bỏ qua cảnh báo tạo thói quen nguy hiểm. step-CA là Root CA nội bộ tin cậy, cấp cert tự động với auto-renewal, không cần domain public.

MụcNội dung
Ứng dụng trong DNTLS cho tất cả service intranet, zero-trust internal networking, mTLS giữa microservices
Tác dụng chínhCấp cert cho Authentik/Gitea/Harbor/Vaultwarden/Mailu/Headscale...; auto-renew qua systemd timer
Nếu không triển khaiHTTP không mã hóa hoặc self-signed cert liên tục gây cảnh báo browser, không thể dùng mTLS
Các service phụ thuộc vào đâyMọi service HTTPS nội bộ trong lab (Authentik, Gitea, Harbor, Vaultwarden, Mailu, Headscale...) đều cần cert từ step-CA để enable HTTPS; giao diện web các node Proxmox VE / PBS xin cert qua ACME provisioner acme (bài 09)

Phiên bản: 1.2 | Ngày cập nhật: 2026-10-15
Cluster: HOATRANHUB (PVE 9.2.20) | Tác giả: HoatranLabs

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
step-ca (step-CA PKI) · VM24210.11.25.4225 (SEC) · node1Máy chủ của bài — Root CA nội bộ chạy bằng Docker Compose (smallstep/step-ca:0.30.2, dữ liệu /etc/step-ca, Ubuntu 24.04); API và ACME cổng 9000, node_exporter cổng 9100.
node1 (Proxmox VE)10.11.45.21045 (MGMT) · cluster HOATRANHUBNode Proxmox chứa VM242 (VLAN tag 25, storage vm-ceph, backup lên pbs-primary); node1–node4 cũng xin cert web qua ACME provisioner acme (bài 09).
FortiGate (firewall)10.100.100.1Quản trị 10.100.100.0/24 · thiết bị mạngGateway VLAN_SEC của VM242, cần Running trước khi triển khai; cổng 9000 do Docker publish nên ufw không lọc được (lọc nguồn ở FortiGate), ufw trên VM242 chỉ kiểm soát 9100, 22.
pihole (Pi-hole DNS) · VM24710.11.45.5345 (MGMT) · node3DNS khi cài OS cho VM242, DNS cho container step-ca (dns: 10.11.45.53) và nơi thêm A record step-ca.hoatranlabs.local, pki.hoatranlabs.local (bài 12).
authentik (Authentik SSO) · VM23410.11.25.4025 (SEC) · node1Nhận cert cấp thủ công bằng step ca certificate (/opt/authentik/certs), tự gia hạn bằng systemd timer 2 lần mỗi ngày (bài 14).
harbor (Harbor Registry) · VM23910.11.45.3945 (MGMT) · node2Nhận cert qua ACME provisioner, lưu ở /etc/ssl/harbor, SAN gồm tên miền và IP của Harbor (bài 21).
gitea (Gitea + Actions) · VM24010.11.45.4045 (MGMT) · node2Nhận cert qua ACME provisioner, lưu ở /opt/gitea/ssl, gia hạn bằng step ca renew + systemd timer (bài 22).
mailu (Mailu Mail Server) · VM24610.11.35.4635 (DMZ) · node2Nằm trong bảng inventory cert: mail.hoatranlabs.local, cert tại /opt/mailu/certs, gia hạn bằng systemd timer, hạn 90 ngày (bài 16).
vaultwarden (Vaultwarden) · VM24310.11.25.4325 (SEC) · node1Nằm trong bảng inventory cert: cert tại /etc/ssl/vaultwarden, gia hạn bằng systemd timer, hạn 90 ngày (bài 19).
headscale (Headscale VPN) · VM23210.11.35.1035 (DMZ) · node2Nằm trong bảng inventory cert: cert tại /etc/ssl/headscale, gia hạn bằng systemd timer, hạn 90 ngày (bài 20).
prometheus (Prometheus + Alertmanager) · VM23510.11.45.3545 (MGMT) · node2Scrape node_exporter cổng 9100 của VM242; ufw trên VM242 chỉ cho nguồn này vào cổng 9100 (bài 15).
pbs01 (PBS Primary) · VM10110.11.45.1745 (MGMT) · node4Lưu backup VM242: pbs-primary daily 01:00 Snapshot, và file-level /etc/step-ca, /opt/step-ca (namespace vm-step-ca); có thể xin cert ACME (bài 04, bài 09).

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.

Phụ thuộc (Dependencies)

Thành phầnVMIDIPTrạng thái cần có
PVE node1—10.11.45.210Running
FortiGate (gateway VLAN_SEC)—10.11.25.1Running
Pi-hole DNSVM24710.11.45.53Running
Prometheus (scrape)VM23510.11.45.35Running
PBS Backup (pbs01)VM10110.11.45.17Running
Ceph storage pool vm-ceph——Healthy

Lưu ý quan trọng: step-CA là PKI core, nên triển khai trước hoặc song song với Authentik (VM234). Sau khi có Root CA, tất cả service HTTPS (Authentik, Gitea, Harbor, Vaultwarden...) nên dùng cert từ step-CA thay vì self-signed.

Tổng Quan Kiến Trúc PKI

┌────────────────────────────────────┐
                │  VM242: step-ca (Docker container)  │
                │  10.11.25.42 | VLAN_SEC tag=25      │
                │  step-ca API  :9000                 │
                │  ACME endpoint:9000/acme/           │
                │  node_exporter:9100 (host)          │
                └──────────────┬─────────────────────┘
                               │ issues TLS certs
        ┌──────────────────────┼──────────────────────┐
        │                      │                       │
┌───────▼────────┐   ┌─────────▼───────┐   ┌─────────▼───────┐
│ Manual issuance│   │ ACME auto-renew │   │ step CLI enroll │
│ step ca cert   │   │ certbot/acme.sh │   │ on each VM      │
│ (one-time)     │   │ (systemd timer) │   │                 │
└────────────────┘   └─────────────────┘   └─────────────────┘

Phương án triển khai (quy tắc của series: có image chính thức thì ưu tiên Docker, rồi LXC, cuối cùng mới cài trực tiếp lên VM):

Phương ánTrạng thái trong bàiLý do chọn / không chọnCách chuyển đổi
Docker Compose trên VM242 (image smallstep/step-ca)Khuyến nghị — Bước 2–7Smallstep phát hành image chính thức, tag theo từng phiên bản nên ghim được 0.30.2; dữ liệu nằm ở bind mount /etc/step-ca nên đường dẫn /etc/step-ca/certs/root_ca.crt mà các bài khác tham chiếu và bản backup PBS in-VM (bài 04 mục 5.7) không đổi; nâng cấp bằng cách đổi tag rồi docker compose up -d; VMID, IP, VLAN, node giữ nguyênTừ .deb sang Docker (và ngược lại): mục "Phụ Lục" cuối bài
LXC không đặc quyền (template Ubuntu 24.04)Không dùngLXC chỉ thay VM cho dịch vụ nhẹ không có Docker phù hợp; step-ca đã có image chính thức nên chọn Docker. Docker không chạy trong LXC (Proxmox không khuyến nghị), nên LXC chỉ hợp với cách .deb + systemdTạo LXC rồi làm theo mục "Phụ Lục"; giữ IP 10.11.25.42 và chuyển /etc/step-ca sang
VM cài trực tiếp: gói .deb + systemdPhương án thay thế (mục "Phụ Lục")PKI không phụ thuộc Docker daemon; một file binary tĩnh, ít thành phần hơnDừng container, đổi chủ sở hữu và đường dẫn trong ca.json, bật unit systemd (mục "Phụ Lục")

Cân nhắc khi chạy PKI trong container:

  • PKI phụ thuộc Docker daemon: docker.service được bật khi boot, container có restart: unless-stopped và VM242 có startup order=1 (Bước 1), nên step-CA lên trước Authentik và các service dùng cert. VM242 chỉ chạy duy nhất CA này.
  • Khóa Root/Intermediate (/etc/step-ca/secrets/) nằm trong bind mount do uid 1000 (user step trong image) sở hữu, thư mục quyền 700 và khóa vẫn mã hóa bằng mật khẩu. Mật khẩu để trong file quyền 600 nạp bằng Docker secret, không ghi vào compose hay biến môi trường (docker inspect hiển thị biến môi trường của container).
  • Quyền dùng Docker daemon tương đương root trên VM242: chỉ sysadmin (qua sudo) quản trị VM này; không thêm user khác vào nhóm docker.

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 (ISO ubuntu-24.04.5-live-server-amd64.iso)Hỗ trợ chuẩn tới 04/2029; systemd 255 (chỉ cần cho phương án .deb + systemd ở mục "Phụ Lục")
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, cùng bản với bài 22; nếu dựng VM242 từ template 9001 (bài 07) thì Docker đã có sẵn
Docker Compose plugin / Buildx5.6.0 / 0.38.0Lệnh docker compose
step-ca (image smallstep/step-ca:0.30.2)0.30.2Tag 0.30.2 có trên Docker Hub (cập nhật 2026-03-23, index digest sha256:a2b17872…bc8270, trùng tag latest); ghim tag, không dùng latest. Nâng từ 0.27.4 vì lỗ hổng CVE-2025-44005 (xem Bước 3); binary trong image: /usr/local/bin/step-ca
step CLI (step-cli_0.31.0-1_amd64.deb)0.31.0Giá trị dùng chung của cả series; cài trên VM242 (host) và mọi máy client từ GitHub Releases; gói đặt binary /usr/bin/step-cli và postinst tạo lệnh step bằng update-alternatives (đã kiểm nội dung gói ngày 2026-10-15). CLI nằm trong image là bản do Smallstep đóng gói lúc build, xem bằng docker exec step-ca step version
node_exporter1.12.1Giá trị dùng chung của cả series; chạy trên host bằng systemd (agent không đóng container), cổng 9100
step-ca (step-ca_0.30.2-1_amd64.deb)0.30.2Chỉ dùng cho phương án thay thế .deb + systemd (mục "Phụ Lục"); binary /usr/bin/step-ca
01

Tạo VM242

Chạy trên node1:

Cách 1: Web UI Proxmox (GUI)

1
Đăng nhập Proxmox Web UI → chọn Node: node1 → nhấn Create VM (góc trên phải)
2
General:
  • VM ID: 242
  • Name: step-ca
  • 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 (tải từ https://releases.ubuntu.com/24.04/)
  • 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: 20 GiB, Cache: Write back, Discard: ☑
6
CPU:
  • Sockets: 1, Cores: 2, Type: x86-64-v2-AES
7
Memory:
  • Memory (MiB): 2048
8
Network:
  • Bridge: vmbr0, VLAN Tag: 25, 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 242 step-ca, 2 core, 2048 MiB, scsi0 20 GiB vm-ceph, net0 VirtIO vmbr0 tag 25, trước khi bấm Finish.
Proxmox Create VM → tab Confirm: VM 242 step-ca, 2 core, 2048 MiB, scsi0 20 GiB vm-ceph, net0 VirtIO vmbr0 tag 25, trước khi bấm Finish.

Cách 2: CLI (qm create)

qm create 242 \
  --name step-ca \
  --memory 2048 \
  --cores 2 \
  --net0 virtio,bridge=vmbr0,tag=25 \
  --scsi0 vm-ceph:20 \
  --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=1,up=20

startup order=1: step-CA nên khởi động trước Authentik và các service dùng cert.

Cài đặt OS Ubuntu Server 24.04 LTS (kiểm tra tên NIC bằng ip -br link: VM q35 thường là enp6s18 hoặc ens18; netplan do bộ cài/cloud-init ghi ở /etc/netplan/50-cloud-init.yaml):

Hostname    : step-ca
Username    : sysadmin
Password    : <mật khẩu mạnh>
IP          : 10.11.25.42/24
Gateway     : 10.11.25.1
DNS         : 10.11.45.53

Eject ISO sau khi cài:

qm set 242 --ide2 none
02

Chuẩn Bị Hệ Thống

Chạy bằng quyền root (sudo -i). Bước này cài hệ thống, Docker Engine (repo chính thức, suite noble, dạng deb822 docker.sources + Signed-By, không dùng apt-key) và tạo thư mục dữ liệu cho container.

# Ubuntu 24.04: needrestart có thể hiện hộp thoại hỏi khi apt cập nhật thư viện, đặt chế độ tự động để script không bị dừng
export NEEDRESTART_MODE=a
apt update && apt upgrade -y
apt install -y curl wget ca-certificates openssl qemu-guest-agent
systemctl enable --now qemu-guest-agent

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

# 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
systemctl is-enabled docker        # enabled: Docker tự chạy khi boot, kéo theo container có restart policy

# Thư mục dữ liệu CA (bind mount vào /home/step của container) và thư mục compose + secret
# uid:gid 1000:1000 = user `step` trong image smallstep/step-ca (STEPUID=STEPGID=1000 trong Dockerfile của step-cli);
# trên host uid 1000 thường trùng user sysadmin của bộ cài, không sao: container chỉ cần quyền ghi theo số uid
install -d -o 1000 -g 1000 -m 755 /etc/step-ca
install -d -m 755 /opt/step-ca
install -d -o 1000 -g 1000 -m 700 /opt/step-ca/secrets
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. Nếu VM242 được clone từ template 9001 (Ubuntu 24.04 + Docker, bài 07) thì Docker đã có sẵn: chỉ cần chạy các lệnh kiểm tra phiên bản và ba lệnh install -d cuối.
03

Cài step CLI và Tải Image step-ca

# 1) step CLI trên host (gói .deb chính thức, Ubuntu 24.04 amd64, GitHub Releases): dùng cho `step certificate fingerprint`,
#    `step ca root`, `step ca certificate`... ngay trên VM242 và là lệnh mà các bài khác gọi khi hướng dẫn "chạy trên VM242".
#    Bản mới xem tại https://github.com/smallstep/cli/releases (0.31.0 = giá trị dùng chung của series)
STEP_VERSION="0.31.0"
cd /tmp
wget "https://github.com/smallstep/cli/releases/download/v${STEP_VERSION}/step-cli_${STEP_VERSION}-1_amd64.deb"
# Gói đặt binary /usr/bin/step-cli và script postinst tạo lệnh `step` (update-alternatives: /usr/bin/step -> /usr/bin/step-cli)
apt install -y "./step-cli_${STEP_VERSION}-1_amd64.deb"
step version

# 2) Image step-ca: GHIM TAG phiên bản, không dùng :latest (nâng cấp có chủ đích ở Bước 7).
#    Tag 0.30.2 = bản stable mới nhất trên Docker Hub (https://hub.docker.com/r/smallstep/step-ca/tags), xác minh 2026-10-15
STEP_CA_IMAGE="smallstep/step-ca:0.30.2"
docker pull "${STEP_CA_IMAGE}"
docker run --rm --entrypoint step-ca "${STEP_CA_IMAGE}" version      # Smallstep CA/0.30.2 ...
docker image inspect "${STEP_CA_IMAGE}" --format '{{index .RepoDigests 0}}'
# Digest index của tag 0.30.2 (Docker Hub, 2026-10-15): sha256:a2b17872915c193259b75a5474c398326f41bd199f0842093e52cf4182bc8270
Terminal VM242: `step version` báo Smallstep CLI 0.31.0; `docker run --rm --entrypoint step-ca smallstep/step-ca:0.30.2 version` báo Smallstep CA 0.30.2 (linux/amd64); `docker image inspect` in digest của image.
Terminal VM242: `step version` báo Smallstep CLI 0.31.0; `docker run --rm --entrypoint step-ca smallstep/step-ca:0.30.2 version` báo Smallstep CA 0.30.2 (linux/amd64); `docker image inspect` in digest của image.
Vì sao không giữ step-ca 0.27.4: bản này nằm trong dải bị lỗ hổng CVE-2025-44005 (GHSA-h8cp-697h-8c8p, mức Critical, CVSS 10.0): provisioner ACME và SCEP bỏ qua bước kiểm tra xác thực, vá từ v0.29.0. Lab này dùng ACME provisioner (Bước 6) nên phải dùng step-ca ≥ 0.29.0; bài chọn bản stable mới nhất 0.30.2. Nguồn: https://github.com/smallstep/certificates/security/advisories/GHSA-h8cp-697h-8c8p. Cặp step CLI 0.31.0 ở host + step-ca 0.30.2 trong image (CLI trong image do step ca init / step ca provisioner add ghi ca.json): cần kiểm lại trên máy thật.
04

Tạo Password File Cho Root CA

# Tạo mật khẩu bảo vệ private key của Root CA / Intermediate CA (cũng là mật khẩu của provisioner [email protected])
# LƯU MẬT KHẨU NÀY VÀO VAULT HOẶC NƠI AN TOÀN
( umask 077; openssl rand -base64 32 | tr -d '\n' > /opt/step-ca/secrets/ca_password )   # subshell: umask 077 không lan sang các lệnh sau trong phiên root
chown 1000:1000 /opt/step-ca/secrets/ca_password      # uid của user `step` trong container (Bước 2)
chmod 600 /opt/step-ca/secrets/ca_password

echo "Root CA password:"
cat /opt/step-ca/secrets/ca_password; echo

File này là Docker secret: compose (Bước 5) mount nó vào container tại /run/secrets/step_ca_password và entrypoint của image đọc qua DOCKER_STEPCA_INIT_PASSWORD_FILE, nên mật khẩu không nằm trong docker-compose.yml hay biến môi trường. Lần khởi tạo đầu tiên, entrypoint chép mật khẩu sang /home/step/secrets/password (= /etc/step-ca/secrets/password trên host) để step-ca đọc mỗi lần khởi động. Vì bản sao đó nằm trong thư mục dữ liệu nên bản backup /etc/step-ca (Bước 13) cũng chứa mật khẩu: kho backup phải được mã hóa và hạn chế quyền truy cập.

05

Khởi Tạo Root CA

Tạo file compose. Lần chạy đầu, entrypoint của image thấy chưa có config/ca.json nên tự chạy step ca init theo các biến DOCKER_STEPCA_INIT_* (root + intermediate, provisioner JWK, provisioner ACME); những lần sau các biến này bị bỏ qua.

cat > /opt/step-ca/docker-compose.yml << 'EOF'
name: step-ca

services:
  step-ca:
    image: smallstep/step-ca:0.30.2        # ghim tag; nâng cấp ở Bước 7
    container_name: step-ca
    restart: unless-stopped
    environment:
      # Chỉ được đọc MỘT lần, khi /home/step/config/ca.json chưa tồn tại
      DOCKER_STEPCA_INIT_NAME: "HoatranLabs Internal CA"
      DOCKER_STEPCA_INIT_DNS_NAMES: "step-ca.hoatranlabs.local,10.11.25.42"   # tên đầu tiên = ca-url trong defaults.json
      DOCKER_STEPCA_INIT_ADDRESS: ":9000"
      DOCKER_STEPCA_INIT_PROVISIONER_NAME: "[email protected]"
      DOCKER_STEPCA_INIT_DEPLOYMENT_TYPE: "standalone"
      DOCKER_STEPCA_INIT_ACME: "true"                      # tạo sẵn provisioner ACME tên "acme"
      DOCKER_STEPCA_INIT_REMOTE_MANAGEMENT: "false"        # giữ ca.json làm nguồn cấu hình (policy ở bài 09)
      DOCKER_STEPCA_INIT_PASSWORD_FILE: /run/secrets/step_ca_password
    secrets:
      - step_ca_password
    ports:
      - "9000:9000"                        # API + ACME của step-ca
    volumes:
      - /etc/step-ca:/home/step            # dữ liệu CA (certs, config, secrets, db) nằm trên host, owner uid 1000
    extra_hosts:
      - "step-ca.hoatranlabs.local:127.0.0.1"   # `step ca health` trong container gọi chính nó, không phụ thuộc DNS
    dns:
      - 10.11.45.53                        # Pi-hole (bài 12): container phân giải nodeN.hoatranlabs.local khi xác thực http-01 (bài 09)
    healthcheck:
      test: ["CMD-SHELL", "step ca health 2>/dev/null | grep -q '^ok'"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"
    security_opt:
      - no-new-privileges:true
    networks:
      - step-ca-net

networks:
  step-ca-net:
    name: step-ca-net
    driver: bridge

secrets:
  step_ca_password:
    file: /opt/step-ca/secrets/ca_password
EOF
chmod 644 /opt/step-ca/docker-compose.yml     # file không chứa bí mật

cd /opt/step-ca
docker compose config -q && echo "compose hợp lệ"
docker compose up -d
docker compose logs -f step-ca        # Ctrl+C để thoát; chờ khoảng "Your PKI is ready to go" và "Serving HTTPS on :9000"

Giải thích các lựa chọn chính:

  • DOCKER_STEPCA_INIT_*: giữ đúng chính sách trước đây (tên CA HoatranLabs Internal CA, SAN step-ca.hoatranlabs.local + 10.11.25.42, cổng :9000, provisioner JWK [email protected], provisioner ACME acme, kiểu triển khai standalone). Không bật DOCKER_STEPCA_INIT_REMOTE_MANAGEMENT để provisioner và policy vẫn nằm trong ca.json như Bước 6 và bài 09; README của image trên Docker Hub ghi bật là "recommended", nếu bật thì phải quyết định ngay lúc khởi tạo và cách quản trị provisioner thay đổi (cần kiểm lại trên máy thật).
  • /etc/step-ca:/home/step: bind mount, thư mục host do uid 1000 sở hữu (Bước 2). Đường dẫn trên host giữ nguyên /etc/step-ca/certs/root_ca.crt cho mọi bài khác, PBS backup và distribute-root-ca.sh; còn trong container là /home/step/... (các đường dẫn trong ca.json cũng là /home/step/...).
  • extra_hosts + dns: container không đọc /etc/hosts của host. extra_hosts giúp healthcheck gọi về chính nó; dns trỏ tới Pi-hole để step-ca phân giải tên node khi xác thực http-01. Chưa có Pi-hole thì bỏ dòng dns (container dùng DNS của host) và thêm các tên node vào extra_hosts.
  • logging: json-file với max-size/max-file để log không phình ra đĩa 20 GiB; Alloy (bài 33, khối loki.source.docker với nhãn job="docker-containers") đọc log container qua Docker API nên thu được log của container step-ca nếu bạn cài Alloy trên VM242.
  • no-new-privileges: tiến trình trong container không tự nâng quyền. step-ca nghe cổng 9000 (> 1024) nên không cần capability nào (Dockerfile của image có đặt sẵn file capability cap_net_bind_service cho binary step-ca, không dùng tới ở cổng này); nếu container báo operation not permitted khi khởi động, bỏ hai dòng security_opt (cần kiểm lại trên máy thật).
  • Mạng bridge riêng step-ca-net; cổng 9000 được publish trên mọi địa chỉ của VM242. Docker bỏ qua luật ufw khi publish cổng nên phải lọc nguồn ở FortiGate, xem ghi chú ở Bước 12.

Container vừa khởi tạo CA nên log của nó có dòng Your CA administrative password is: ... (chính là mật khẩu ở Bước 4). Tạo lại container để xóa log đó:

cd /opt/step-ca
docker compose up -d --force-recreate      # container mới: log mới, dữ liệu vẫn nằm ở /etc/step-ca
docker compose logs --tail=20 step-ca      # không còn dòng mật khẩu
docker compose ps                          # sau khoảng 30-60 giây: STATUS "Up ... (healthy)"

Sau khi init, chỉnh quyền cho phần công khai: certs/ chỉ chứa chứng chỉ nên cho user thường trên host đọc (các bài khác chạy scp/cat /etc/step-ca/certs/root_ca.crt từ đây), còn secrets/, db/, config/ giữ nguyên quyền 700 của uid 1000:

chmod 755 /etc/step-ca/certs
chmod 644 /etc/step-ca/certs/*.crt
chmod 600 /etc/step-ca/secrets/password      # bản sao mật khẩu do entrypoint tạo

Ghi lại Root CA Fingerprint (dùng để trust CA trên các VM):

# Xem fingerprint Root CA (step CLI cài trên host ở Bước 3)
step certificate fingerprint /etc/step-ca/certs/root_ca.crt
# Ví dụ output: a1b2c3d4e5f6...  (64 ký tự hex)
# LƯU GIÁ TRỊ NÀY LẠI
# Cùng giá trị, đọc từ trong container: docker exec step-ca step certificate fingerprint /home/step/certs/root_ca.crt
Terminal VM242: `step certificate fingerprint /etc/step-ca/certs/root_ca.crt` in Root CA fingerprint 64 ký tự hex sau khi container step-ca khởi tạo CA xong (thư mục bind mount /etc/step-ca), cần lưu lại.
Terminal VM242: `step certificate fingerprint /etc/step-ca/certs/root_ca.crt` in Root CA fingerprint 64 ký tự hex sau khi container step-ca khởi tạo CA xong (thư mục bind mount /etc/step-ca), cần lưu lại.

Xem cấu trúc thư mục sau khi init:

ls -ln /etc/step-ca/        # cột chủ sở hữu hiện 1000 1000 (uid:gid của user `step` trong container)
# certs/      - root_ca.crt, intermediate_ca.crt
# config/     - ca.json (cấu hình CA), defaults.json (ca-url, root, fingerprint cho step CLI trong container)
# db/         - badger database
# secrets/    - root_ca_key, intermediate_ca_key (bảo vệ bằng password), password (bản sao mật khẩu cho step-ca)
# templates/  - certificate templates
06

Cấu Hình Thêm Provisioner ACME

ACME provisioner cho phép service tự động xin và renew cert (tương thích Let's Encrypt API). Provisioner đặt tên acme nên Directory URL là https://step-ca.hoatranlabs.local:9000/acme/acme/directory; Harbor, Gitea (Bước 10) và các node Proxmox VE / PBS (mục "ACME Provisioner Cho Proxmox VE" bên dưới, bài 09) cùng dùng provisioner này. Provisioner acme đã được tạo ở Bước 5 nhờ DOCKER_STEPCA_INIT_ACME: "true", nên bước này chỉ kiểm tra (và thêm bằng tay nếu thiếu). Các lệnh quản trị chạy bằng step bên trong container qua docker exec (STEPPATH của container là /home/step, nên --ca-config trỏ /home/step/config/ca.json; thư mục /etc/step-ca ở host là cùng dữ liệu đó):

# Xem danh sách provisioner NGAY TỪ ca.json (kiểm tra offline; chạy bằng root vì thư mục config/ chỉ uid 1000 và root đọc được)
python3 -c "import json; [print(p['type'], p['name']) for p in json.load(open('/etc/step-ca/config/ca.json'))['authority']['provisioners']]"
# Kết quả mong đợi (2 dòng):
#   JWK [email protected]
#   ACME acme

# Cách khác: hỏi CA qua API bằng step CLI trong container (ca-url và root lấy từ /home/step/config/defaults.json)
docker exec step-ca step ca provisioner list

# CHỈ chạy khi thiếu provisioner "acme" (vd. CA từng khởi tạo mà không bật DOCKER_STEPCA_INIT_ACME): thêm vào ca.json rồi nạp lại cấu hình
docker exec step-ca step ca provisioner add acme --type ACME --ca-config /home/step/config/ca.json
docker kill -s HUP step-ca

Chỉnh sửa ca.json để cấu hình default cert lifetime:

cat /etc/step-ca/config/ca.json
Terminal VM242: `cat /etc/step-ca/config/ca.json` — mảng "provisioners" gồm provisioner JWK admin@hoatranlabs.local và provisioner ACME tên acme (cả hai do container tạo lúc khởi tạo nhờ DOCKER_STEPCA_INIT_ACME).
Terminal VM242: `cat /etc/step-ca/config/ca.json` — mảng "provisioners" gồm provisioner JWK [email protected] và provisioner ACME tên acme (cả hai do container tạo lúc khởi tạo nhờ DOCKER_STEPCA_INIT_ACME).

Tìm và cập nhật phần "claims" trong ca.json:

"claims": {
    "minTLSCertDuration": "5m",
    "maxTLSCertDuration": "2160h",
    "defaultTLSCertDuration": "2160h",
    "disableRenewalNotification": false,
    "minHostSSHCertDuration": "5m",
    "maxHostSSHCertDuration": "1680h",
    "minUserSSHCertDuration": "5m",
    "maxUserSSHCertDuration": "24h"
}
# Sửa file ca.json trên host (chạy bằng root; dùng python3 để parse JSON an toàn)
python3 << 'EOF'
import json

with open('/etc/step-ca/config/ca.json', 'r') as f:
    config = json.load(f)

config['authority']['claims'] = {
    "minTLSCertDuration": "5m",
    "maxTLSCertDuration": "2160h",
    "defaultTLSCertDuration": "2160h",
    "disableRenewalNotification": False
}

with open('/etc/step-ca/config/ca.json', 'w') as f:
    json.dump(config, f, indent=4)

print("ca.json updated successfully")
EOF

chown 1000:1000 /etc/step-ca/config/ca.json      # giữ chủ sở hữu là uid của user `step` trong container

# Nạp lại cấu hình: step-ca nhận SIGHUP là đọc lại ca.json (hoặc restart: xem Bước 7)
docker kill -s HUP step-ca
07

Vận Hành Container (Kiểm Tra, Tự Khởi Động, Reload, Nâng Cấp)

Container đã chạy từ Bước 5. Kiểm tra trạng thái, healthcheck và chính sách khởi động lại:

cd /opt/step-ca
docker compose ps                      # step-ca: Up ... (healthy)
docker inspect step-ca --format 'health={{.State.Health.Status}} restart={{.HostConfig.RestartPolicy.Name}}'
# health=healthy restart=unless-stopped
docker compose logs --tail=30 step-ca

Kiểm tra CA đang chạy:

curl -sk https://step-ca.hoatranlabs.local:9000/health | python3 -m json.tool
# Kết quả mong đợi: {"status": "ok"}
Terminal VM242: `docker compose ps` báo container step-ca `Up ... (healthy)`, rồi `curl .../health` trả {"status": "ok"}.
Terminal VM242: `docker compose ps` báo container step-ca `Up ... (healthy)`, rồi `curl .../health` trả {"status": "ok"}.

Tự khởi động: docker.service được bật khi boot (Bước 2) và container có restart: unless-stopped, nên sau khi VM242 khởi động lại (hoặc Docker daemon khởi động lại) step-ca tự chạy lại; riêng container bạn đã chủ động docker compose stop thì giữ nguyên trạng thái dừng. Thử bằng reboot, rồi docker compose ps phải báo healthy sau khoảng một phút.

Reload cấu hình (sau khi sửa ca.json, thêm provisioner, đặt policy ở bài 09): step-ca đọc lại cấu hình khi nhận SIGHUP, hoặc restart container:

docker kill -s HUP step-ca                  # nạp lại ca.json, không ngắt container
docker compose -f /opt/step-ca/docker-compose.yml restart step-ca    # nếu cần restart hẳn
docker compose -f /opt/step-ca/docker-compose.yml logs --tail=20 step-ca

Chạy CLI quản trị: lệnh step ngoài container dùng cấu hình ~/.step của host, còn lệnh quản trị CA phải chạy trong container (STEPPATH /home/step). Tạo alias stepca để gõ ngắn (đăng nhập lại để có hiệu lực; trong script dùng docker exec step-ca step ..., không có -it):

cat > /etc/profile.d/step-ca.sh << 'EOF'
alias stepca='docker exec -it step-ca step'
EOF
# Ví dụ sau khi đăng nhập lại: stepca ca provisioner list ; stepca certificate fingerprint /home/step/certs/root_ca.crt

Nâng cấp image (đổi tag, không dùng latest). Tag mới xem tại https://hub.docker.com/r/smallstep/step-ca/tags và ghi chú phát hành tại https://github.com/smallstep/certificates/releases; backup trước (Bước 13):

cd /opt/step-ca
NEW_TAG="<tag mới, dạng 0.30.x>"
BK="/root/step-ca-data-$(date +%F).tgz"
docker compose stop step-ca
tar -C /etc -czpf "$BK" step-ca && chmod 600 "$BK"      # chứa khóa + mật khẩu: giữ chặt hoặc chép ra offline rồi xóa
sed -i "s#smallstep/step-ca:[0-9][0-9.]*#smallstep/step-ca:${NEW_TAG}#" docker-compose.yml
grep 'image:' docker-compose.yml
docker compose pull
docker compose up -d
docker exec step-ca step-ca version
curl -sk https://step-ca.hoatranlabs.local:9000/health

Nâng cấp không chạy lại step ca init vì ca.json đã có; dữ liệu CA ở /etc/step-ca giữ nguyên. Quay lại bản cũ: đặt lại tag cũ rồi docker compose up -d (nếu bản mới đã ghi db/ thì khôi phục từ file .tgz).

08

Cài node_exporter

# node_exporter 1.12.1: giá trị dùng chung của cả series (đã xác minh 2026-10-15)
NODE_EXPORTER_VERSION="1.12.1"
cd /tmp

wget -q "https://github.com/prometheus/node_exporter/releases/download/v${NODE_EXPORTER_VERSION}/node_exporter-${NODE_EXPORTER_VERSION}.linux-amd64.tar.gz"
tar xzf "node_exporter-${NODE_EXPORTER_VERSION}.linux-amd64.tar.gz"
cp "node_exporter-${NODE_EXPORTER_VERSION}.linux-amd64/node_exporter" /usr/local/bin/
chmod 755 /usr/local/bin/node_exporter

id node_exporter &>/dev/null || useradd -rs /bin/false node_exporter

cat > /etc/systemd/system/node_exporter.service << 'EOF'
[Unit]
Description=Prometheus Node Exporter
After=network-online.target

[Service]
User=node_exporter
Group=node_exporter
Type=simple
Restart=on-failure
ExecStart=/usr/local/bin/node_exporter --web.listen-address=:9100

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now node_exporter
09

Phân Phối Root CA Certificate Đến Tất Cả VM

Script cài Root CA cert lên từng VM Ubuntu để browser và OS tin tưởng:

#!/bin/bash
# distribute-root-ca.sh
# Chạy bằng root trên MỖI VM Ubuntu (và trên mỗi node Proxmox VE / PBS, bài 09) sau khi step-CA đã chạy
# Biến: CA_URL, CA_FINGERPRINT (lấy từ Bước 5)

CA_URL="https://step-ca.hoatranlabs.local:9000"
CA_FINGERPRINT="REPLACE_WITH_FINGERPRINT_FROM_STEP_5"
CERT_PATH="/usr/local/share/ca-certificates/hoatranlabs-root.crt"

echo "[1/3] Cài step CLI (gói .deb, chạy được trên Ubuntu 24.04, Debian và Proxmox VE)..."
STEP_VERSION="0.31.0"
cd /tmp
wget -q "https://github.com/smallstep/cli/releases/download/v${STEP_VERSION}/step-cli_${STEP_VERSION}-1_amd64.deb"
apt-get install -y "./step-cli_${STEP_VERSION}-1_amd64.deb"

echo "[2/3] Tải Root CA cert..."
step ca root "${CERT_PATH}" \
  --ca-url "${CA_URL}" \
  --fingerprint "${CA_FINGERPRINT}"

echo "[3/3] Trust Root CA..."
chmod 644 "${CERT_PATH}"
update-ca-certificates

echo "Done. Root CA trusted on $(hostname)"
Terminal một VM Ubuntu: distribute-root-ca.sh chạy qua các bước [1/3]–[3/3] và kết thúc bằng dòng "Done. Root CA trusted on <hostname>".
Terminal một VM Ubuntu: distribute-root-ca.sh chạy qua các bước [1/3]–[3/3] và kết thúc bằng dòng "Done. Root CA trusted on <hostname>".
10

Phát Hành TLS Certificate Cho Service

Cấp cert thủ công (one-time) cho Authentik:

# Chạy trên VM234 (Authentik) sau khi đã trust Root CA (thư mục /opt/authentik/certs/ tạo ở bài 14)
# Thư mục này được mount vào container worker tại /certs: Authentik tự import authentik.crt + authentik.key
# thành key pair `authentik`, rồi gán cho Brand ở bài 14 mục 7.3-7.4
# Khi đã có --san thì tên subject không tự thành SAN, nên khai báo cả tên lẫn IP (giống Harbor/Gitea bên dưới):
# truy cập https://10.11.25.40:9443 bằng IP không bị lệch tên
step ca certificate "authentik.hoatranlabs.local" \
  /opt/authentik/certs/authentik.crt \
  /opt/authentik/certs/authentik.key \
  --ca-url https://step-ca.hoatranlabs.local:9000 \
  --root /usr/local/share/ca-certificates/hoatranlabs-root.crt \
  --provisioner [email protected] \
  --san authentik.hoatranlabs.local \
  --san 10.11.25.40 \
  --not-after 2160h
Terminal VM234: `step ca certificate "authentik.hoatranlabs.local"` báo cert và key đã lưu tại /opt/authentik/certs/authentik.crt và authentik.key.
Terminal VM234: `step ca certificate "authentik.hoatranlabs.local"` báo cert và key đã lưu tại /opt/authentik/certs/authentik.crt và authentik.key.

Cấp cert cho Harbor (theo bài 21):

# Chạy trên VM239 (Harbor)
mkdir -p /etc/ssl/harbor
step ca certificate "harbor.hoatranlabs.local" \
  /etc/ssl/harbor/harbor.crt \
  /etc/ssl/harbor/harbor.key \
  --ca-url https://step-ca.hoatranlabs.local:9000 \
  --root /usr/local/share/ca-certificates/hoatranlabs-root.crt \
  --provisioner acme \
  --san harbor.hoatranlabs.local \
  --san 10.11.45.39

Cấp cert qua ACME provisioner cho Gitea (theo bài 22):

# Chạy trên VM240 (Gitea); gia hạn bằng step ca renew + systemd timer (xem bài 22)
mkdir -p /opt/gitea/ssl
step ca certificate "gitea.hoatranlabs.local" \
  /opt/gitea/ssl/cert.pem \
  /opt/gitea/ssl/key.pem \
  --ca-url https://step-ca.hoatranlabs.local:9000 \
  --root /usr/local/share/ca-certificates/hoatranlabs-root.crt \
  --provisioner acme \
  --san gitea.hoatranlabs.local \
  --san 10.11.45.40

chmod 640 /opt/gitea/ssl/key.pem
Terminal VM240 (Gitea): `step ca certificate` với `--provisioner acme` báo đã cấp chứng chỉ gitea.hoatranlabs.local, lưu tại /opt/gitea/ssl/cert.pem và key.pem.
Terminal VM240 (Gitea): `step ca certificate` với `--provisioner acme` báo đã cấp chứng chỉ gitea.hoatranlabs.local, lưu tại /opt/gitea/ssl/cert.pem và key.pem.

ACME Provisioner Cho Proxmox VE / PBS (bài 09)

Bài 09 dùng step-CA làm ACME CA để cấp chứng chỉ cho giao diện web (cổng 8006) của các node Proxmox VE và, tùy chọn, PBS/PDM. Phía step-CA chỉ cần provisioner acme (tạo lúc khởi tạo ở Bước 5, kiểm ở Bước 6, dùng chung với Harbor/Gitea) cùng vài điều kiện mạng và tin cậy bên dưới; lệnh phía Proxmox (pvenode acme ...) nằm ở bài 09. Nếu đi tuần tự, hoàn thành bài 13 trước khi làm bài 09.

Thêm và kiểm tra provisioner acme (chạy trên VM242):

# Lệnh quản trị giống Bước 6: chạy `step` trong container. Xem trước, chỉ chạy lệnh add nếu CHƯA thấy provisioner "acme"
# (Bước 5 đã bật sẵn bằng DOCKER_STEPCA_INIT_ACME)
docker exec step-ca step ca provisioner list
# Phải có một provisioner "type": "ACME", "name": "acme"

docker exec step-ca step ca provisioner add acme --type ACME --ca-config /home/step/config/ca.json
docker kill -s HUP step-ca        # ca.json sửa bằng CLI phải được nạp lại (SIGHUP) hoặc restart: docker compose -f /opt/step-ca/docker-compose.yml restart step-ca

# Kiểm tra từ máy khách bất kỳ đã có Root CA (không cần vào container): danh sách provisioner là thông tin công khai của CA
step ca provisioner list --ca-url https://step-ca.hoatranlabs.local:9000 --root /etc/step-ca/certs/root_ca.crt   # trên VM242; máy khác dùng --root /usr/local/share/ca-certificates/hoatranlabs-root.crt

curl -s --cacert /etc/step-ca/certs/root_ca.crt https://step-ca.hoatranlabs.local:9000/acme/acme/directory | python3 -m json.tool
# Kết quả mẫu: có các khóa newNonce, newAccount, newOrder, revokeCert, keyChange

Directory URL cho Proxmox: https://step-ca.hoatranlabs.local:9000/acme/acme/directory (tên provisioner acme nằm giữa /acme/ và /directory). Thời hạn chứng chỉ do claims quyết định (client ACME không tự chọn được): claims toàn cục ở Bước 6 (defaultTLSCertDuration = maxTLSCertDuration = 2160h, tức 90 ngày) áp dụng cho acme. Theo tài liệu Proxmox, dịch vụ pve-daily-update thử gia hạn khi chứng chỉ đã hết hạn hoặc còn dưới 30 ngày, nên 90 ngày là phù hợp. Muốn đặt thời hạn riêng cho provisioner này (CA không bật remote management nên phải sửa thẳng ca.json bằng --ca-config): docker exec step-ca step ca provisioner update acme --x509-default-dur 720h --x509-max-dur 720h --ca-config /home/step/config/ca.json rồi docker kill -s HUP step-ca (720h chỉ minh hoạ cú pháp; với Proxmox đừng đặt ≤ 720h, xem bài 09 mục 6.2; tên cờ --x509-*-dur và --ca-config đối chiếu với mã nguồn step CLI 0.31.0, command/ca/provisioner/update.go; chạy thật trên CA của lab: cần kiểm lại trên máy thật).

Điều kiện để node Proxmox đặt hàng thành công:

#Yêu cầuChi tiết
1Node → step-CA, TCP 9000VLAN 45 → VLAN 25: đã nằm trong quy tắc "Tất cả VM → 9000" và ufw allow from 10.11.0.0/16 (Bước 12)
2step-CA → node, TCP 80Với challenge http-01, VM242 (10.11.25.42) gọi ngược http://node1.hoatranlabs.local/.well-known/acme-challenge/...; plugin Standalone của Proxmox mở cổng 80 tạm thời trong lúc xác thực. Mở policy FortiGate VLAN 25 → VLAN 45 (10.11.45.210–213, thêm pbs01 10.11.45.17 nếu cấp cho PBS) cổng 80, và cho phép 10.11.25.42 → cổng 80 trong firewall của node (bài 05)
3DNS hai chiềuContainer step-ca (không chỉ VM242) phân giải được node1…node4.hoatranlabs.local và pbs01.hoatranlabs.local (bản ghi trong Pi-hole, bài 12; compose đã đặt dns: 10.11.45.53): kiểm bằng docker exec step-ca getent hosts node1.hoatranlabs.local; node phân giải được step-ca.hoatranlabs.local
4Node tin cậy Root CAChạy distribute-root-ca.sh (Bước 9) bằng root trên từng node; script dùng gói .deb nên chạy được trên Proxmox VE (Debian) và update-ca-certificates có sẵn. Việc pvenode chấp nhận CA nội bộ qua kho tin cậy hệ thống: cần kiểm lại trên máy thật
5Giờ hệ thống chính xácLệch giờ giữa node và VM242 làm chứng chỉ báo "chưa có hiệu lực"

Tóm tắt phía Proxmox (chi tiết, đa node và xử lý lỗi ở bài 09):

# Trên node1 (lặp lại cho node2–node4 với tên nodeN tương ứng)
pvenode acme account register default [email protected] --directory https://step-ca.hoatranlabs.local:9000/acme/acme/directory
pvenode config set --acme domains=node1.hoatranlabs.local
pvenode acme cert order
# Kết quả mẫu: "Placing ACME order ... Status is 'valid'! ... Setting pveproxy certificate and key ... Restarting pveproxy ... Task OK"
Shell node1 trên Proxmox: `pvenode acme cert order` đi qua "Placing ACME order", "Status is 'valid'!" và kết thúc "Task OK"; Datacenter → node1 → System → Certificates hiện chứng chỉ do HoatranLabs Internal CA cấp cho node1.hoatranlabs.local.
Shell node1 trên Proxmox: `pvenode acme cert order` đi qua "Placing ACME order", "Status is 'valid'!" và kết thúc "Task OK"; Datacenter → node1 → System → Certificates hiện chứng chỉ do HoatranLabs Internal CA cấp cho node1.hoatranlabs.local.
11

Cấu Hình Auto-Renew với step CLI + systemd Timer

Trên mỗi VM dùng cert từ step-CA, thiết lập auto-renew:

# Tạo script renew
cat > /usr/local/bin/renew-cert-authentik.sh << 'EOF'
#!/bin/bash
set -e

CERT="/opt/authentik/certs/authentik.crt"
KEY="/opt/authentik/certs/authentik.key"
CA_URL="https://step-ca.hoatranlabs.local:9000"
ROOT_CA="/usr/local/share/ca-certificates/hoatranlabs-root.crt"

# Renew khi cert đã qua 66% thời hạn (mặc định của step certificate needs-renewal)
# Authentik không đọc file cert trực tiếp: worker import cặp cert/key từ /certs (= /opt/authentik/certs
# trên host, bài 14 mục 7.3) vào database, nên sau khi renew phải import lại rồi restart server để HTTPS :9443 dùng cert mới
step certificate needs-renewal "${CERT}" && \
  step ca renew --force "${CERT}" "${KEY}" \
    --ca-url "${CA_URL}" \
    --root "${ROOT_CA}" && \
  docker compose -f /opt/authentik/docker-compose.yml exec -T worker \
    ak import_certificate --certificate /certs/authentik.crt --private-key /certs/authentik.key --name authentik && \
  docker compose -f /opt/authentik/docker-compose.yml restart server || true
EOF
chmod +x /usr/local/bin/renew-cert-authentik.sh

# Tạo systemd service renew
cat > /etc/systemd/system/renew-cert-authentik.service << 'EOF'
[Unit]
Description=Renew Authentik TLS Certificate
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/renew-cert-authentik.sh
EOF

# Tạo systemd timer (chạy 2 lần mỗi ngày)
cat > /etc/systemd/system/renew-cert-authentik.timer << 'EOF'
[Unit]
Description=Timer for Authentik cert renewal
Requires=renew-cert-authentik.service

[Timer]
OnCalendar=*-*-* 03,15:00:00
RandomizedDelaySec=600
Persistent=true

[Install]
WantedBy=timers.target
EOF

systemctl daemon-reload
systemctl enable --now renew-cert-authentik.timer
Terminal VM234: `systemctl list-timers | grep renew-cert` hiện renew-cert-authentik.timer, lần chạy kế tiếp quanh 03:00 hoặc 15:00 (trễ ngẫu nhiên tối đa 10 phút).
Terminal VM234: `systemctl list-timers | grep renew-cert` hiện renew-cert-authentik.timer, lần chạy kế tiếp quanh 03:00 hoặc 15:00 (trễ ngẫu nhiên tối đa 10 phút).

Bảng Inventory Certificate

ServiceVMDomainCert PathRenew MethodExpiry
AuthentikVM234authentik.hoatranlabs.local/opt/authentik/certs/authentik.crtsystemd timer90 ngày
MailuVM246mail.hoatranlabs.local/opt/mailu/certs/cert.pemsystemd timer90 ngày
GiteaVM240gitea.hoatranlabs.local/opt/gitea/ssl/cert.pemsystemd timer90 ngày
HarborVM239harbor.hoatranlabs.local/etc/ssl/harbor/harbor.crtsystemd timer90 ngày
VaultwardenVM243vaultwarden.hoatranlabs.local/etc/ssl/vaultwarden/vaultwarden.crtsystemd timer90 ngày
step-CAVM242step-ca.hoatranlabs.local/etc/step-ca/certs/Internal10 năm
HeadscaleVM232headscale.hoatranlabs.local/etc/ssl/headscale/headscale.crtsystemd timer90 ngày
Proxmox VE (node1–node4)—node1…node4.hoatranlabs.local/etc/pve/local/pveproxy-ssl.pem (bài 09)ACME (pve-daily-update, provisioner acme)90 ngày
12

Cấu Hình DNS và Firewall

Thêm A records trong Pi-hole:

DomainIP
step-ca.hoatranlabs.local10.11.25.42
pki.hoatranlabs.local10.11.25.42
Pi-hole Admin → Settings → Local DNS Records (khung Local DNS records): hai bản ghi step-ca.hoatranlabs.local và pki.hoatranlabs.local cùng trỏ về 10.11.25.42.
Pi-hole Admin → Settings → Local DNS Records (khung Local DNS records): hai bản ghi step-ca.hoatranlabs.local và pki.hoatranlabs.local cùng trỏ về 10.11.25.42.

Quy tắc firewall (VLAN_SEC):

NguồnĐíchPortProtocolMục đích
Tất cả VM10.11.25.429000TCPXin / renew cert
10.11.45.35 (Prometheus)10.11.25.429100TCPMetrics scrape
Admin VLAN10.11.25.4222TCPSSH admin
10.11.25.42 (step-CA)node1–node4 (10.11.45.210–213), pbs01 (10.11.45.17)80TCPstep-CA xác thực challenge http-01 khi Proxmox/PBS xin cert qua ACME (bài 09); mở trên FortiGate, VM242 mặc định cho phép kết nối đi ra

Mở port trên VM242:

ufw allow from 10.11.0.0/16 to any port 9000 proto tcp
# Site phụ (node5, node6, pbsdr01 — bài 09 xin chứng chỉ ACME từ đây); cần thêm policy FortiGate 10.100.100.0/24 -> 10.11.25.42:9000
ufw allow from 10.100.100.0/24 to any port 9000 proto tcp
ufw allow from 10.11.45.35 to any port 9100 proto tcp
ufw allow from 10.11.45.0/24 to any port 22 proto tcp
ufw enable
Docker và ufw: cổng 9000 do Docker publish (9000:9000 trong compose) đi qua chuỗi iptables riêng của Docker nên bỏ qua luật ufw ở trên: hai dòng ufw allow ... port 9000 chỉ còn tác dụng ghi nhận ý định, còn lọc nguồn thật sự phải làm ở FortiGate (bảng quy tắc phía trên). Cổng 9100 (node_exporter) và 22 chạy trên host nên vẫn do ufw kiểm soát. Không dùng 127.0.0.1:9000:9000 vì các VM khác cần gọi cổng 9000 qua IP 10.11.25.42. Lưu ý FortiGate chỉ thấy lưu lượng đi qua nó: máy cùng VLAN 25 (ví dụ Authentik 10.11.25.40) gọi thẳng VM242 mà không qua FortiGate. Muốn lọc nguồn cả trường hợp đó ngay trên VM242, thêm luật vào chuỗi DOCKER-USER của iptables (chuỗi dành cho luật của quản trị viên, xem mục "Docker and ufw" trong https://docs.docker.com/engine/network/packet-filtering-firewalls/); luật cụ thể cần kiểm lại trên máy thật.
13

Cấu Hình Backup PBS

Đăng nhập PVE → Datacenter → Backup → Add:

Node        : node1
Storage     : pbs-primary (pbs01, 10.11.45.17)
Schedule    : daily 01:00
VMs         : 242
Mode        : Snapshot
Retention   : mặc định (retention do Prune Job trên PBS quản lý, bài 04 mục 7)
Proxmox Datacenter → Backup: job daily 01:00, storage pbs-primary, VM 242, mode Snapshot, retention keep-daily=14 và keep-weekly=8.
Proxmox Datacenter → Backup: job daily 01:00, storage pbs-primary, VM 242, mode Snapshot, retention keep-daily=14 và keep-weekly=8.

Backup file-level từ trong VM242 (PBS in-VM, bài 04 mục 5.7): job vzdump ở trên chụp cả đĩa VM, còn bước này đưa riêng dữ liệu CA (/etc/step-ca: khóa mã hóa, config/, db/) và file compose (/opt/step-ca) vào namespace vm-step-ca, để khôi phục từng file mà không phải dựng lại VM. Token vm-backup@pbs!step-ca và namespace tạo sẵn theo bài 04 mục 5.7.

# Cài proxmox-backup-client trên Ubuntu 24.04 (cách chuẩn của series): repo client-only pbs-client, suite trixie,
# dạng deb822 + Signed-By. Gói proxmox-backup-client-static là bản tĩnh (chỉ phụ thuộc qrencode), nên không vướng glibc của noble.
# (Cần kiểm lại trên máy thật: apt trên Ubuntu 24.04 nhận repo suite trixie và chạy được binary static.)
wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg -O /usr/share/keyrings/proxmox-archive-keyring.gpg
cat > /etc/apt/sources.list.d/pbs-client.sources << 'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pbs-client
Suites: trixie
Components: main
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
apt update && apt install -y proxmox-backup-client-static

# Dừng container trong lúc backup để Badger (/etc/step-ca/db) nhất quán. CA ngừng cấp/gia hạn cert trong ít phút;
# chứng chỉ đã cấp vẫn hợp lệ. Chọn giờ vắng (client gia hạn lại ở lần timer kế tiếp).
cd /opt/step-ca
docker compose stop step-ca

export PBS_PASSWORD='<TOKEN_SECRET>'     # secret của token vm-backup@pbs!step-ca
export PBS_FINGERPRINT='<FINGERPRINT>'   # fingerprint của pbs01 (bài 04 mục 5.3), cần khi chứng chỉ PBS là tự ký

proxmox-backup-client backup \
  step-ca-data.pxar:/etc/step-ca \
  step-ca-compose.pxar:/opt/step-ca \
  --repository 'vm-backup@[email protected]:syno-primary' \
  --ns vm-step-ca

docker compose start step-ca
docker compose ps

/etc/step-ca chứa khóa Root/Intermediate (đã mã hóa), secrets/password và config/; /opt/step-ca chứa docker-compose.yml và secrets/ca_password. Vì thế token backup, namespace vm-step-ca và kho PBS phải được hạn chế quyền như chính khóa CA; nên bật mã hóa phía client của proxmox-backup-client (--keyfile) nếu kho PBS dùng chung với dữ liệu thường. Khôi phục: docker compose stop step-ca, restore hai thư mục về đúng đường dẫn, kiểm tra chủ sở hữu bằng ls -ln /etc/step-ca (phải là 1000 1000), docker compose up -d.

Backup offline Root CA key (quan trọng nhất):

# Tạo thư mục backup (chỉ root đọc được)
mkdir -p /opt/backup-pki
chmod 700 /opt/backup-pki

# Xuất Root CA cert (public, an toàn để backup)
cp /etc/step-ca/certs/root_ca.crt /opt/backup-pki/
cp /etc/step-ca/certs/intermediate_ca.crt /opt/backup-pki/

# Backup encrypted Root CA private key (CHỈ lưu offline, USB hoặc vault)
# Private key đã được mã hóa bằng mật khẩu ở /opt/step-ca/secrets/ca_password (bản sao: /etc/step-ca/secrets/password); lưu mật khẩu RIÊNG với file khóa
cp /etc/step-ca/secrets/root_ca_key /opt/backup-pki/root_ca_key.enc
# SAO CHÉP /opt/backup-pki/ RA USB / OFFSITE STORAGE

Xử Lý Sự Cố (Troubleshooting)

step-ca không khởi động:

cd /opt/step-ca
docker compose ps                       # Exit / Restarting / (unhealthy)?
docker compose logs --tail=50 step-ca
# Thường gặp: sai mật khẩu, file permission (chủ sở hữu /etc/step-ca khác 1000), port đã dùng

# Kiểm tra port 9000 (docker-proxy phải đang giữ cổng)
ss -tlnp | grep 9000

# Trạng thái healthcheck gần nhất
docker inspect step-ca --format '{{json .State.Health}}'

# Chạy thử foreground để xem lỗi
docker compose stop step-ca && docker compose up step-ca     # Ctrl+C rồi docker compose up -d
Triệu chứng trong docker compose logsNguyên nhân thường gặpCách xử lý
there is no ca.json config file; please run step ca init, or provide config parameters via DOCKER_STEPCA_INIT_ varsThiếu DOCKER_STEPCA_INIT_NAME/DOCKER_STEPCA_INIT_DNS_NAMES, hoặc bind mount sai (thư mục host trống/khác /etc/step-ca)Kiểm tra environment: và dòng volumes: trong docker-compose.yml, ls /etc/step-ca/config/ca.json
permission denied khi ghi /home/step/... hoặc mở ca.json/dbThư mục host do root sở hữu (ví dụ do Docker tự tạo) hoặc sai uidchown -R 1000:1000 /etc/step-ca rồi chmod 755 /etc/step-ca /etc/step-ca/certs, khởi động lại container
Lỗi đọc/giải mã khóa intermediate_ca_key (thông báo thường có chữ decrypt hoặc password; nguyên văn cần kiểm lại trên máy thật)Mật khẩu trong /etc/step-ca/secrets/password không khớp khóaĐặt lại đúng mật khẩu đã lưu ở Bước 4, quyền 600, owner 1000
operation not permitted ngay khi exec step-caTùy chọn no-new-privileges không tương thích môi trường của bạn (cần kiểm lại trên máy thật)Bỏ security_opt trong compose rồi docker compose up -d
Container unhealthy nhưng curl -k .../health từ host vẫn okextra_hosts bị xóa nên step ca health trong container phân giải sai tênKhôi phục dòng extra_hosts: step-ca.hoatranlabs.local:127.0.0.1

Cert bị từ chối (certificate not trusted):

# Kiểm tra Root CA đã được trust chưa
cat /etc/ssl/certs/hoatranlabs-root.pem
# Nếu rỗng: chạy lại distribute-root-ca.sh

# Verify cert chain
openssl verify -CAfile /usr/local/share/ca-certificates/hoatranlabs-root.crt \
  /opt/authentik/certs/authentik.crt
# Kết quả mong đợi: /opt/authentik/certs/authentik.crt: OK

ACME certificate request thất bại:

# Kiểm tra ACME endpoint
curl -sk https://step-ca.hoatranlabs.local:9000/acme/acme/directory | python3 -m json.tool

# Kiểm tra provisioner ACME tồn tại (chạy trong container, giống Bước 6)
docker exec step-ca step ca provisioner list
# Thiếu "acme": thêm lại bằng `docker exec step-ca step ca provisioner add acme ...` + `docker kill -s HUP step-ca` (Bước 6)

# Xem log CA lúc client xin cert
docker compose -f /opt/step-ca/docker-compose.yml logs --tail=50 step-ca

Proxmox báo lỗi khi pvenode acme cert order (bài 09):

Triệu chứngNguyên nhân thường gặpCách xử lý
certificate verify failed / unable to get local issuer certificate khi đăng ký accountNode chưa tin Root CAChạy distribute-root-ca.sh (Bước 9) trên node, kiểm tra curl https://step-ca.hoatranlabs.local:9000/health không cần -k
Order invalid, challenge http-01 timeout/connection refusedstep-CA không vào được cổng 80 của node (FortiGate hoặc firewall node), hoặc DNS của container step-ca (không đọc /etc/hosts của VM242) không phân giải nodeNTừ VM242: curl -v http://node1.hoatranlabs.local/ (kết nối được là đủ); trong container: docker exec step-ca getent hosts node1.hoatranlabs.local; mở policy tcp/80 VLAN 25 → VLAN 45
acme: provisioner not found / 404 ở Directory URLSai tên provisioner trong URLDùng đúng https://step-ca.hoatranlabs.local:9000/acme/acme/directory; kiểm tra bằng docker exec step-ca step ca provisioner list
Cert đã cấp nhưng trình duyệt vẫn cảnh báoTrình duyệt/máy khách chưa tin Root CACài root_ca.crt vào máy khách (GPO, hoặc import thủ công)

Cert sắp hết hạn không tự renew:

# Kiểm tra timer
systemctl list-timers | grep renew-cert

# Chạy renew thủ công
/usr/local/bin/renew-cert-authentik.sh

# Kiểm tra thời hạn cert còn lại
step certificate inspect /opt/authentik/certs/authentik.crt --short

Checklist Hoàn Thành

  • VM242 tạo thành công (Ubuntu Server 24.04 LTS), IP 10.11.25.42/24, VLAN_SEC tag=25
  • Docker Engine từ repo download.docker.com (suite noble) + Compose plugin (docker --version, docker compose version); systemctl is-enabled docker báo enabled
  • step CLI 0.31.0 cài từ gói .deb trên host (step version); image smallstep/step-ca:0.30.2 đã pull, ghim tag trong compose (docker exec step-ca step-ca version); không còn dùng step-ca 0.27.4 (CVE-2025-44005)
  • Root CA khởi tạo thành công tại /etc/step-ca/ (bind mount của container, owner 1000:1000); certs/*.crt đọc được từ host (644)
  • Root CA fingerprint đã ghi lại và lưu an toàn
  • Root CA password lưu trong vault/offline; /opt/step-ca/secrets/ca_password quyền 600, không có mật khẩu trong compose; log khởi tạo đã xóa (up -d --force-recreate)
  • Container step-ca chạy ổn định (docker compose ps báo Up ... (healthy)), restart: unless-stopped, giới hạn log json-file 10m x 5
  • ACME provisioner acme có trong ca.json (DOCKER_STEPCA_INIT_ACME); https://step-ca.hoatranlabs.local:9000/acme/acme/directory trả về JSON
  • CA health check trả về {"status": "ok"}
  • Root CA cert phân phối đến tất cả VM (update-ca-certificates)
  • TLS cert cấp cho Authentik, Harbor, Gitea thành công
  • Auto-renew systemd timer chạy trên từng VM có cert
  • node_exporter 1.12.1 chạy, Prometheus scrape được
  • (Làm bài 09) Node Proxmox tin Root CA, step-CA vào được cổng 80 của node, pvenode acme cert order báo Task OK
  • DNS: step-ca.hoatranlabs.local, pki.hoatranlabs.local trỏ đúng IP
  • Firewall cho phép port 9000 từ tất cả VM nội bộ
  • Backup PBS định kỳ cho VM242 (job vzdump + proxmox-backup-client cho /etc/step-ca và /opt/step-ca, namespace vm-step-ca)
  • Root CA private key backup offline (USB/vault)

Phụ Lục: Phương Án Thay Thế — Cài Gói .deb + systemd (Không Dùng Docker)

Dùng khi VM242 không được phép cài Docker, hoặc khi muốn PKI không phụ thuộc Docker daemon (chạy trong LXC không đặc quyền cũng theo cách này). Dữ liệu vẫn ở /etc/step-ca nên client, các bài khác và backup không đổi; khác nhau ở cách chạy, chủ sở hữu thư mục và đường dẫn ghi trong ca.json.

ViệcDocker (cách của bài)Gói .deb + systemd
Chạy / dừngdocker compose up -d / docker compose stop step-casystemctl enable --now step-ca / systemctl stop step-ca
Nạp lại ca.jsondocker kill -s HUP step-casystemctl reload step-ca
Restartdocker compose restart step-casystemctl restart step-ca
Xem logdocker compose logs step-cajournalctl -u step-ca
Lệnh quản trị CAdocker exec step-ca step ... --ca-config /home/step/config/ca.jsonsudo -u step env STEPPATH=/etc/step-ca step ... --ca-config /etc/step-ca/config/ca.json
Xem phiên bảndocker exec step-ca step-ca versionstep-ca version
Chủ sở hữu /etc/step-cauid:gid 1000:1000user hệ thống step
Mật khẩu CA/etc/step-ca/secrets/password (từ Docker secret)/etc/step-ca/password.txt
Nâng cấpđổi tag image, docker compose up -dapt install ./step-ca_<phiên bản>-1_amd64.deb

Cài mới bằng gói .deb (thay cho phần Docker của Bước 2–5; vẫn cài step CLI 0.31.0 như Bước 3 nhưng bỏ docker pull, và bỏ Bước 4 vì mật khẩu tạo ở đây):

# Gói step-ca đặt /usr/bin/step-ca và KHÔNG tạo user `step`, KHÔNG kèm unit systemd: tạo user và unit bên dưới
useradd --system --no-create-home --shell /bin/false step
install -d -o step -g step -m 755 /etc/step-ca

STEP_CA_VERSION="0.30.2"
cd /tmp
wget "https://github.com/smallstep/certificates/releases/download/v${STEP_CA_VERSION}/step-ca_${STEP_CA_VERSION}-1_amd64.deb"
apt install -y "./step-ca_${STEP_CA_VERSION}-1_amd64.deb"
step-ca version

( umask 077; openssl rand -base64 32 | tr -d '\n' > /etc/step-ca/password.txt )
chown step:step /etc/step-ca/password.txt

# STEPPATH=/etc/step-ca để init tạo certs/, config/, secrets/, db/ tại đó. Không dùng --root/--key (chỉ dành cho root CA đã có sẵn)
sudo -u step env STEPPATH=/etc/step-ca step ca init \
  --name "HoatranLabs Internal CA" \
  --dns "step-ca.hoatranlabs.local" \
  --dns "10.11.25.42" \
  --address ":9000" \
  --provisioner "[email protected]" \
  --password-file /etc/step-ca/password.txt \
  --deployment-type standalone \
  --acme

chmod 755 /etc/step-ca/certs
chmod 644 /etc/step-ca/certs/*.crt

cat > /etc/systemd/system/step-ca.service << 'EOF'
[Unit]
Description=Smallstep Certificate Authority
Documentation=https://smallstep.com/docs/step-ca
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=step
Group=step
Environment=STEPPATH=/etc/step-ca
ExecStart=/usr/bin/step-ca /etc/step-ca/config/ca.json \
  --password-file /etc/step-ca/password.txt
ExecReload=/bin/kill --signal HUP $MAINPID
Restart=on-failure
RestartSec=5s

# Security hardening
NoNewPrivileges=yes
ProtectSystem=strict
ReadWritePaths=/etc/step-ca
ProtectHome=yes
PrivateTmp=yes

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now step-ca
systemctl status step-ca

Từ Bước 6 trở đi mọi thứ giống bài, chỉ thay lệnh theo bảng trên (claims sửa trên /etc/step-ca/config/ca.json rồi systemctl reload step-ca).

Chuyển đổi giữa hai cách (cần kiểm lại trên máy thật): trong container STEPPATH là /home/step nên config/ca.json và config/defaults.json ghi đường dẫn tuyệt đối /home/step/...; bản .deb dùng /etc/step-ca/.... Khi chuyển phải đổi đường dẫn trong hai file này và đổi chủ sở hữu thư mục dữ liệu, rồi đối chiếu lại fingerprint root CA (phải không đổi).

# Docker -> .deb + systemd
cd /opt/step-ca && docker compose down
chown -R step:step /etc/step-ca
sed -i 's#/home/step#/etc/step-ca#g' /etc/step-ca/config/ca.json /etc/step-ca/config/defaults.json
cp /etc/step-ca/secrets/password /etc/step-ca/password.txt && chown step:step /etc/step-ca/password.txt && chmod 600 /etc/step-ca/password.txt
# rồi tạo unit systemd như trên (ExecStart dùng --password-file /etc/step-ca/password.txt) và: systemctl enable --now step-ca

# .deb + systemd -> Docker
systemctl disable --now step-ca
chown -R 1000:1000 /etc/step-ca
sed -i 's#/etc/step-ca#/home/step#g' /etc/step-ca/config/ca.json /etc/step-ca/config/defaults.json
install -D -m 600 -o 1000 -g 1000 /etc/step-ca/password.txt /etc/step-ca/secrets/password
install -d -m 755 /opt/step-ca && install -d -o 1000 -g 1000 -m 700 /opt/step-ca/secrets
install -m 600 -o 1000 -g 1000 /etc/step-ca/password.txt /opt/step-ca/secrets/ca_password
# rồi tạo /opt/step-ca/docker-compose.yml như Bước 5 (ca.json đã có nên entrypoint bỏ qua bước init) và: docker compose up -d

Tài Liệu Tham Khảo

Zalo