System & Network Vault / OpenBao
Bài 34 · Giai đoạn 7 — Observability & Security nâng cao

HashiCorp Vault Secrets Management

Machine-to-machine secrets cho CI/CD — AppRole, K8s auth, dynamic credentials.

VM269 · node1 Ubuntu Server 24.04 LTS 10.11.25.10 2 vCPU · 4 GB · 20 GB

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

Vị trí trong chuỗi bài: Bài 34 thuộc Giai đoạn 7 — Observability & Security nâng cao, nối tiếp Bài 33. Loki Log Stack và đứng trước Bài 35. TheHive SOAR.
Mức độ cần thiết: 🟡 Quan trọng — Centralized secrets store cho CI/CD và K3s
Bản quyền — Business Source License (BSL 1.1): HashiCorp Vault đổi sang BSL từ tháng 8/2023 — không phải open-source theo tiêu chuẩn OSI (mã nguồn bản 2.x vẫn mang header BUSL-1.1). BSL cấm dùng Vault để xây sản phẩm/dịch vụ cạnh tranh trực tiếp với HashiCorp. Với doanh nghiệp dùng nội bộ (không bán lại, không tạo SaaS cạnh tranh), Vault vẫn miễn phí sử dụng. Nếu cần giải pháp 100% open-source (MPL 2.0), hãy dùng Phương án 2: OpenBao ở cuối tài liệu này.

Hiện tại credentials (database passwords, API keys, TLS private keys) đang nằm rải rác trong .env files, GitLab/Gitea CI variables, và config files trên các VM. Khi rotate một secret, phải sửa thủ công hàng chục nơi. HashiCorp Vault cung cấp single source of truth cho secrets: ứng dụng và pipeline CI/CD lấy secret tại runtime, không bao giờ lưu plain text trong repo hay container image.

Vault chạy bằng Docker Engine + Compose plugin trên VM269 với image chính thức hashicorp/vault (ghim tag 2.2.0, không dùng latest). VM269 chỉ chạy duy nhất một container Vault, nên vẫn giữ được nguyên tắc "Vault là tiến trình chính duy nhất trên máy" của hướng dẫn production hardening. Storage backend dùng Raft integrated (built-in HA, không cần Consul). Cấu hình, chứng chỉ TLS, dữ liệu Raft, audit log và snapshot nằm ở các thư mục bind mount trên host (/etc/vault.d, /opt/vault/...) nên bản sao lưu file-level của PBS (bài 04 mục 5.7) lấy được; nâng cấp = đổi tag image rồi tạo lại container (mục 7).

MụcNội dung
Ứng dụng trong doanh nghiệpSecrets cho Gitea CI, K3s pods, database dynamic creds, SSH cert signing
Tác dụng chínhZero-trust secrets: rotate tập trung, audit log toàn bộ, TTL-based leases
Nếu không triển khaiSecrets hardcoded trong config/repo, không có audit trail, rotation thủ công
Các service phụ thuộc vào đâyGitea CI, K3s (external-secrets), ứng dụng dùng dynamic DB creds

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 VM269 (image hashicorp/vault)Khuyến nghị — mục 1–8HashiCorp phát hành image chính thức trên Docker Hub, tag theo từng phiên bản nên ghim được 2.2.0; từ Vault 2.0.2 image chạy bằng user vault và không còn đòi capability IPC_LOCK. Đường dẫn dữ liệu trên host (/etc/vault.d, /opt/vault/data, /opt/vault/tls, /opt/vault/logs, /opt/vault/snapshots) giống phương án binary nên backup PBS không đổi. VMID, IP, VLAN, node giữ nguyênTừ binary sang Docker (và ngược lại): snapshot Raft rồi restore, xem "Phụ lục" cuối bài
LXC không đặc quyền (template Ubuntu 24.04)Lựa chọn nhẹ, không làm trong bàiDocker không chạy trong LXC (Proxmox không khuyến nghị) nên LXC chỉ hợp với cách binary + systemd ở "Phụ lục". Vault chứa bí mật nhạy cảm mà CT dùng chung nhân với node, nên môi trường nghiêm ngặt vẫn chọn VM; mlock/swap trong CT cần kiểm lại trên máy thậtCTID = 269 (không dựng song song VM269), IP 10.11.25.10; tạo CT theo bài 07 mục 11, cài binary theo "Phụ lục", khôi phục từ snapshot Raft
VM cài trực tiếp: binary + systemdPhương án thay thế ("Phụ lục")Một file binary tĩnh, không phụ thuộc Docker daemon; đổi lại phải tự quản user, unit systemd, quyền thư mục và nâng cấp bằng tayDừng container, cài binary, dùng chung thư mục dữ liệu hoặc restore snapshot ("Phụ lục")

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

  • Vault phụ thuộc Docker daemon: docker.service được bật khi boot và container có restart: unless-stopped, nên Vault tự chạy lại sau khi VM khởi động lại, nhưng luôn ở trạng thái sealed cho tới khi bạn unseal (mục 3.2, hoặc script lab ở mục 3.3).
  • Khóa bộ nhớ (mlock): image 2.x chạy bằng user không phải root và binary không còn file capability cap_ipc_lock, nên bài đặt disable_mlock = true (Raft cũng yêu cầu khai báo tường minh tham số này) và bù lại bằng swap tắt trên VM (mục 1.4).
  • Quyền dùng Docker daemon tương đương root trên VM269: chỉ sysadmin (qua sudo) quản trị VM này, không thêm user khác vào nhóm docker; ai vào được docker exec vault cùng VAULT_TOKEN là có quyền theo token đó.
  • Cổng container đã publish đi vòng qua luật ufw: phải lọc nguồn ở FortiGate hoặc chuỗi DOCKER-USER (mục 2.7).

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
vault (HashiCorp Vault) · VM26910.11.25.1025 (SEC) · node1Máy chủ của bài — Ubuntu 24.04 chạy Vault 2.2.0 bằng Docker Compose (image hashicorp/vault), storage Raft tích hợp; API/UI HTTPS cổng 8200, cluster cổng 8201.
node1 (Proxmox VE)10.11.45.21045 (MGMT) · cluster HOATRANHUBNode Proxmox chứa VM269; tạo VM (VLAN tag 25, scsi0 20 GiB trên SSD vm-ceph) và cài Ubuntu qua qm terminal.
pihole (Pi-hole DNS) · VM24710.11.45.5345 (MGMT) · node3Làm DNS cho VM và phân giải vault.hoatranlabs.local về Vault (thêm thủ công hoặc qua add_dns_records.sh, bài 12).
step-ca (step-CA PKI) · VM24210.11.25.4225 (SEC) · node1Cấp chứng chỉ TLS cho listener Vault (SAN gồm FQDN, IP, loopback, localhost) qua step ca certificate, hiệu lực 90 ngày, gia hạn tự động (bài 13).
authentik (Authentik SSO) · VM23410.11.25.4025 (SEC) · node1Nhà cung cấp OIDC cho đăng nhập Vault (application slug vault); nhóm vault-admins ánh xạ policy admin (bài 14).
gitea (Gitea + Actions) · VM24010.11.45.4045 (MGMT) · node2Pipeline Gitea CI đăng nhập Vault bằng AppRole gitea-ci (VAULT_ROLE_ID, VAULT_SECRET_ID trong Gitea Secrets) qua API HTTPS để lấy secret (bài 22).
K3s API VIP (kube-vip)10.11.65.5565 (SRV) · — (VIP)Địa chỉ API K3s cổng 6443 mà Vault dùng cho Kubernetes auth (token reviewer) để pod xác thực vào Vault (bài 28).
prometheus (Prometheus + Alertmanager) · VM23510.11.45.3545 (MGMT) · node2Scrape metrics Vault tại /v1/sys/metrics (HTTPS, không cần token nhờ unauthenticated_metrics_access) bằng job vault trong prometheus.yml (bài 15).
pbs01 (PBS Primary) · VM10110.11.45.1745 (MGMT) · node4Nhận backup file-level snapshot Raft và /etc/vault.d bằng proxmox-backup-client, token vm-backup@pbs!vault, namespace vm-vault (bài 04).
syno-primary (Synology NAS)10.11.45.1645 (MGMT) · NASNAS chứa datastore syno-primary — đích lưu bản backup snapshot Raft và cấu hình Vault (bài 04).

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.

Thông tin VM

Thông sốGiá trị
VMID269
Hostnamevault
IP10.11.25.10/24
Gateway10.11.25.1
VLAN25 (VLAN_SEC)
vCPU2
RAM4 GB
Disk20 GB (scsi0, SSD vm-ceph)
OSUbuntu Server 24.04 LTS
Phân bổ nodenode1
Triển khaiDocker Compose, image hashicorp/vault:2.2.0
Cổng8200/TCP (API + Web UI, HTTPS), 8201/TCP (cluster Raft)
Dung lượng đĩa theo kế hoạch lab 800 GB SSD + 1 TB HDD (bài 07, mục 8.4): dựng bằng create-lab-vms.sh thì scsi0 = 20 GB trên SSD vm-ceph, không có đĩa dữ liệu scsi1 (Raft cần fsync nhanh nên ở lại SSD); số 20 GB khớp vms.csv và chỉ là trần danh nghĩa (thin provisioning), môi trường thật nên cấp lớn hơn (bài từng ghi 50 GB). Dữ liệu Raft, snapshot (giữ 7 ngày, mục 5.4) và audit log (xoay vòng 14 ngày, mục 3.4) chỉ khoảng 1-2 GB theo ước tính bài 07 mục 8.6, nên 20 GB đủ cho cả hệ điều hành lẫn image Docker.

Phiên bản phần mềm sử dụng (đã xác minh 2026-10-15; các dòng Vault, image và OpenBao kiểm lại 2026-10-16):

Thành phầnPhiên bảnGhi chú
Hệ điều hànhUbuntu Server 24.04.5 LTS "Noble Numbat" (ISO ubuntu-24.04.5-live-server-amd64.iso)24.04.5 ra ngày 2026-09-10; hỗ trợ chuẩn tới 04/2029. Kernel GA 6.8, systemd 255, OpenSSH 9.6, netplan 1.0, apt 2.7 (nguồn deb822).
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 13 và 22; VM dựng từ template 9001 (bài 07) đã có sẵn Docker.
Docker Compose plugin / Buildx5.6.0 / 0.38.0Lệnh docker compose.
HashiCorp Vault (image hashicorp/vault:2.2.0)2.2.0 (GA 2026-10-15)Bản mới nhất trên Docker Hub và releases.hashicorp.com; index digest sha256:e0acd3c681bdf57f002d7214e5d050b876e1704678005c6b0406dd96a65be919 (amd64, arm64, 386). Image đã đọc: USER vault (uid 100, gid 1000), cổng 8200, volume /vault/file và /vault/logs, không có healthcheck, /bin/vault không có file capability. Lý do chọn 2.x và cách dự phòng bằng 2.1.2: mục 7.
Vault 1.17.6 (bản cũ của bài)Không dùng1.17.6 (24/09/2024) là bản cuối của dòng 1.17, đã hết hỗ trợ. Với Community Edition, dòng 1.x kết thúc ở 1.21.4 (03/2026): từ 1.21.5 chỉ còn bản Enterprise, không có zip/image Community.
OpenBao (Phương án 2)2.7.1 (image openbao/openbao:2.7.1)Bản mới nhất ngày 2026-10-01 trên GitHub và Docker Hub; trước đây bài ghim 2.0.3.
step-cli0.31.0 (step-cli_0.31.0-1_amd64.deb)Giá trị dùng chung của series. Bài 13 chạy step-ca 0.30.2 bằng Docker; cặp CLI 0.31.0 với CA 0.30.2 cần kiểm lại trên máy thật.
proxmox-backup-clientproxmox-backup-client-static 4.x, repo pbs-client suite trixieBản tĩnh nên không phụ thuộc glibc của noble; cần kiểm lại trên máy thật (mục 5.4).
01

Tạo VM trên Proxmox

Tải Ubuntu ISO (nếu chưa có) · Tạo VM · Cài đặt Ubuntu 24.04

1.1 Tải Ubuntu ISO (nếu chưa có)

wget -O /var/lib/vz/template/iso/ubuntu-24.04-server.iso \
  https://releases.ubuntu.com/24.04/ubuntu-24.04.5-live-server-amd64.iso

1.2 Tạo VM

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: 269
  • Name: vault
  • Bỏ tick Start after created
3
OS:
  • Storage: local (hoặc nơi chứa ISO)
  • ISO Image: ubuntu-24.04-server.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
  • Disk size: 20 GiB, Cache: Write back, Discard: ☑
6
CPU:
  • Sockets: 1, Cores: 2, Type: x86-64-v2-AES
7
Memory:
  • Memory (MiB): 4096
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 trên node1 → tab Confirm: vault (VMID 269), 2 cores, 4096 MiB, scsi0 50G trên vm-ceph, net0 vmbr0 tag=25, Start after created tắt.
Proxmox Create VM trên node1 → tab Confirm: vault (VMID 269), 2 cores, 4096 MiB, scsi0 50G trên vm-ceph, net0 vmbr0 tag=25, Start after created tắt.
Lưu ý: Vault chạy bằng Docker Compose (image chính thức hashicorp/vault): Docker được cài ở mục 1.5, Vault ở mục 2. Nếu dựng VM269 từ template 9001 (Ubuntu 24.04 + Docker, bài 07) thì Docker đã có sẵn.

Cách 2: CLI (qm create)

qm create 269 --name vault --memory 4096 --cores 2 --sockets 1 \
  --net0 virtio,bridge=vmbr0,tag=25 \
  --scsi0 vm-ceph:20,cache=writeback \
  --ide2 local:iso/ubuntu-24.04-server.iso,media=cdrom \
  --boot "order=ide2;scsi0" \
  --ostype l26 --machine q35 --bios seabios \
  --agent 1 --serial0 socket --vga serial0
qm start 269

1.3 Cài đặt Ubuntu 24.04

Theo dõi console qua qm terminal 269:

  • Keyboard layout: English (US)
  • Network: DHCP tạm thời (sẽ đổi sau)
  • Storage: Use entire disk → LVM → no LVM group
  • Profile: username sysadmin, hostname vault
  • Ubuntu Pro: Skip for now (nếu màn hình này xuất hiện)
  • SSH: Install OpenSSH server ✓
  • Snaps: Không cần

1.4 Cấu hình sau cài đặt

# Ubuntu 24.04 có needrestart: đặt chế độ tự động để apt không hiện hộp thoại hỏi khởi động lại dịch vụ
export NEEDRESTART_MODE=a
apt update && apt upgrade -y
apt install -y qemu-guest-agent ca-certificates curl wget jq vim net-tools ufw fail2ban

systemctl enable --now qemu-guest-agent

# Cấu hình static IP
ip -br link                 # xem tên NIC thật (ens18, enp6s18...) vì máy q35 có thể không phải ens18
NIC=$(ip -br link | awk '$1!="lo"{print $1; exit}')
echo "NIC = $NIC"

# Ubuntu 24.04 ghi mạng của bản cài vào /etc/netplan/50-cloud-init.yaml (DHCP); giữ nguyên tệp đó thì DHCP
# cộng dồn với IP tĩnh. Tắt phần mạng của cloud-init rồi thay bằng một tệp duy nhất:
echo 'network: {config: disabled}' > /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg
rm -f /etc/netplan/*.yaml
cat > /etc/netplan/01-netcfg.yaml << EOF
network:
  version: 2
  ethernets:
    ${NIC}:
      addresses: [10.11.25.10/24]
      routes:
        - to: default
          via: 10.11.25.1
      nameservers:
        addresses: [10.11.45.53]
        search: [hoatranlabs.local]
EOF
chmod 600 /etc/netplan/01-netcfg.yaml
netplan apply   # nếu đang SSH bằng IP DHCP thì phiên sẽ đứt; đăng nhập lại bằng 10.11.25.10

# Firewall cơ bản của host: chỉ SSH. KHÔNG mở 8200/8201 bằng ufw vì cổng Docker publish đi vòng qua ufw
# (lọc nguồn cho hai cổng này ở mục 2.7)
ufw default deny incoming
ufw default allow outgoing
ufw allow from 10.11.0.0/16 to any port 22
ufw --force enable

# Disable swap (Vault khuyến cáo mạnh; với image 2.x bài đặt disable_mlock = true nên swap tắt là lớp bảo vệ duy nhất
# giữ secret trong RAM khỏi bị ghi ra đĩa); Ubuntu 24.04 mặc định tạo tệp swap /swap.img nên xóa luôn
swapoff -a
sed -i '/swap/d' /etc/fstab
rm -f /swap.img

1.5 Cài Docker Engine và Compose plugin

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), cùng cách với bài 13, 14 và 22. Chạy bằng quyền root (sudo -i). Nếu VM269 được dựng từ template 9001 (bài 07) thì Docker đã có sẵn: chỉ cần chạy các lệnh kiểm tra phiên bản ở cuối.

# 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
systemctl enable --now docker

# 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
grep Suites /etc/apt/sources.list.d/docker.sources   # phải ra: Suites: noble
02

Triển khai Vault bằng Docker Compose

Chuẩn bị thư mục và quyền · Lấy TLS cert từ step-CA · File cấu hình Vault chính

Chạy toàn bộ mục 2 và các mục sau bằng quyền root (sudo -i) trên VM269.

2.1 Chuẩn bị thư mục và quyền

Trong image hashicorp/vault, Vault chạy bằng user vault (uid 100, gid 1000). Thư mục bind mount từ host phải cho user đó ghi được, nên chủ sở hữu đặt theo số uid:gid, không theo tên user trên host (gid 1000 trên host chính là nhóm của sysadmin, nên dữ liệu nhạy cảm đặt quyền cho chủ sở hữu, không mở cho nhóm).

# Cấu hình, chứng chỉ TLS, dữ liệu Raft, audit log, snapshot
mkdir -p /etc/vault.d /opt/vault/{tls,data,logs,snapshots}

chown 100:1000 /opt/vault/data /opt/vault/logs /opt/vault/snapshots
chmod 700 /opt/vault/data /opt/vault/snapshots
chmod 750 /opt/vault/logs
chown root:1000 /etc/vault.d && chmod 750 /etc/vault.d      # vault.hcl chỉ cần đọc (bind mount :ro)

# Kéo image đã ghim tag và kiểm lại user trong image
docker pull hashicorp/vault:2.2.0
docker run --rm --entrypoint id hashicorp/vault:2.2.0 vault     # uid=100(vault) gid=1000(vault) groups=1000(vault)

2.2 Lấy TLS cert từ step-CA

# Cài step CLI 0.31.0 bằng gói .deb (tên tệp có hậu tố "-1"; URL đã kiểm trả HTTP 200 ngày 2026-10-15)
STEP_VERSION="0.31.0"
wget -O /tmp/step.deb "https://dl.smallstep.com/gh-release/cli/gh-release-header/v${STEP_VERSION}/step-cli_${STEP_VERSION}-1_amd64.deb"
dpkg -i /tmp/step.deb
step version

# Bootstrap trust với step-CA (VM242). Fingerprint lấy trên VM242: step certificate fingerprint /etc/step-ca/certs/root_ca.crt (bài 13 Bước 5)
step ca bootstrap --ca-url https://step-ca.hoatranlabs.local:9000 --fingerprint <CA_FINGERPRINT>

# Lấy cert (provisioner JWK [email protected] giống bài 14; lệnh hỏi mật khẩu provisioner ở bài 13 Bước 4).
# SAN thêm 127.0.0.1 để lệnh vault chạy bên trong container (VAULT_ADDR=https://127.0.0.1:8200) xác thực được
step ca certificate vault.hoatranlabs.local \
  /opt/vault/tls/vault.crt \
  /opt/vault/tls/vault.key \
  --ca-url https://step-ca.hoatranlabs.local:9000 \
  --provisioner [email protected] \
  --san vault.hoatranlabs.local \
  --san 10.11.25.10 \
  --san 127.0.0.1 \
  --san localhost \
  --not-after 2160h    # 90 ngày (tối đa theo maxTLSCertDuration của step-CA, bài 13)

# Root CA để container tin (VAULT_CACERT, oidc_discovery_ca_pem) và để step ca renew dùng
cp "$HOME/.step/certs/root_ca.crt" /opt/vault/tls/root_ca.crt

# Khóa riêng chỉ chủ sở hữu (uid 100 của container) đọc được; cert và root CA là công khai
chown 100:1000 /opt/vault/tls/vault.key && chmod 600 /opt/vault/tls/vault.key
chmod 644 /opt/vault/tls/vault.crt /opt/vault/tls/root_ca.crt

2.3 File cấu hình Vault chính

Đường dẫn trong file là đường dẫn bên trong container (/vault/...), ánh xạ tới thư mục host ở mục 2.4.

cat > /etc/vault.d/vault.hcl << 'EOF'
ui            = true
cluster_name  = "hoatranlabs-vault"
log_level     = "info"
# Không đặt log_file: log ra stdout để Docker (json-file) giữ và xoay vòng; Alloy (bài 33) đọc được qua Docker API

# Image 2.x chạy bằng user thường, binary không có cap_ipc_lock nên không mlock được; storage Raft bắt buộc
# khai báo tham số này và tài liệu HashiCorp khuyến nghị true. Bù lại: swap đã tắt trên VM (mục 1.4)
disable_mlock = true

# Storage: Raft integrated (một node; không cần retry_join, chỉ thêm khi mở rộng cụm)
storage "raft" {
  path    = "/vault/file"
  node_id = "vault-node-1"
}

# Listener
listener "tcp" {
  address         = "0.0.0.0:8200"
  cluster_address = "0.0.0.0:8201"
  tls_cert_file   = "/vault/tls/vault.crt"
  tls_key_file    = "/vault/tls/vault.key"
  tls_min_version = "tls12"

  # Cho Prometheus scrape /v1/sys/metrics không cần token (nguồn bị giới hạn ở mục 2.7)
  telemetry {
    unauthenticated_metrics_access = true
  }
}

# Địa chỉ quảng bá ra ngoài (cổng đã publish của VM, không phải IP nội bộ của container)
api_addr     = "https://vault.hoatranlabs.local:8200"
cluster_addr = "https://10.11.25.10:8201"

# Telemetry cho Prometheus
telemetry {
  prometheus_retention_time = "30s"
  disable_hostname          = true
}
EOF

chown root:1000 /etc/vault.d/vault.hcl
chmod 640 /etc/vault.d/vault.hcl

Các điểm khác bản cấu hình binary cũ (1.17.6) và lý do:

  • disable_mlock = true: từ Vault 1.20.0, Raft đòi khai báo tường minh; từ 2.0.2 HashiCorp bỏ yêu cầu IPC_LOCK khỏi image và khuyến nghị disable_mlock = true cùng swap tắt hoặc mã hóa.
  • cluster_address là tham số của listener "tcp"; cluster_addr và api_addr là tham số cấp trên cùng. Bản cũ ghi cluster_addr trong listener nên không có tác dụng.
  • unauthenticated_metrics_access chỉ hợp lệ trong khối telemetry bên trong listener; đặt ở khối telemetry cấp trên cùng (như bản cũ) là sai chỗ.
  • Bỏ retry_join trỏ về chính node: cụm một node không cần, và trong container, tên vault.hoatranlabs.local trỏ về IP của host nên node tự gọi chính mình qua cổng publish là không cần thiết.
  • Bỏ log_file/log_rotate_*: log đi ra stdout của container (mục 2.4 có giới hạn dung lượng).

2.4 docker-compose.yml

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

services:
  vault:
    # Ghim tag (không dùng latest); nâng cấp ở mục 7. Index digest đã kiểm 2026-10-16:
    # sha256:e0acd3c681bdf57f002d7214e5d050b876e1704678005c6b0406dd96a65be919
    image: hashicorp/vault:2.2.0
    container_name: vault
    restart: unless-stopped
    user: "100:1000"                     # = user vault trong image; ghi rõ để khớp chủ sở hữu thư mục bind mount
    command: ["server"]                  # entrypoint của image thêm -config=/vault/config
    environment:
      VAULT_ADDR: "https://127.0.0.1:8200"       # cho lệnh vault chạy trong container (docker exec, healthcheck)
      VAULT_CACERT: /vault/tls/root_ca.crt
    ports:
      - "8200:8200"                      # API + Web UI (HTTPS)
      - "8201:8201"                      # cluster Raft (chỉ cần khi thêm node thứ hai)
    volumes:
      - /etc/vault.d:/vault/config:ro            # vault.hcl
      - /opt/vault/tls:/vault/tls:ro             # cert/key step-CA và root_ca.crt
      - /opt/vault/data:/vault/file              # dữ liệu Raft
      - /opt/vault/logs:/vault/logs              # audit log (mục 3.4)
      - /opt/vault/snapshots:/vault/snapshots    # snapshot Raft (mục 5.4)
    dns:
      - 10.11.45.53                      # Pi-hole (bài 12): container phân giải authentik, postgres... như host
    healthcheck:
      # vault status trả 0 = unsealed, 2 = sealed/chưa init (tiến trình vẫn sống), 1 = lỗi kết nối
      test: ["CMD-SHELL", "vault status >/dev/null 2>&1; [ $$? -ne 1 ]"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s
    stop_grace_period: 30s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    networks:
      - vault-net

networks:
  vault-net:
    name: vault-net
    driver: bridge
EOF
chmod 644 /opt/vault/docker-compose.yml     # file không chứa bí mật

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

  • image ghim tag: tag 2.2.0 đã được kiểm trên Docker Hub (cập nhật 2026-10-15). Không dùng latest/2.2 vì mỗi lần pull có thể kéo bản vá mới ngoài ý muốn trong khi Vault phải nâng cấp có kế hoạch và có snapshot trước.
  • Không có cap_add: IPC_LOCK: tài liệu HashiCorp cho 2.0.2 ghi đã bỏ yêu cầu này khỏi image chính thức; layer image 2.1.2 và 2.2.0 đã kiểm không có file capability trên /bin/vault và image chạy sẵn bằng user vault, nên thêm IPC_LOCK cho tiến trình không phải root không có tác dụng. Muốn khóa bộ nhớ thật sự phải chạy container bằng root để entrypoint tự setcap (không khuyến nghị, cần kiểm lại trên máy thật); bài chọn disable_mlock = true và swap tắt.
  • cap_drop: ALL và no-new-privileges: Vault chỉ nghe cổng 8200/8201 (> 1024), không cần capability nào. Hai tùy chọn này chỉ phù hợp với image không còn file capability (2.x); với image cũ (1.x) có cap_ipc_lock trên binary, no-new-privileges làm container không khởi động được. Nếu container báo operation not permitted, bỏ hai khối này rồi docker compose up -d (cần kiểm lại trên máy thật).
  • Bind mount :ro cho cấu hình và TLS: Vault chỉ đọc; thư mục ghi được chỉ gồm dữ liệu, log và snapshot.
  • healthcheck dùng vault status vì image từ 1.18 không còn curl. Ký hiệu $$? là cách viết $? trong Compose (một dấu $ đơn bị Compose coi là biến).
  • logging: json-file với max-size/max-file để log không phình ra đĩa; Alloy (bài 33, khối loki.source.docker nhãn job="docker-containers") đọc log container qua Docker API nên thu được log của container vault nếu bạn cài Alloy trên VM269.
  • dns trỏ Pi-hole: container không đọc /etc/hosts của host nên cần DNS để gọi authentik.hoatranlabs.local (OIDC) và các host khác.
  • Mạng bridge riêng vault-net; cổng 8200/8201 được publish trên mọi địa chỉ của VM269 (xem mục 2.7 về lọc nguồn).

2.5 Khởi động và kiểm tra

cd /opt/vault
docker compose config -q && echo "compose hợp lệ"
docker compose up -d
docker compose logs --tail=30 vault     # thấy Vault chưa khởi tạo: "seal configuration missing, not initialized" (bình thường lúc này)
docker compose ps                       # sau khoảng 30-60 giây: STATUS "Up ... (healthy)"
Terminal VM269: docker compose ps trong /opt/vault hiện container vault (image hashicorp/vault:2.2.0) ở trạng thái Up (healthy), cổng 8200 và 8201 được publish.
Terminal VM269: docker compose ps trong /opt/vault hiện container vault (image hashicorp/vault:2.2.0) ở trạng thái Up (healthy), cổng 8200 và 8201 được publish.

Lệnh vault chạy bên trong container qua docker exec. Tạo hàm vault cho shell đăng nhập của root để gõ như bình thường (biến VAULT_ADDR, VAULT_CACERT đã đặt trong container; VAULT_TOKEN lấy từ shell trên host):

cat > /etc/profile.d/vault-docker.sh << 'EOF'
# CLI vault của container "vault". -t chỉ bật khi cả stdin và stdout là terminal, để nhận lệnh qua pipe/heredoc và ghi ra file được
vault() { docker exec $([ -t 0 ] && [ -t 1 ] && echo -t) -i -e VAULT_TOKEN vault vault "$@"; }
EOF
. /etc/profile.d/vault-docker.sh

vault version            # Vault v2.2.0 ...
vault status             # Initialized false, Sealed true (chưa init, exit code 2 là bình thường)
Lệnh nào cần đọc file hoặc nhận nội dung từ host thì đưa vào qua stdin (vault policy write ten - với heredoc) hoặc đặt file trong thư mục đã bind mount (/opt/vault/snapshots ↔ /vault/snapshots), vì CLI chạy trong container không thấy /tmp của host. Trong script/systemd (không phải shell đăng nhập) dùng thẳng docker exec vault vault ....

2.6 Tự gia hạn cert

Cert step-CA hiệu lực 90 ngày. Script dưới gia hạn khi đã qua 2/3 thời hạn rồi gửi SIGHUP cho Vault: Vault nạp lại tls_cert_file/tls_key_file đã khai báo lúc khởi động mà không restart nên không phải unseal lại.

cat > /usr/local/sbin/renew-cert-vault.sh << 'EOF'
#!/bin/bash
set -euo pipefail
CERT=/opt/vault/tls/vault.crt
KEY=/opt/vault/tls/vault.key

# Chỉ gia hạn khi đã qua 66% thời hạn (mặc định của step certificate needs-renewal)
if step certificate needs-renewal "$CERT"; then
  step ca renew --force "$CERT" "$KEY" \
    --ca-url https://step-ca.hoatranlabs.local:9000 \
    --root /opt/vault/tls/root_ca.crt
  chown 100:1000 "$KEY" && chmod 600 "$KEY" && chmod 644 "$CERT"
  docker kill --signal=HUP vault     # Vault nạp lại cert TLS, không cần unseal
fi
EOF
chmod 700 /usr/local/sbin/renew-cert-vault.sh

cat > /etc/systemd/system/renew-cert-vault.service << 'EOF'
[Unit]
Description=Renew Vault TLS certificate from step-CA
After=network-online.target docker.service

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

cat > /etc/systemd/system/renew-cert-vault.timer << 'EOF'
[Unit]
Description=Timer for Vault cert renewal

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

[Install]
WantedBy=timers.target
EOF

systemctl daemon-reload
systemctl enable --now renew-cert-vault.timer

# Kiểm tra cert Vault đang phục vụ (ngày hết hạn, SAN)
openssl s_client -connect 127.0.0.1:8200 -servername vault.hoatranlabs.local </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -enddate -ext subjectAltName

2.7 Docker và UFW: lọc nguồn cho cổng 8200/8201

Cổng publish của container được Docker mở bằng luật DNAT, gói tin bị chuyển hướng trước khi tới chuỗi INPUT mà ufw quản lý, nên luật ufw không có tác dụng với 8200/8201 (tài liệu Docker: "Docker and ufw"). Có hai lớp lọc:

  • FortiGate (bắt buộc): chỉ mở các luồng sau, mọi luồng khác tới 10.11.25.10 bị chặn ở ranh giới VLAN.
NguồnĐíchCổngMục đích
prometheus 10.11.45.35VM269 10.11.25.108200/TCPScrape /v1/sys/metrics
gitea 10.11.45.40 (và job runner)VM269 10.11.25.108200/TCPAppRole gitea-ci lấy secret
Máy quản trị VLAN 45VM269 10.11.25.108200/TCPWeb UI / API
VM269 10.11.25.10K3s API VIP 10.11.65.556443/TCPKubernetes auth (TokenReview)
VM269 10.11.25.10pbs01 10.11.45.17, pihole 10.11.45.538007/TCP, 53/UDP+TCPBackup PBS, DNS
  • Chuỗi DOCKER-USER trên VM269 (tùy chọn, thêm một lớp): luật trong DOCKER-USER được xét sau DNAT nên phải khớp bằng conntrack --ctorigdstport (cổng gốc client gọi tới). Script idempotent dưới đây giới hạn 8200 cho dải 10.11.0.0/16 và 8201 cho VLAN 25 (nơi sẽ đặt node Raft thứ hai):
cat > /usr/local/sbin/vault-docker-fw.sh << 'EOF'
#!/bin/bash
# Lọc nguồn cho cổng Docker publish của Vault (ufw không áp dụng). Chạy sau docker.service; chạy lại nhiều lần vẫn an toàn
NIC=$(ip route show default | awk '{print $5; exit}')
add() { iptables -C DOCKER-USER "$@" 2>/dev/null || iptables -I DOCKER-USER "$@"; }
add -i "$NIC" -p tcp -m conntrack --ctorigdstport 8201 ! -s 10.11.25.0/24 -j DROP
add -i "$NIC" -p tcp -m conntrack --ctorigdstport 8200 ! -s 10.11.0.0/16 -j DROP
add -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT      # chèn sau cùng nên đứng đầu chuỗi
EOF
chmod 700 /usr/local/sbin/vault-docker-fw.sh

cat > /etc/systemd/system/vault-docker-fw.service << 'EOF'
[Unit]
Description=Loc nguon cong Docker cua Vault (DOCKER-USER)
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/sbin/vault-docker-fw.sh

[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now vault-docker-fw.service
iptables -S DOCKER-USER
Luật DOCKER-USER chạy đúng với Docker 29 và backend iptables-nft của Ubuntu 24.04 (Docker chỉ hỗ trợ iptables-nft/iptables-legacy) cần kiểm lại trên máy thật; nếu không chắc, chỉ dựa vào FortiGate cũng là cách chấp nhận được trong lab.
03

Khởi tạo & Unseal Vault

Initialize Vault (chỉ làm 1 lần) · Unseal lần đầu (cần 3 trong 5 keys) · Script Auto-Unseal sau reboot (lưu keys có bảo mật)

3.1 Initialize Vault (chỉ làm 1 lần)

# Initialize với 5 key shares, threshold 3; lưu kết quả vào file chỉ root đọc
(umask 077; vault operator init -key-shares=5 -key-threshold=3 \
  -format=json > /root/vault-init-keys.json)

# File này cực kỳ nhạy cảm — chép 5 unseal key và root token sang nơi lưu offline ngay lập tức!
# Sau đó xóa khỏi server (trừ khi dùng script lab ở mục 3.3)

# Đưa root token vào biến môi trường của shell (không in ra màn hình)
export VAULT_TOKEN=$(jq -r '.root_token' /root/vault-init-keys.json)

QUAN TRỌNG: Lưu 5 unseal keys và root token vào KeePass / password manager offline. Phân phát 5 keys cho 5 người khác nhau (cần 3 trong 5 keys để unseal). Root token chỉ dùng lần đầu init: khi dùng thật, tạo token/OIDC admin rồi thu hồi root token (vault token revoke -self); từ Vault 2.0, sys/generate-root cần cả key fragments lẫn một token hợp lệ (cần kiểm lại trên máy thật).

3.2 Unseal lần đầu (cần 3 trong 5 keys)

# Chạy 3 lần, mỗi lần nhập MỘT key khác nhau khi được hỏi (nhập ẩn)
vault operator unseal
vault operator unseal
vault operator unseal

vault status  # Sealed: false = thành công
Terminal VM269 (lệnh vault chạy qua docker exec): vault status sau 3 lần unseal hiện Initialized true, Sealed false, Total Shares 5, Threshold 3, Storage Type raft, Version 2.2.0.
Terminal VM269 (lệnh vault chạy qua docker exec): vault status sau 3 lần unseal hiện Initialized true, Sealed false, Total Shares 5, Threshold 3, Storage Type raft, Version 2.2.0.

Sau mỗi lần khởi động lại container hoặc VM, Vault quay về trạng thái sealed và phải unseal lại (3 lần như trên, hoặc dùng script lab ở mục 3.3).

3.3 Script Auto-Unseal sau reboot (lưu keys có bảo mật)

Đây là workaround cho môi trường lab — production nên dùng cloud KMS (AWS KMS, GCP CKMS), HSM hoặc Transit seal của một Vault khác, vì ở đây 3 key nằm ngay trên VM:

# Lưu 3 unseal keys vào file chỉ root đọc được (trích từ file init; nhớ xóa vault-init-keys.json sau đó)
(umask 277; cat > /root/.vault-unseal-keys << EOF
UNSEAL_KEY_1="$(jq -r '.unseal_keys_b64[0]' /root/vault-init-keys.json)"
UNSEAL_KEY_2="$(jq -r '.unseal_keys_b64[1]' /root/vault-init-keys.json)"
UNSEAL_KEY_3="$(jq -r '.unseal_keys_b64[2]' /root/vault-init-keys.json)"
EOF
)

cat > /usr/local/sbin/vault-unseal.sh << 'EOF'
#!/bin/bash
# Chỉ dùng cho lab: unseal tự động sau khi Docker/VM khởi động lại
source /root/.vault-unseal-keys
rc=1
for i in $(seq 1 60); do                       # chờ container sẵn sàng (tối đa ~2 phút)
  docker exec vault vault status >/dev/null 2>&1 && rc=0 || rc=$?
  [ "$rc" -ne 1 ] && break                     # 0 = đã unseal, 2 = đang sealed, 1 = chưa kết nối được
  sleep 2
done
[ "$rc" -eq 0 ] && exit 0
[ "$rc" -eq 2 ] || { echo "Vault không trả lời" >&2; exit 1; }
for k in UNSEAL_KEY_1 UNSEAL_KEY_2 UNSEAL_KEY_3; do
  export UNSEAL_KEY="${!k}"                    # truyền key bằng biến môi trường, không để trong tham số lệnh
  docker exec -e UNSEAL_KEY vault sh -c 'vault operator unseal "$UNSEAL_KEY"' >/dev/null
done
docker exec vault vault status | grep -E '^Sealed'
EOF
chmod 700 /usr/local/sbin/vault-unseal.sh

# Systemd one-shot service chạy sau khi Docker khởi động (container tự chạy lại nhờ restart: unless-stopped)
cat > /etc/systemd/system/vault-unseal.service << 'EOF'
[Unit]
Description=Vault Auto-Unseal (Lab Only)
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/vault-unseal.sh

[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable vault-unseal

3.4 Bật audit device

Bật ngay sau khi đăng nhập bằng root token để mọi thao tác ở các mục sau đều có dấu vết. Audit log nằm ở /opt/vault/logs/audit.log trên host (container thấy là /vault/logs/audit.log), file tạo với quyền mặc định 0600.

vault audit enable file file_path=/vault/logs/audit.log
vault audit list -detailed

# Xoay vòng log: Vault mở lại file khi nhận SIGHUP; "nocreate" để Vault (uid 100) tự tạo file mới sau khi xoay
cat > /etc/logrotate.d/vault-audit << 'EOF'
/opt/vault/logs/audit.log {
    daily
    rotate 14
    missingok
    notifempty
    nocreate
    compress
    delaycompress
    postrotate
        /usr/bin/docker kill --signal=HUP vault >/dev/null 2>&1 || true
    endscript
}
EOF
Khi đã bật audit device, nếu không thiết bị audit nào ghi được (đĩa đầy, sai quyền thư mục /opt/vault/logs), Vault từ chối phục vụ request. Giữ dung lượng đĩa dư và kiểm quyền 100:1000 của thư mục.
04

Cấu hình Auth Methods & Secret Engines

Enable Secret Engines · AppRole Auth (cho Gitea CI/CD) · OIDC Auth (Authentik SSO)

# Chạy trên VM269 bằng root, dùng hàm `vault` ở mục 2.5 (docker exec vào container)
# Nếu mở shell mới: nạp lại hàm và đặt lại token root (biến VAULT_TOKEN của shell trên host)
. /etc/profile.d/vault-docker.sh
export VAULT_TOKEN="<root-token-từ-init>"

4.1 Enable Secret Engines

# KV v2 — general secrets
vault secrets enable -path=secret kv-v2
vault kv put secret/test/hello value="world"
vault kv get secret/test/hello

# PKI — dynamic short-lived certs
vault secrets enable pki
# TTL của root không được lớn hơn max-lease-ttl của engine, nên nâng max lên 10 năm TRƯỚC khi tạo root
vault secrets tune -max-lease-ttl=87600h pki

vault write pki/root/generate/internal \
  common_name="hoatranlabs.local" \
  issuer_name="hoatranlabs-root" \
  ttl=87600h

vault write pki/config/urls \
  issuing_certificates="https://vault.hoatranlabs.local:8200/v1/pki/ca" \
  crl_distribution_points="https://vault.hoatranlabs.local:8200/v1/pki/crl"

vault write pki/roles/hoatranlabs-dot-local \
  allowed_domains=hoatranlabs.local \
  allow_subdomains=true \
  max_ttl=72h

# Database dynamic credentials (PostgreSQL example)
# VÍ DỤ: postgres.hoatranlabs.local không phải VM có sẵn trong lab — thay bằng host PostgreSQL thật khi áp dụng
vault secrets enable database
vault write database/config/postgres \
  plugin_name=postgresql-database-plugin \
  allowed_roles="app-readonly,app-readwrite" \
  connection_url="postgresql://{{username}}:{{password}}@postgres.hoatranlabs.local:5432/appdb?sslmode=require" \
  username="vault-admin" \
  password="Hoatran@2024!"

vault write database/roles/app-readonly \
  db_name=postgres \
  creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
  default_ttl="1h" \
  max_ttl="24h"

# SSH cert signing
vault secrets enable ssh
vault write ssh/config/ca generate_signing_key=true
vault write ssh/roles/ops-role \
  key_type=ca \
  default_extensions='{"permit-pty":"","permit-port-forwarding":""}' \
  allowed_users="sysadmin" \
  ttl=8h \
  max_ttl=24h
Vault Web UI (https://vault.hoatranlabs.local:8200/ui, khóa HTTPS hợp lệ, đăng nhập bằng token) → Secrets Engines: secret/ (KV v2), pki/, database/, ssh/.
Vault Web UI (https://vault.hoatranlabs.local:8200/ui, khóa HTTPS hợp lệ, đăng nhập bằng token) → Secrets Engines: secret/ (KV v2), pki/, database/, ssh/.
PKI của Vault và step-CA là hai gốc tin cậy khác nhau. Root hoatranlabs-root do Vault tự sinh, không nằm trong chuỗi của step-CA (bài 13): máy nào cần tin cert do Vault cấp phải cài thêm root này (vault read -field=certificate pki/cert/ca). Muốn chỉ có một gốc tin cậy thì cho step-CA ký intermediate cho engine PKI của Vault; bài không làm bước này (cần kiểm lại trên máy thật). Từ Vault 2.0.2, khóa RSA của PKI bị giới hạn tối đa 8192 bit (CVE-2026-39829), khóa mặc định của bài nằm trong giới hạn.

4.2 AppRole Auth (cho Gitea CI/CD)

vault auth enable approle

# Policy cho Gitea CI (đọc policy từ stdin vì CLI chạy trong container, không thấy file trên host)
vault policy write gitea-ci - << 'EOF'
path "secret/data/gitea/*" {
  capabilities = ["read", "list"]
}
path "secret/data/deploy/*" {
  capabilities = ["read"]
}
path "database/creds/app-readonly" {
  capabilities = ["read"]
}
path "pki/issue/hoatranlabs-dot-local" {
  capabilities = ["create", "update"]
}
EOF

# Tạo AppRole cho Gitea
vault write auth/approle/role/gitea-ci \
  token_policies="gitea-ci" \
  token_ttl=1h \
  token_max_ttl=4h \
  secret_id_ttl=720h \
  secret_id_num_uses=0

ROLE_ID=$(vault read -field=role_id auth/approle/role/gitea-ci/role-id)
SECRET_ID=$(vault write -field=secret_id -f auth/approle/role/gitea-ci/secret-id)
echo "Role ID: $ROLE_ID"
echo "Secret ID: $SECRET_ID"
# Lưu vào Gitea → Settings → Secrets: VAULT_ROLE_ID và VAULT_SECRET_ID
Gitea (VM240) → Settings → Secrets: hai secret VAULT_ROLE_ID và VAULT_SECRET_ID vừa lưu (giá trị được che).
Gitea (VM240) → Settings → Secrets: hai secret VAULT_ROLE_ID và VAULT_SECRET_ID vừa lưu (giá trị được che).

4.3 OIDC Auth (Authentik SSO)

Phía Authentik (VM234): trước khi chạy lệnh bên dưới, tạo Provider và Application theo cách của Bài 14 mục 8.1–8.2 (giống Grafana), với các giá trị: Provider vault-oidc (OAuth2/OpenID, Confidential, authorization flow default-provider-authorization-implicit-consent, Signing Key: chọn một key có sẵn như hướng dẫn tích hợp Vault của Authentik); Redirect URIs kiểu Strict, loại Authorization: https://vault.hoatranlabs.local:8200/ui/vault/auth/oidc/oidc/callback; Application Name Vault với Slug vault (slug quyết định Issuer https://authentik.hoatranlabs.local:9443/application/o/vault/). Giữ các scope mặc định openid, email, profile (claim groups nằm trong scope profile). Tạo nhóm vault-admins (không bật quyền superuser) và thêm user akadmin. Dùng Client ID/Client Secret của Provider thay cho vault-client-id / vault-client-secret. Đăng nhập OIDC từ CLI cần redirect http://localhost:8250/oidc/callback và trình duyệt cùng máy, không dùng được qua docker exec; bài đăng nhập bằng Web UI.
vault auth enable oidc

# oidc_discovery_ca_pem: container không tin step-CA nên phải đưa root CA vào (đọc từ /vault/tls trong container)
vault write auth/oidc/config \
  oidc_discovery_url="https://authentik.hoatranlabs.local:9443/application/o/vault/" \
  oidc_discovery_ca_pem=@/vault/tls/root_ca.crt \
  oidc_client_id="vault-client-id" \
  oidc_client_secret="vault-client-secret" \
  default_role="oidc-default"

# bound_audiences bắt buộc từ Vault 1.17; oidc_scopes="profile" để Authentik trả claim groups
vault write auth/oidc/role/oidc-default \
  user_claim="sub" \
  groups_claim="groups" \
  oidc_scopes="profile" \
  bound_audiences="vault-client-id" \
  allowed_redirect_uris="https://vault.hoatranlabs.local:8200/ui/vault/auth/oidc/oidc/callback" \
  token_ttl=8h \
  token_policies="default"

# Policy cho admin group từ Authentik
vault policy write admin - << 'EOF'
path "*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
EOF

# Map Authentik group "vault-admins" → policy admin
vault write identity/group name="vault-admins" type=external policies=admin
OIDC_ACCESSOR=$(vault read -field=accessor sys/auth/oidc)
vault write identity/group-alias \
  name="vault-admins" \
  mount_accessor="$OIDC_ACCESSOR" \
  canonical_id=$(vault read -field=id identity/group/name/vault-admins)

Kiểm tra: mở https://vault.hoatranlabs.local:8200/ui, chọn Method OIDC (để trống Role), nhấn Sign in with OIDC Provider, đăng nhập Authentik rồi quay về Vault. Nếu cửa sổ đăng nhập báo x509: certificate signed by unknown authority thì thiếu oidc_discovery_ca_pem; nếu báo redirect_uri_mismatch xem bài 14 mục 14.3.

Vault Web UI, màn hình đăng nhập: chọn Method OIDC, đăng nhập qua Authentik rồi quay về callback /ui/vault/auth/oidc/oidc/callback.
Vault Web UI, màn hình đăng nhập: chọn Method OIDC, đăng nhập qua Authentik rồi quay về callback /ui/vault/auth/oidc/oidc/callback.

4.4 Kubernetes Auth (K3s cluster)

Vault nằm ngoài cụm K3s nên cần một ServiceAccount làm "reviewer" (quyền system:auth-delegator để gọi TokenReview) cùng token dài hạn của nó. Bước 1 chạy trên máy admin có kubectl trỏ vào VIP 10.11.65.55 (bài 28, mục 2.5), bước 2 chạy trên VM269.

# --- Bước 1: trên máy admin (kubectl) — tạo namespace, ServiceAccount, quyền TokenReview, token và CA ---
kubectl create namespace vault
kubectl -n vault create serviceaccount vault-reviewer
kubectl create clusterrolebinding vault-reviewer-auth-delegator \
  --clusterrole=system:auth-delegator \
  --serviceaccount=vault:vault-reviewer

# Từ Kubernetes 1.24 không còn Secret token tự sinh cho ServiceAccount: tạo Secret token dài hạn
cat <<'EOF' | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: vault-reviewer
  namespace: vault
  annotations:
    kubernetes.io/service-account.name: vault-reviewer
type: kubernetes.io/service-account-token
EOF
sleep 5   # chờ controller điền token vào Secret

# Token reviewer và CA của cụm K3s (lấy từ kubeconfig của máy admin, server = VIP 10.11.65.55)
kubectl -n vault get secret vault-reviewer -o jsonpath='{.data.token}' | base64 -d > /tmp/vault-reviewer.jwt
kubectl config view --raw --minify --flatten -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' \
  | base64 -d > /tmp/k3s-ca.crt

# VÍ DỤ ứng dụng cho role app-production ở Bước 2: namespace production + ServiceAccount app-sa
kubectl create namespace production
kubectl -n production create serviceaccount app-sa

# Chuyển sang VM269 (Vault)
scp /tmp/vault-reviewer.jwt /tmp/k3s-ca.crt [email protected]:/tmp/
shred -u /tmp/vault-reviewer.jwt && rm -f /tmp/k3s-ca.crt

# --- Bước 2: trên VM269 (đã nạp hàm vault và đặt VAULT_TOKEN ở đầu mục 4) ---
vault auth enable kubernetes

# VM269 (VLAN 25) phải truy cập được 10.11.65.55:6443 (VLAN 65) qua FortiGate
K3S_HOST="https://10.11.65.55:6443"

# CLI chạy trong container không đọc được /tmp của host: ghép JSON bằng jq rồi đưa vào qua stdin ("-")
jq -n --arg host "$K3S_HOST" \
  --rawfile jwt /tmp/vault-reviewer.jwt --rawfile ca /tmp/k3s-ca.crt \
  '{kubernetes_host: $host, token_reviewer_jwt: ($jwt | rtrimstr("\n")), kubernetes_ca_cert: ($ca | rtrimstr("\n"))}' \
  | vault write auth/kubernetes/config -
# Không đặt issuer / disable_iss_validation: cả hai deprecated từ Vault 1.9.0 (mount mới đã mặc định bỏ qua
# kiểm tra issuer vì Kubernetes API tự kiểm tra khi xử lý TokenReview)

# Dọn file tạm (token reviewer đã nằm trong cấu hình Vault)
shred -u /tmp/vault-reviewer.jwt && rm -f /tmp/k3s-ca.crt

# VÍ DỤ: policy app-production mà role bên dưới tham chiếu (chỉ đọc secret của ứng dụng; đổi path theo nhu cầu)
vault policy write app-production - << 'EOF'
path "secret/data/app/production/*" {
  capabilities = ["read"]
}
EOF

# Role cho K3s namespaces (ServiceAccount app-sa / namespace production tạo ở Bước 1)
vault write auth/kubernetes/role/app-production \
  bound_service_account_names="app-sa" \
  bound_service_account_namespaces="production" \
  token_policies="app-production" \
  token_ttl=1h
Từ Vault 1.20, tạo role Kubernetes không đặt audience sẽ kèm cảnh báo; chỉ là cảnh báo. Muốn xác thực thêm claim audience thì đặt audience khớp với audience của token mà pod gửi lên (cần kiểm lại trên máy thật với K3s).
05

Tích hợp với hạ tầng

Pi-hole DNS · Prometheus Monitoring · Gitea CI — Sử dụng Vault trong pipeline

5.1 Pi-hole DNS

# Thêm DNS record vault.hoatranlabs.local → 10.11.25.10
# Cách 1: Pi-hole Admin UI → Settings → Local DNS Records (Domain: vault.hoatranlabs.local, IP: 10.11.25.10)
# Cách 2: SSH vào VM Pi-hole (chạy Docker), thêm dòng add_dns "vault.hoatranlabs.local" "10.11.25.10"
#         vào /opt/pihole/scripts/add_dns_records.sh (Bài 12) rồi chạy lại script
ssh [email protected]

5.2 Prometheus Monitoring

# Thêm vào prometheus.yml (VM235, container prometheus — Bài 15; root CA đã được mount sẵn
# vào container tại /etc/prometheus/certs/hoatranlabs-root.crt):
  - job_name: 'vault'
    metrics_path: '/v1/sys/metrics'
    params:
      format: ['prometheus']
    scheme: https
    tls_config:
      ca_file: /etc/prometheus/certs/hoatranlabs-root.crt
    static_configs:
      - targets: ['vault.hoatranlabs.local:8200']

Job không cần token vì listener có unauthenticated_metrics_access = true (mục 2.3); FortiGate chỉ cho 10.11.45.35 gọi cổng 8200 (mục 2.7). Nếu bạn muốn bắt buộc token: bỏ khối telemetry trong listener, tạo policy path "sys/metrics" { capabilities = ["read"] } rồi cấp token periodic cho Prometheus (token thường bị giới hạn bởi max_lease_ttl mặc định 768h nên sẽ hết hạn sau 32 ngày; token default cũ của bài không đọc được sys/metrics) và thêm bearer_token vào job.

Sau khi docker compose exec prometheus kill -HUP 1 hoặc reload cấu hình theo bài 15, vào Status → Targets kiểm tra job vault ở trạng thái UP.

Prometheus (VM235) → Status → Targets: job vault (vault.hoatranlabs.local:8200) ở trạng thái UP, scrape HTTPS không cần bearer_token nhờ unauthenticated_metrics_access.
Prometheus (VM235) → Status → Targets: job vault (vault.hoatranlabs.local:8200) ở trạng thái UP, scrape HTTPS không cần bearer_token nhờ unauthenticated_metrics_access.

5.3 Gitea CI — Sử dụng Vault trong pipeline

# .gitea/workflows/deploy.yml (ví dụ)
# Job container (runner-images, bài 22) không chắc có sẵn Vault CLI nên ví dụ gọi API HTTPS bằng curl + jq
# (cần kiểm lại các công cụ có trong image); job phải tin root CA step-CA (bài 22 mục 8.3)
steps:
  - name: Fetch secrets from Vault
    run: |
      VAULT_TOKEN=$(curl -sf -X POST "$VAULT_ADDR/v1/auth/approle/login" \
        -d "{\"role_id\":\"$VAULT_ROLE_ID\",\"secret_id\":\"$VAULT_SECRET_ID\"}" | jq -r '.auth.client_token')
      DB_PASSWORD=$(curl -sf -H "X-Vault-Token: $VAULT_TOKEN" \
        "$VAULT_ADDR/v1/secret/data/deploy/database" | jq -r '.data.data.password')
      echo "DB_PASSWORD=$DB_PASSWORD" >> $GITHUB_ENV
    env:
      VAULT_ADDR: https://vault.hoatranlabs.local:8200
      VAULT_ROLE_ID: ${{ secrets.VAULT_ROLE_ID }}
      VAULT_SECRET_ID: ${{ secrets.VAULT_SECRET_ID }}

5.4 Snapshot Raft và PBS Backup

Không chép trực tiếp /opt/vault/data khi Vault đang chạy. Cách sao lưu nhất quán là snapshot Raft (vault operator raft snapshot save), lưu ở /opt/vault/snapshots (thư mục bind mount nên nằm trong archive PBS) rồi đẩy lên PBS bằng proxmox-backup-client (bài 04 mục 5.7). Job chạy hằng ngày bằng một AppRole riêng chỉ có quyền đọc snapshot, không dùng root token.

# Cài proxmox-backup-client (bản static, không phụ thuộc glibc của Ubuntu 24.04) từ client-only repository công khai của Proxmox.
# Suite "trixie" là suite có bản static mới nhất (đã kiểm repo ngày 2026-10-15); chạy trên noble: cần kiểm lại trên máy thật
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

# AppRole chỉ được đọc snapshot (policy từ stdin); token sống ngắn
vault policy write raft-snapshot - << 'EOF'
path "sys/storage/raft/snapshot" {
  capabilities = ["read"]
}
EOF
vault write auth/approle/role/raft-snapshot token_policies="raft-snapshot" token_ttl=10m token_max_ttl=30m

# Role ID / Secret ID của job và secret token PBS (token + namespace tạo sẵn theo Bài 04 mục 5.7:
# user vm-backup@pbs, token "vault", ACL DatastoreBackup tại /datastore/syno-primary/vm-vault)
(umask 077; cat > /etc/vault-backup.env << EOF
VAULT_ROLE_ID=$(vault read -field=role_id auth/approle/role/raft-snapshot/role-id)
VAULT_SECRET_ID=$(vault write -field=secret_id -f auth/approle/role/raft-snapshot/secret-id)
PBS_PASSWORD='<TOKEN_SECRET>'
EOF
)
# Thay <TOKEN_SECRET> bằng secret của token vm-backup@pbs!vault:  nano /etc/vault-backup.env

cat > /usr/local/sbin/vault-backup.sh << 'EOF'
#!/bin/bash
# Snapshot Raft của container "vault" rồi đẩy lên PBS (bài 04 mục 5.7)
set -euo pipefail
source /etc/vault-backup.env
export PBS_PASSWORD
STAMP=$(date +%Y%m%d-%H%M)

# Đăng nhập AppRole raft-snapshot (secret truyền bằng biến môi trường của docker exec)
export ROLE_ID="$VAULT_ROLE_ID" SECRET_ID="$VAULT_SECRET_ID"
VAULT_TOKEN=$(docker exec -e ROLE_ID -e SECRET_ID vault sh -c \
  'vault write -field=token auth/approle/login role_id="$ROLE_ID" secret_id="$SECRET_ID"')
export VAULT_TOKEN

# Snapshot nhất quán; file xuất hiện ở /opt/vault/snapshots trên host. Giữ 7 ngày trên VM
docker exec -e VAULT_TOKEN vault vault operator raft snapshot save "/vault/snapshots/vault-${STAMP}.snap"
find /opt/vault/snapshots -name 'vault-*.snap' -mtime +7 -delete

proxmox-backup-client backup \
  vault-snapshots.pxar:/opt/vault/snapshots \
  vault-config.pxar:/etc/vault.d \
  --repository 'vm-backup@[email protected]:syno-primary' \
  --ns vm-vault
EOF
chmod 700 /usr/local/sbin/vault-backup.sh

cat > /etc/systemd/system/vault-backup.service << 'EOF'
[Unit]
Description=Vault Raft snapshot and PBS backup
After=docker.service

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/vault-backup.sh
EOF

cat > /etc/systemd/system/vault-backup.timer << 'EOF'
[Unit]
Description=Vault snapshot daily

[Timer]
OnCalendar=*-*-* 02:00:00
RandomizedDelaySec=600
Persistent=true

[Install]
WantedBy=timers.target
EOF

systemctl daemon-reload
systemctl enable --now vault-backup.timer
systemctl start vault-backup.service          # chạy thử ngay
journalctl -u vault-backup.service -n 20 --no-pager
ls -l /opt/vault/snapshots
Terminal VM269: vault-backup.service tạo file .snap trong /opt/vault/snapshots bằng vault operator raft snapshot save (docker exec), rồi proxmox-backup-client backup vault-snapshots.pxar và vault-config.pxar vào datastore syno-primary, namespace vm-vault (token vm-backup@pbs!vault).
Terminal VM269: vault-backup.service tạo file .snap trong /opt/vault/snapshots bằng vault operator raft snapshot save (docker exec), rồi proxmox-backup-client backup vault-snapshots.pxar và vault-config.pxar vào datastore syno-primary, namespace vm-vault (token vm-backup@pbs!vault).

Khôi phục từ snapshot (đã unseal, token có quyền ghi sys/storage/raft/snapshot, file .snap nằm trong /opt/vault/snapshots; lấy lại từ PBS bằng proxmox-backup-client restore nếu cần):

vault operator raft snapshot restore -force /vault/snapshots/vault-YYYYMMDD-HHMM.snap

Snapshot chứa cả dữ liệu mã hóa lẫn keyring: khi khôi phục sang cụm khác (hoặc VM dựng lại), sau restore phải unseal bằng unseal keys của cụm gốc. Hãy thử khôi phục vào một VM thử trước khi cần đến (cần kiểm lại trên máy thật).

06

Kiểm tra & Xác minh

# 0. Container và TLS
cd /opt/vault && docker compose ps
curl -s --cacert /opt/vault/tls/root_ca.crt https://vault.hoatranlabs.local:8200/v1/sys/health | jq    # initialized/sealed/version

# 1. Status cơ bản
vault status

# 2. Test KV secret
vault kv put secret/test/ping value="pong-$(date +%s)"
vault kv get secret/test/ping

# 3. Test PKI cấp cert
vault write pki/issue/hoatranlabs-dot-local \
  common_name="test.hoatranlabs.local" \
  ttl=1h | jq '.data.certificate'

# 4. Test AppRole login
vault write auth/approle/login \
  role_id="$ROLE_ID" secret_id="$SECRET_ID" | jq '.auth.client_token'

# 5. Test database dynamic creds
vault read database/creds/app-readonly

# 6. Web UI
echo "Truy cập: https://vault.hoatranlabs.local:8200/ui"

# 7. Raft cluster health
vault operator raft list-peers

# 8. Audit log đang ghi (mỗi dòng là một JSON; xem 3 sự kiện cuối)
tail -n 3 /opt/vault/logs/audit.log | jq -r '[.time, .type, .request.path] | @tsv'
Terminal: kết quả docker compose ps, curl /v1/sys/health, vault status, kv get secret/test/ping (pong-...), approle login và operator raft list-peers đều thành công.
Terminal: kết quả docker compose ps, curl /v1/sys/health, vault status, kv get secret/test/ping (pong-...), approle login và operator raft list-peers đều thành công.
07

Nâng cấp phiên bản Vault

Vì sao 2.2.0 (và 2.1.2 là bản dự phòng) · Thay đổi từ 1.17 tới 2.2 ảnh hưởng tới bài này · Quy trình nâng cấp image

7.1 Vì sao 2.2.0 (và 2.1.2 là bản dự phòng)

  • Vault 1.17.6 (bản cũ của bài) đã hết hỗ trợ và thiếu các bản vá bảo mật sau 09/2024 (ví dụ giới hạn RSA 8192 bit CVE-2026-39829, sửa các lỗi bypass ACL ở 2.0.x và 2.1.x).
  • Dòng 1.x không còn bản Community mới: Community 1.x kết thúc ở 1.21.4 (03/2026). Từ 1.21.5 (04/2026) mọi bản 1.x chỉ còn là Enterprise: releases.hashicorp.com/vault/1.21.5/ không có zip Community (HTTP 404), Docker Hub và kho APT noble của HashiCorp dừng ở 1.21.4. Vì vậy bản "còn được vá" duy nhất cho Community là dòng 2.x. Trang docs của HashiCorp ghi mỗi major là một vòng đời hỗ trợ mới, "phải cập nhật lên bản fix mới nhất trong major" và "không backport qua các minor"; chính sách chi tiết cho Community không được công bố rõ trên docs (đã tìm), phần này suy ra từ lịch sử phát hành.
  • Chọn 2.2.0 (GA 2026-10-15, image latest hiện tại) vì sau khi 2.2 ra mắt, các bản vá Community tiếp theo sẽ nằm ở 2.2.x (dòng 2.0 dừng ở 2.0.4 ngày 2026-08-04, ngay trước khi 2.1.0 ra mắt; 2.1.x nhiều khả năng dừng ở 2.1.2 ngày 2026-10-07). Change tracker 2.x hiện chỉ liệt kê cho 2.2.0 hai known issue của Enterprise (Azure static credentials, Transit datakey) và một thay đổi thứ tự ưu tiên credential của AWS auth/secrets engine, không ảnh hưởng bài này.
  • Rủi ro của 2.2.0: mới phát hành một ngày, chưa có bản vá .1. Nếu muốn chờ, thay 2.2.0 bằng 2.1.2 (bản vá bảo mật ngày 2026-10-07; image đã kiểm cùng cấu trúc: user vault, không file capability) ở mục 2.1 và 2.4. Toàn bộ cấu hình trong bài dùng được cho cả hai tag. Ghi chú thêm: tài liệu HashiCorp chưa có trang riêng cho 2.2 tại thời điểm viết; nội dung thay đổi của 2.2.0 lấy từ CHANGELOG 2.2.0-rc1 và change tracker 2.x (cần kiểm lại khi đọc release notes chính thức).

7.2 Thay đổi từ 1.17 tới 2.2 ảnh hưởng tới bài này

Đọc từ change tracker, release notes và CHANGELOG của Vault (đường dẫn ở mục "Tài liệu tham khảo"):

Từ bảnThay đổiẢnh hưởng và cách xử lý trong bài
1.17.0Đăng nhập JWT/OIDC đòi role có bound_audiencesRole oidc-default đã đặt bound_audiences (mục 4.3)
1.17.0PKI sign-intermediate cắt notAfter theo hạn của issuer kýBài chỉ tạo root nội bộ và dùng pki/issue, không ký intermediate
1.18.0Image Docker không còn curlHealthcheck dùng vault status (mục 2.4)
1.18.12, 1.19.7, 1.20.1 (CVE-2025-6000)File audit device không được có quyền thực thimode mặc định 0600 (mục 3.4)
1.20.0Integrated storage đòi khai báo disable_mlockdisable_mlock = true (mục 2.3)
1.20.0Role Kubernetes auth không có audience bị cảnh báoChỉ là cảnh báo (mục 4.4)
1.21.0allowed_parameters / denied_parameters so sánh từng phần tửPolicy của bài không dùng hai tham số này
2.0.0sys/rekey, sys/generate-root đòi thêm token hợp lệ (trước chỉ cần key fragments); đường dẫn request phải chuẩn hóa (không //, /./, /../); listener có max_token_header_size mặc định 8 KBĐường dẫn API trong bài đều sạch; token Vault ngắn; JWT của OIDC đi trong body, không qua header
2.0.1Wildcard/glob trong đường dẫn policy dạng template bị từ chốiBài không dùng policy template
2.0.2Image chạy user vault, bỏ yêu cầu IPC_LOCK; HashiCorp khuyến nghị disable_mlock = true cùng swap tắt/mã hóa; giới hạn RSA 8192 bitCompose không có cap_add; swap tắt ở mục 1.4
2.1.2Tên policy chứa đoạn . hoặc .. bị từ chối; ACL path theo tên role/policy được khớp ở dạng chữ thường; ACME mặc định từ chối CSR có URI/email SANTên policy/role trong bài đều là chữ thường; bài không dùng ACME
2.2.0Image bỏ cap_ipc_lock khi build (CHANGELOG 2.2.0-rc1)Đã đặt disable_mlock = true

Nếu VM269 đã chạy bản cũ 1.17.6 (binary): HashiCorp cho phép nâng nhảy phiên bản nhưng yêu cầu đọc ghi chú của từng bản đi qua; dữ liệu Raft không đọc ngược được. Cách an toàn: snapshot Raft trên bản cũ, dựng container 2.2.0 mới theo bài, vault operator init rồi snapshot restore -force và unseal bằng unseal keys của cụm cũ (cần kiểm lại trên máy thật).

7.3 Quy trình nâng cấp image

cd /opt/vault
# 1. Snapshot Raft + đẩy lên PBS (mục 5.4), rồi ghi lại phiên bản hiện tại
systemctl start vault-backup.service && journalctl -u vault-backup.service -n 5 --no-pager
vault version

# 2. Đọc change tracker và release notes của bản đích; thử trước trên VM khác với bản snapshot (cách ly mạng)

# 3. Đổi tag image (ví dụ minh họa: lên bản vá 2.2.1 khi có), kéo image mới và tạo lại container
sed -i 's|image: hashicorp/vault:.*|image: hashicorp/vault:2.2.1|' docker-compose.yml
docker compose config -q && docker compose pull
docker compose up -d            # container mới khởi động ở trạng thái sealed; dữ liệu ở /opt/vault/data giữ nguyên

# 4. Unseal (mục 3.2 hoặc script lab) và kiểm tra
vault operator unseal           # 3 lần
vault status                    # Version đúng bản mới, Sealed false
docker compose ps               # healthy

Cụm một node có thời gian gián đoạn bằng thời gian khởi động lại và unseal. Nếu sau này có nhiều node Raft thì nâng cấp node standby trước, node active sau (tài liệu HashiCorp "Manual upgrade for HA deployments").

Quay lại bản cũ: HashiCorp ghi rõ Vault không đảm bảo tương thích ngược của kho dữ liệu, nên chỉ đặt lại tag cũ là chưa đủ nếu bản mới đã ghi dữ liệu. Quy trình: docker compose down, dời /opt/vault/data sang chỗ khác và tạo lại thư mục rỗng (chown 100:1000, chmod 700), đặt lại tag cũ, docker compose up -d, vault operator init (cụm tạm), vault operator raft snapshot restore -force bằng snapshot trước nâng cấp, rồi unseal bằng unseal keys của cụm gốc (cần kiểm lại trên máy thật).

08

Troubleshooting

Vấn đềNguyên nhânGiải pháp
Error checking seal status: connection refusedContainer chưa chạy hoặc đang restart, hoặc cổng bị chặndocker compose ps, docker compose logs --tail=50 vault; kiểm FortiGate và chuỗi DOCKER-USER (mục 2.7)
Container Restarting, log có Failed to lock memory hoặc mlockCấu hình không đặt disable_mlock = trueĐặt disable_mlock = true trong /etc/vault.d/vault.hcl rồi docker compose restart vault
Log báo invalid key ... on line N khi khởi độngHCL có khóa sai chỗ (ví dụ unauthenticated_metrics_access ngoài listener)Sửa theo mục 2.3 rồi docker compose restart vault
permission denied mở /vault/file hoặc /vault/tls/vault.keyThư mục/file host không thuộc 100:1000chown 100:1000 và chmod theo mục 2.1, 2.2
Vault is sealed sau rebootChưa unseal (hoặc script lab chưa chạy)vault operator unseal 3 lần, hoặc systemctl start vault-unseal
tls: certificate signed by unknown authority ở clientClient chưa trust root CAThêm root CA vào /etc/ssl/certs/, update-ca-certificates; trong container dùng VAULT_CACERT
x509 khi cấu hình auth/oidc/configContainer không tin step-CAThêm oidc_discovery_ca_pem=@/vault/tls/root_ca.crt (mục 4.3)
permission denied khi đọc secretToken không có policyvault token lookup, kiểm tra policies
500 Internal Server Error trên RaftRaft data directory bị lỗivault operator raft autopilot state
OIDC callback failedRedirect URI không đúngKiểm tra URL trong Authentik provider (kiểu Strict) và allowed_redirect_uris
Lệnh vault báo Error ... missing client tokenShell mới chưa có VAULT_TOKEN hoặc chưa nạp hàm. /etc/profile.d/vault-docker.sh và export VAULT_TOKEN=...
Prometheus báo 403 ở job vaultListener thiếu unauthenticated_metrics_access = true (đặt trong khối telemetry của listener)Sửa mục 2.3, restart container
Cổng 8200 vẫn truy cập được từ VLAN không cho phépDocker publish cổng bỏ qua ufwLọc ở FortiGate và/hoặc DOCKER-USER (mục 2.7)
Log audit không còn ghi, mọi request lỗiĐĩa đầy hoặc sai quyền /opt/vault/logsGiải phóng đĩa, chown 100:1000 /opt/vault/logs, docker kill --signal=HUP vault

Checklist triển khai

  • VM269 tạo thành công, IP 10.11.25.10, VLAN 25
  • Swap disabled (free -h không còn swap)
  • Docker Engine từ repo download.docker.com (suite noble) + Compose plugin (docker --version, docker compose version); systemctl is-enabled docker báo enabled
  • TLS cert từ step-CA cho vault.hoatranlabs.local (SAN gồm FQDN, IP, 127.0.0.1, localhost); renew-cert-vault.timer đã bật
  • Container vault chạy ổn định (docker compose ps báo Up ... (healthy)), image ghim hashicorp/vault:2.2.0, restart: unless-stopped, giới hạn log json-file 10m x 5
  • Cổng 8200/8201 được lọc nguồn ở FortiGate (và DOCKER-USER nếu dùng); không dựa vào ufw
  • Vault initialized — unseal keys lưu an toàn (5 keys → 5 người, cần 3 trong 5)
  • Vault unsealed (Sealed: false)
  • Audit device file bật ở /vault/logs/audit.log, có logrotate với SIGHUP
  • KV v2 secret engine bật tại secret/
  • AppRole auth enable, Role ID/Secret ID cho Gitea CI lưu vào Gitea Secrets
  • OIDC auth enable, kết nối Authentik (có oidc_discovery_ca_pem)
  • Kubernetes auth enable cho K3s
  • DNS record vault.hoatranlabs.local → 10.11.25.10
  • Prometheus scrape vault metrics thành công
  • Web UI https://vault.hoatranlabs.local:8200/ui accessible
  • vault-backup.timer chạy: snapshot Raft trong /opt/vault/snapshots và backup PBS thành công

Phụ lục — Phương án thay thế: binary + systemd (không Docker)

Dùng khi không muốn chạy Docker trên VM269 hoặc khi đặt Vault trong LXC không đặc quyền (CTID 269, Docker không chạy trong LXC). Dùng chung thư mục host /etc/vault.d, /opt/vault/{tls,data,logs,snapshots}, nên các mục 5.1–5.4 và backup PBS không đổi nội dung; khác nhau ở các điểm dưới đây.

# Cài Vault binary (chọn MỘT trong hai cách)
# a) zip từ releases.hashicorp.com (ghim phiên bản; sha256 zip 2.2.0 linux_amd64 đã kiểm 2026-10-16:
#    05d78b0ac842ca7c522fc297df91527cd43c15420c4c5c0a969d48a7b0ff7b6d)
apt install -y unzip
VAULT_VERSION="2.2.0"
cd /tmp
wget "https://releases.hashicorp.com/vault/${VAULT_VERSION}/vault_${VAULT_VERSION}_linux_amd64.zip"
wget "https://releases.hashicorp.com/vault/${VAULT_VERSION}/vault_${VAULT_VERSION}_SHA256SUMS"
sha256sum -c vault_${VAULT_VERSION}_SHA256SUMS --ignore-missing
unzip vault_${VAULT_VERSION}_linux_amd64.zip
install -m 0755 vault /usr/local/bin/vault
vault version
# b) APT HashiCorp: apt.releases.hashicorp.com có suite noble với vault 2.2.0-1 (đã kiểm Packages.gz 2026-10-16); khi đó
#    dùng nguồn deb822 có Signed-By, gói tự tạo user vault, /etc/vault.d, vault.service nên bỏ các bước tương ứng bên dưới

# User hệ thống, thư mục (đổi quyền sang user vault trên host thay cho uid 100)
useradd --system --home /etc/vault.d --shell /bin/false vault
mkdir -p /etc/vault.d /opt/vault/{tls,data,logs,snapshots}
chown -R vault:vault /opt/vault /etc/vault.d
chmod 750 /opt/vault/data
# Cert/khóa step-CA (mục 2.2) lưu ở /opt/vault/tls; chown vault:vault cho vault.key

File /etc/vault.d/vault.hcl giữ nội dung mục 2.3 nhưng đổi đường dẫn sang đường dẫn host và có thể ghi log ra file:

sed -i -e 's|/vault/file|/opt/vault/data|' -e 's|/vault/tls|/opt/vault/tls|g' /etc/vault.d/vault.hcl
# Thêm vào đầu file nếu muốn log ra file thay vì journald:
#   log_file = "/opt/vault/logs/vault.log"
#   log_rotate_duration = "24h"
#   log_rotate_max_files = 7

cat > /etc/systemd/system/vault.service << 'EOF'
[Unit]
Description=HashiCorp Vault - Secrets Management
Documentation=https://developer.hashicorp.com/vault/docs
Requires=network-online.target
After=network-online.target
ConditionFileNotEmpty=/etc/vault.d/vault.hcl
StartLimitIntervalSec=60
StartLimitBurst=3

[Service]
Type=notify
User=vault
Group=vault
ProtectSystem=full
ProtectHome=read-only
PrivateTmp=yes
PrivateDevices=yes
NoNewPrivileges=yes
ExecStart=/usr/local/bin/vault server -config=/etc/vault.d/vault.hcl
ExecReload=/bin/kill --signal HUP $MAINPID
KillMode=process
KillSignal=SIGINT
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now vault
export VAULT_ADDR="https://vault.hoatranlabs.local:8200"
export VAULT_CACERT="/opt/vault/tls/root_ca.crt"
vault status

Khác biệt so với phương án Docker:

  • Lệnh vault là binary thật (không qua docker exec): policy/cert đọc trực tiếp file trên host, ví dụ kubernetes_ca_cert=@/tmp/k3s-ca.crt; oidc_discovery_ca_pem=@/opt/vault/tls/root_ca.crt.
  • Unseal tự động (mục 3.3): đổi After=docker.service thành After=vault.service, thay docker exec vault vault ... bằng vault .... Nạp lại cert: systemctl reload vault (SIGHUP) thay cho docker kill. Audit rotate: systemctl kill -s HUP vault.
  • Không còn khối cap_* / healthcheck; disable_mlock = true giữ nguyên (đã bỏ setcap, AmbientCapabilities, LimitMEMLOCK vì Raft khuyến nghị tắt mlock). Muốn khóa bộ nhớ thật sự: đặt disable_mlock = false, setcap cap_ipc_lock=+ep /usr/local/bin/vault và thêm AmbientCapabilities=CAP_IPC_LOCK, LimitMEMLOCK=infinity vào unit (cần kiểm lại trên máy thật).
  • Chuyển Docker ↔ binary: snapshot Raft (mục 5.4), dừng bên cũ, dựng bên mới, vault operator init rồi vault operator raft snapshot restore -force, unseal bằng unseal keys của cụm gốc.
  • LXC không đặc quyền: tạo CT Ubuntu 24.04 theo bài 07 mục 11 (CTID 269, rootfs trên vm-ceph), cài binary như trên; swap của CT là swap của node nên mlock/swap cần kiểm lại trên máy thật.

Phương án 2 — OpenBao (MPL 2.0, Miễn phí hoàn toàn)

So sánh OpenBao vs HashiCorp Vault · Chạy OpenBao thay Vault (Docker)

OpenBao là community fork của HashiCorp Vault, được tạo ra ngay sau khi Vault đổi sang BSL (tách từ Vault 1.14, bản MPL cuối cùng). License Mozilla Public License 2.0 (MPL 2.0) — hoàn toàn open-source, được OSI công nhận, không có ràng buộc thương mại. Release notes 2.0.0 của OpenBao ghi tương thích API với Vault 1.14.9; mức tương thích với Vault 2.x không được đảm bảo (hai dự án phát triển độc lập), nên hãy thử các tích hợp của bạn trước khi dùng.
- GitHub: https://github.com/openbao/openbao - Docs: https://openbao.org/docs/ - Phiên bản: 2.7.1 (ngày 2026-10-01)

So sánh OpenBao vs HashiCorp Vault

Tiêu chíHashiCorp VaultOpenBao
LicenseBSL 1.1 (không OSI)MPL 2.0 (OSI, hoàn toàn free)
API compatibility—Tương thích API Vault 1.14.x; với Vault 2.x cần tự kiểm tra
Cộng đồngHashiCorp/IBMDự án cộng đồng thuộc Linux Foundation (hiện dưới OpenSSF theo nguồn thứ cấp, cần kiểm lại)
Enterprise featuresCó bản trả phíKhông có bản trả phí của hãng; một số tính năng tương đương được phát triển riêng
Phù hợp nội bộ✅ Miễn phí✅ Miễn phí
Phù hợp SaaS/resell❌ Cần license✅ Không ràng buộc

Chạy OpenBao thay Vault (Docker)

Mục 1 (tạo VM, cài Docker), mục 2.1–2.3, 2.5–2.7 và mục 3–5 giữ nguyên ý nghĩa; chỉ đổi các điểm sau. Image openbao/openbao:2.7.1 đã kiểm trên Docker Hub (2026-10-16): USER openbao, cổng 8200, entrypoint đọc cấu hình ở /openbao/config, dữ liệu /openbao/file, audit /openbao/logs, biến môi trường BAO_*, lệnh bao. Chạy thật cần kiểm lại trên máy thật.

Hạng mụcHashiCorp VaultOpenBao
image trong composehashicorp/vault:2.2.0openbao/openbao:2.7.1
Đích bind mount/vault/config, /vault/file, /vault/logs, /vault/tls, /vault/snapshots/openbao/config, /openbao/file, /openbao/logs, /openbao/tls, /openbao/snapshots
Đường dẫn trong vault.hcl/vault/file, /vault/tls/.../openbao/file, /openbao/tls/...
Biến môi trườngVAULT_ADDR, VAULT_CACERTBAO_ADDR, BAO_CACERT
Lệnh CLIvaultbao
user: trong compose100:1000uid:gid của user openbao (xem docker run --rm --entrypoint id openbao/openbao:2.7.1 openbao), chown các thư mục theo đó

Hàm trên host trỏ vào container (giữ tên container vault để các script ở mục 2.6, 3.3, 5.4 không phải sửa):

cat > /etc/profile.d/vault-docker.sh << 'EOF'
# Container tên "vault" nhưng chạy OpenBao: gọi lệnh bao; BAO_TOKEN lấy từ shell trên host
bao() { docker exec $([ -t 0 ] && [ -t 1 ] && echo -t) -i -e BAO_TOKEN vault bao "$@"; }
vault() { bao "$@"; }
EOF
. /etc/profile.d/vault-docker.sh

# Khởi tạo và unseal (3 trong 5 keys), kiểm tra
bao operator init -key-shares=5 -key-threshold=3
bao operator unseal
bao status

Trong các script mục 2.6, 3.3, 5.4, thay docker exec ... vault vault ... bằng docker exec ... vault bao ... và VAULT_TOKEN bằng BAO_TOKEN.

Tích hợp với Gitea CI, K3s external-secrets, Authentik OIDC và Prometheus metrics về nguyên tắc giữ nguyên vì OpenBao giữ API kiểu Vault; các tham số mới của Vault 2.x (ví dụ những mục ở bảng 7.2 từ 2.0 trở đi) có thể khác hoặc chưa có trong OpenBao. Bản chạy binary của OpenBao (không Docker) làm theo "Phụ lục" với các file tương ứng (openbao_<phiên bản>_linux_amd64.tar.gz trên GitHub Releases, lệnh bao).

Tài liệu tham khảo

Cập nhật: 2026-10-16 (Docker Compose, Vault 2.2.0, Ubuntu Server 24.04 LTS)

Zalo