HashiCorp Vault Secrets Management
Machine-to-machine secrets cho CI/CD — AppRole, K8s auth, dynamic credentials.
Bối cảnh & Lý do triển khai
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ục | Nội dung |
|---|---|
| Ứng dụng trong doanh nghiệp | Secrets cho Gitea CI, K3s pods, database dynamic creds, SSH cert signing |
| Tác dụng chính | Zero-trust secrets: rotate tập trung, audit log toàn bộ, TTL-based leases |
| Nếu không triển khai | Secrets hardcoded trong config/repo, không có audit trail, rotation thủ công |
| Các service phụ thuộc vào đây | Gitea 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 án | Trạng thái trong bài | Lý do chọn / không chọn | Cách chuyển đổi |
|---|---|---|---|
Docker Compose trên VM269 (image hashicorp/vault) | Khuyến nghị — mục 1–8 | HashiCorp 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ên | Từ 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ài | Docker 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ật | CTID = 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 + systemd | Phươ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 tay | Dừ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 capabilitycap_ipc_lock, nên bài đặtdisable_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(quasudo) quản trị VM này, không thêm user khác vào nhómdocker; ai vào đượcdocker exec vaultcùngVAULT_TOKENlà 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ỗiDOCKER-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ủ | IP | VLAN · Node | Vai trò trong bài này |
|---|---|---|---|
| vault (HashiCorp Vault) · VM269 | 10.11.25.10 | 25 (SEC) · node1 | Má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.210 | 45 (MGMT) · cluster HOATRANHUB | Node 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) · VM247 | 10.11.45.53 | 45 (MGMT) · node3 | Là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) · VM242 | 10.11.25.42 | 25 (SEC) · node1 | Cấ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) · VM234 | 10.11.25.40 | 25 (SEC) · node1 | Nhà 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) · VM240 | 10.11.45.40 | 45 (MGMT) · node2 | Pipeline 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.55 | 65 (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) · VM235 | 10.11.45.35 | 45 (MGMT) · node2 | Scrape 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) · VM101 | 10.11.45.17 | 45 (MGMT) · node4 | Nhậ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.16 | 45 (MGMT) · NAS | NAS 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ị |
|---|---|
| VMID | 269 |
| Hostname | vault |
| IP | 10.11.25.10/24 |
| Gateway | 10.11.25.1 |
| VLAN | 25 (VLAN_SEC) |
| vCPU | 2 |
| RAM | 4 GB |
| Disk | 20 GB (scsi0, SSD vm-ceph) |
| OS | Ubuntu Server 24.04 LTS |
| Phân bổ node | node1 |
| Triển khai | Docker Compose, image hashicorp/vault:2.2.0 |
| Cổng | 8200/TCP (API + Web UI, HTTPS), 8201/TCP (cluster Raft) |
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ần | Phiên bản | Ghi chú |
|---|---|---|
| Hệ điều hành | Ubuntu 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 Engine | 29.9.1 (docker-ce 5:29.9.1-1~ubuntu.24.04~noble) | Repo chính thức download.docker.com/linux/ubuntu noble stable, 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 / Buildx | 5.6.0 / 0.38.0 | Lệ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ùng | 1.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-cli | 0.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-client | proxmox-backup-client-static 4.x, repo pbs-client suite trixie | Bả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). |
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)
- VM ID:
269 - Name:
vault - Bỏ tick Start after created
- 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
- Machine:
q35 - SCSI Controller:
VirtIO SCSI single - BIOS:
SeaBIOS - Qemu Agent: ☑
- Bus/Device:
SCSI 0, Storage:vm-ceph - Disk size:
20 GiB, Cache:Write back, Discard: ☑
- Sockets:
1, Cores:2, Type:x86-64-v2-AES
- Memory (MiB):
4096
- Bridge:
vmbr0, VLAN Tag:25, Model:VirtIO (paravirtualized), Firewall: ☐
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, hostnamevault - 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
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ầuIPC_LOCKkhỏi image và khuyến nghịdisable_mlock = truecùng swap tắt hoặc mã hóa. -
cluster_addresslà tham số củalistener "tcp";cluster_addrvàapi_addrlà tham số cấp trên cùng. Bản cũ ghicluster_addrtrong listener nên không có tác dụng. -
unauthenticated_metrics_accesschỉ hợp lệ trong khốitelemetrybên trong listener; đặt ở khốitelemetrycấp trên cùng (như bản cũ) là sai chỗ. - Bỏ
retry_jointrỏ về chính node: cụm một node không cần, và trong container, tênvault.hoatranlabs.localtrỏ 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:
-
imageghim tag: tag2.2.0đã được kiểm trên Docker Hub (cập nhật 2026-10-15). Không dùnglatest/2.2vì mỗi lầnpullcó 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/vaultvà image chạy sẵn bằng uservault, nên thêmIPC_LOCKcho 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ọndisable_mlock = truevà swap tắt. -
cap_drop: ALLvà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_locktrên binary,no-new-privilegeslàm container không khởi động được. Nếu container báooperation not permitted, bỏ hai khối này rồidocker compose up -d(cần kiểm lại trên máy thật). - Bind mount
:rocho cấu hình và TLS: Vault chỉ đọc; thư mục ghi được chỉ gồm dữ liệu, log và snapshot. -
healthcheckdùngvault statusvì image từ 1.18 không còncurl. Ký hiệu$$?là cách viết$?trong Compose (một dấu$đơn bị Compose coi là biến). -
logging:json-filevớimax-size/max-fileđể log không phình ra đĩa; Alloy (bài 33, khốiloki.source.dockernhãnjob="docker-containers") đọc log container qua Docker API nên thu được log của containervaultnếu bạn cài Alloy trên VM269. -
dnstrỏ Pi-hole: container không đọc/etc/hostscủa host nên cần DNS để gọiauthentik.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)"
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)
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.10bị chặn ở ranh giới VLAN.
| Nguồn | Đích | Cổng | Mục đích |
|---|---|---|---|
prometheus 10.11.45.35 | VM269 10.11.25.10 | 8200/TCP | Scrape /v1/sys/metrics |
gitea 10.11.45.40 (và job runner) | VM269 10.11.25.10 | 8200/TCP | AppRole gitea-ci lấy secret |
| Máy quản trị VLAN 45 | VM269 10.11.25.10 | 8200/TCP | Web UI / API |
VM269 10.11.25.10 | K3s API VIP 10.11.65.55 | 6443/TCP | Kubernetes auth (TokenReview) |
VM269 10.11.25.10 | pbs01 10.11.45.17, pihole 10.11.45.53 | 8007/TCP, 53/UDP+TCP | Backup PBS, DNS |
- Chuỗi
DOCKER-USERtrên VM269 (tùy chọn, thêm một lớp): luật trongDOCKER-USERđược xét sau DNAT nên phải khớp bằngconntrack --ctorigdstport(cổng gốc client gọi tới). Script idempotent dưới đây giới hạn 8200 cho dải10.11.0.0/16và 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
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.
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
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
/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.
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
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
4.3 OIDC Auth (Authentik SSO)
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.
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
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).
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.
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
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).
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'
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 APTnoblecủ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
latesthiệ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ờ, thay2.2.0bằng2.1.2(bản vá bảo mật ngày 2026-10-07; image đã kiểm cùng cấu trúc: uservault, 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ừ CHANGELOG2.2.0-rc1và 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ản | Thay đổi | Ảnh hưởng và cách xử lý trong bài |
|---|---|---|
| 1.17.0 | Đăng nhập JWT/OIDC đòi role có bound_audiences | Role oidc-default đã đặt bound_audiences (mục 4.3) |
| 1.17.0 | PKI 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.0 | Image Docker không còn curl | Healthcheck 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 thi | mode mặc định 0600 (mục 3.4) |
| 1.20.0 | Integrated storage đòi khai báo disable_mlock | disable_mlock = true (mục 2.3) |
| 1.20.0 | Role Kubernetes auth không có audience bị cảnh báo | Chỉ là cảnh báo (mục 4.4) |
| 1.21.0 | allowed_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.0 | sys/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.1 | Wildcard/glob trong đường dẫn policy dạng template bị từ chối | Bài không dùng policy template |
| 2.0.2 | Image 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 bit | Compose không có cap_add; swap tắt ở mục 1.4 |
| 2.1.2 | Tê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 SAN | Tên policy/role trong bài đều là chữ thường; bài không dùng ACME |
| 2.2.0 | Image 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).
Troubleshooting
| Vấn đề | Nguyên nhân | Giải pháp |
|---|---|---|
Error checking seal status: connection refused | Container chưa chạy hoặc đang restart, hoặc cổng bị chặn | docker 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 mlock | Cấ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 động | HCL 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.key | Thư mục/file host không thuộc 100:1000 | chown 100:1000 và chmod theo mục 2.1, 2.2 |
Vault is sealed sau reboot | Chư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 ở client | Client chưa trust root CA | Thê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/config | Container không tin step-CA | Thêm oidc_discovery_ca_pem=@/vault/tls/root_ca.crt (mục 4.3) |
permission denied khi đọc secret | Token không có policy | vault token lookup, kiểm tra policies |
500 Internal Server Error trên Raft | Raft data directory bị lỗi | vault operator raft autopilot state |
| OIDC callback failed | Redirect URI không đúng | Kiểm tra URL trong Authentik provider (kiểu Strict) và allowed_redirect_uris |
Lệnh vault báo Error ... missing client token | Shell 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 vault | Listener 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ép | Docker publish cổng bỏ qua ufw | Lọ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/logs | Giả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 -hkhông còn swap) - Docker Engine từ repo
download.docker.com(suite noble) + Compose plugin (docker --version,docker compose version);systemctl is-enabled dockerbáoenabled - 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
vaultchạy ổn định (docker compose psbáoUp ... (healthy)), image ghimhashicorp/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-USERnếu dùng); không dựa vàoufw - 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
filebật ở/vault/logs/audit.log, có logrotate vớiSIGHUP - 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.timerchạy: snapshot Raft trong/opt/vault/snapshotsvà 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
vaultlà binary thật (không quadocker 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.servicethànhAfter=vault.service, thaydocker exec vault vault ...bằngvault .... Nạp lại cert:systemctl reload vault(SIGHUP) thay chodocker kill. Audit rotate:systemctl kill -s HUP vault. - Không còn khối
cap_*/healthcheck;disable_mlock = truegiữ nguyên (đã bỏsetcap,AmbientCapabilities,LimitMEMLOCKvì Raft khuyến nghị tắt mlock). Muốn khóa bộ nhớ thật sự: đặtdisable_mlock = false,setcap cap_ipc_lock=+ep /usr/local/bin/vaultvà thêmAmbientCapabilities=CAP_IPC_LOCK,LimitMEMLOCK=infinityvà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 initrồivault 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ênmlock/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)
So sánh OpenBao vs HashiCorp Vault
| Tiêu chí | HashiCorp Vault | OpenBao |
|---|---|---|
| License | BSL 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 đồng | HashiCorp/IBM | Dự á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 features | Có 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ục | HashiCorp Vault | OpenBao |
|---|---|---|
image trong compose | hashicorp/vault:2.2.0 | openbao/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ường | VAULT_ADDR, VAULT_CACERT | BAO_ADDR, BAO_CACERT |
| Lệnh CLI | vault | bao |
user: trong compose | 100:1000 | uid: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.
openbao_<phiên bản>_linux_amd64.tar.gz trên GitHub Releases, lệnh bao).
Tài liệu tham khảo
- Vault — release notes: https://developer.hashicorp.com/vault/docs/updates/release-notes ; change tracker 2.x: https://developer.hashicorp.com/vault/docs/v2.x/updates/change-tracker ; important changes 2.x: https://developer.hashicorp.com/vault/docs/v2.x/updates/important-changes
- Vault — nâng cấp: https://developer.hashicorp.com/vault/docs/upgrade ; CHANGELOG: https://github.com/hashicorp/vault/blob/main/CHANGELOG.md
- Vault — cấu hình: https://developer.hashicorp.com/vault/docs/configuration ; Raft: https://developer.hashicorp.com/vault/docs/configuration/storage/raft ; listener TCP: https://developer.hashicorp.com/vault/docs/configuration/listener/tcp ; file audit device: https://developer.hashicorp.com/vault/docs/audit/file
- Vault — API PKI: https://developer.hashicorp.com/vault/api-docs/secret/pki ; Kubernetes auth: https://developer.hashicorp.com/vault/api-docs/auth/kubernetes
- Image: https://hub.docker.com/r/hashicorp/vault ; Dockerfile và entrypoint: https://github.com/hashicorp/vault/blob/main/Dockerfile ; bản phát hành: https://releases.hashicorp.com/vault/
- Authentik — tích hợp Vault: https://integrations.goauthentik.io/security/hashicorp-vault/
- Docker — packet filtering và firewall (cổng publish bỏ qua
ufw, chuỗiDOCKER-USER): https://docs.docker.com/engine/network/packet-filtering-firewalls/ - OpenBao: https://openbao.org/docs/ ; https://github.com/openbao/openbao/releases
Cập nhật: 2026-10-16 (Docker Compose, Vault 2.2.0, Ubuntu Server 24.04 LTS)