Sổ tay kỹ thuật

HashiCorp Vault cơ bản – KV v2, policy, AppRole, vault CLI

how-to#vault#secrets#security· cập nhật 2026-11-06

Dùng khi cần lưu credential thiết bị/DB trong Vault, cấp quyền đọc theo path cho người và cho automation (Ansible, CI) qua AppRole.

Sửa trang này
Mục lục

Tóm tắt: Bật secrets engine KV v2 (vault secrets enable -path=secret kv-v2), ghi/đọc bằng vault kv put/get -mount=secret. Viết policy HCL cấp quyền theo path (với KV v2 path API có data/ và metadata/). Automation đăng nhập bằng AppRole (role_id + secret_id) để nhận token ngắn hạn gắn policy. So sánh Vault với SOPS/ansible-vault xem Quản lý secret. Lệnh dưới cũng chạy với OpenBao (thay vault bằng bao).

Luồng hoạt động

flowchart LR
  A["Ansible / CI"] -->|"role_id + secret_id"| B["auth/approle/login"]
  B -->|"token (TTL 1h, policy netops-ro)"| A
  A -->|"GET secret/data/netops/router"| C["KV v2"]
  C --> D{"Policy cho phép?"}
  D -->|có| E["Trả secret"]
  D -->|không| F["403 permission denied"]

Lệnh

Kết nối

export VAULT_ADDR=https://vault.example.com:8200
export VAULT_CACERT=/etc/ssl/certs/internal-ca.pem   # CA nội bộ ký cert của Vault
vault status                       # Sealed: false là OK
vault login -method=oidc           # hoặc -method=userpass username=alice
vault token lookup                 # policy, TTL của token hiện tại

Lab nhanh: vault server -dev (in-memory, tự unseal, root token in ra màn hình). Chỉ dùng để thử lệnh, không lưu dữ liệu thật.

KV v2

vault secrets enable -path=secret kv-v2
vault secrets list -detailed                     # cột Options có version:2
 
# Ghi: "-" đọc giá trị từ stdin, tránh lộ trong history/ps
printf '%s' "$ROUTER_PASS" | vault kv put -mount=secret netops/router username=automation password=-
vault kv get -mount=secret netops/router
vault kv get -mount=secret -field=password netops/router
vault kv get -mount=secret -format=json netops/router | jq .data.data
vault kv patch -mount=secret netops/router enable_secret=-   # sửa 1 key, giữ key khác
vault kv list -mount=secret netops
Mục đích Lệnh
Xem lịch sử version vault kv metadata get -mount=secret netops/router
Đọc version cũ vault kv get -mount=secret -version=2 netops/router
Quay về version cũ (tạo version mới) vault kv rollback -mount=secret -version=2 netops/router
Xoá mềm version mới nhất / khôi phục vault kv delete ... / vault kv undelete -versions=3 ...
Xoá vĩnh viễn một version vault kv destroy -mount=secret -versions=3 netops/router
Xoá toàn bộ secret và lịch sử vault kv metadata delete -mount=secret netops/router
Giới hạn số version giữ lại vault kv metadata put -mount=secret -max-versions=10 netops/router

Policy

KV v2 dùng path API secret/data/... (đọc/ghi) và secret/metadata/... (list, lịch sử). CLI vault kv tự thêm data/, policy thì phải viết rõ.

netops-ro.hcl
path "secret/data/netops/*" {
  capabilities = ["read"]
}
path "secret/metadata/netops/*" {
  capabilities = ["list"]
}
vault policy write netops-ro netops-ro.hcl
vault policy read netops-ro
vault token capabilities secret/data/netops/router   # kiểm tra token hiện tại có quyền gì

AppRole cho automation

vault auth enable approle
vault write auth/approle/role/ansible \
  token_policies=netops-ro token_ttl=1h token_max_ttl=4h \
  secret_id_ttl=24h secret_id_num_uses=0 token_bound_cidrs=198.51.100.0/24
 
vault read -field=role_id auth/approle/role/ansible/role-id        # ít nhạy cảm, có thể để trong config
vault write -f -field=secret_id auth/approle/role/ansible/secret-id # nhạy cảm, giao qua CI secret
 
# Phía automation
export VAULT_TOKEN=$(vault write -field=token auth/approle/login \
  role_id="$VAULT_ROLE_ID" secret_id="$VAULT_SECRET_ID")
vault kv get -mount=secret -field=password netops/router

Trong Ansible, collection community.hashi_vault đọc trực tiếp (lookup community.hashi_vault.vault_kv2_get, auth approle hoặc token), không cần ghi secret ra file.

Lỗi thường gặp

Triệu chứng Nguyên nhân Cách xử lý
403 permission denied dù policy có secret/netops/* KV v2 cần secret/data/netops/* Sửa path trong policy; thử vault token capabilities <path>
vault kv list bị từ chối nhưng get được Thiếu list trên secret/metadata/... Thêm block metadata
Vault is sealed (503) Vault restart, chưa unseal vault operator unseal (đủ số key share) hoặc cấu hình auto-unseal
x509: certificate signed by unknown authority Client không tin CA của Vault Đặt VAULT_CACERT; không dùng VAULT_SKIP_VERIFY ngoài lab
no handler for route "secret/..." Mount chưa bật hoặc sai tên mount vault secrets list
Token automation hết hạn giữa chừng token_ttl ngắn hơn thời gian job Tăng token_ttl/token_max_ttl vừa đủ, hoặc renew
invalid secret id secret_id hết hạn/hết lượt dùng Cấp secret_id mới; xem secret_id_ttl, secret_id_num_uses

Tham khảo