Fix lỗi "Decryption failed (no vault secrets would decrypt)" trong Ansible Vault

TL;DR

Ansible đã thử mọi vault secret bạn cung cấp nhưng không có cái nào mở được file. Ba nguyên nhân chiếm 90% trường hợp: sai mật khẩu, thiếu cờ --vault-password-file, hoặc vault ID label không khớp. Chạy các lệnh này trước để nhanh chóng thu hẹp vấn đề.

# Kiểm tra tương tác — loại trừ lỗi gõ nhầm mật khẩu ngay lập tức
ansible-vault view /path/to/vars/vault.yml --ask-vault-pass

# Với file mật khẩu
ansible-vault view /path/to/vars/vault.yml --vault-password-file ~/.vault_pass

# Với vault ID có nhãn
ansible-vault view /path/to/vars/vault.yml --vault-id prod@~/.vault_pass_prod

Chuyện Gì Đang Xảy Ra

Trong khi thực thi playbook, Ansible lần lượt thử từng vault secret bạn đã cung cấp với file được mã hóa. Khi không có cái nào hoạt động, bạn nhận được:

ERROR! Decryption failed (no vault secrets would decrypt) on /path/to/vars/vault.yml

File vẫn bị khóa. Playbook dừng lại. Đây là thiết kế có chủ đích — Ansible sẽ không âm thầm bỏ qua các biến được mã hóa và để lộ hạ tầng cấu hình nửa chừng.

Nguyên Nhân Gốc Rễ

• Sai mật khẩu — gõ nhầm, hoặc dùng mật khẩu từ môi trường khác
• Không cung cấp vault secret — quên --ask-vault-pass hoặc --vault-password-file
• Vault ID không khớp — file được mã hóa với nhãn prod nhưng bạn đang truyền nhãn dev
• File mật khẩu bị lỗi — khoảng trắng thừa, ký tự xuống dòng kiểu Windows (CRLF), hoặc đường dẫn file sai
• File được mã hóa bởi người khác — đồng nghiệp dùng key của họ mà bạn không có

Fix 1: Cung Cấp Đúng Mật Khẩu Vault

Bắt đầu với lệnh nhập mật khẩu tương tác. Cách này loại bỏ các biến tự động hóa và cho bạn biết ngay mật khẩu có đúng không:

ansible-playbook site.yml --ask-vault-pass

Chạy được ở đây nhưng lại lỗi trong lần chạy bình thường? Mật khẩu ổn rồi. Vấn đề là cách nó được cung cấp — chuyển sang Fix 2 hoặc Fix 3.

Fix 2: Kiểm Tra File Mật Khẩu Vault

File mật khẩu thất bại âm thầm. Một ký tự xuống dòng lạc hoặc khoảng trắng thừa ở cuối vô hình với mắt thường nhưng phá vỡ hoàn toàn quá trình giải mã. Kiểm tra file của bạn:

# Hiển thị ký tự không in được — tìm khoảng trắng thừa hoặc ký tự xuống dòng kiểu Windows
cat -A ~/.vault_pass
# Đúng: "mypassword$"
# Sai:  "mypassword ^M$"  (Windows CRLF)
# Sai:  "mypassword  $"   (khoảng trắng thừa)

Ghi mật khẩu sạch để sửa:

echo -n "yourpassword" > ~/.vault_pass
chmod 600 ~/.vault_pass

Truyền trực tiếp, hoặc đặt mặc định trong ansible.cfg để không bao giờ quên cờ:

ansible-playbook site.yml --vault-password-file ~/.vault_pass

# Hoặc trong ansible.cfg:
# [defaults]
# vault_password_file = ~/.vault_pass

Fix 3: Khớp Vault ID Label

Vault ID có nhãn được giới thiệu trong Ansible 2.4. Chúng hữu ích cho các thiết lập đa môi trường, nhưng cũng là nguồn gốc phổ biến của lỗi này — nếu file được mã hóa với một nhãn, bạn phải dùng đúng nhãn đó để giải mã. Kiểm tra header của file trước:

head -1 /path/to/vars/vault.yml
# Ví dụ đầu ra:
# $ANSIBLE_VAULT;1.1;AES256          ← không có nhãn (định dạng cổ điển)
# $ANSIBLE_VAULT;1.2;AES256;prod     ← vault ID label là "prod"

Header hiển thị prod? Truyền ID tương ứng:

# File đã được mã hóa với:
ansible-vault encrypt --vault-id prod@prompt vault.yml

# Vậy giải mã/chạy với:
ansible-playbook site.yml --vault-id prod@~/.vault_pass_prod

# Nhiều môi trường trong một lần chạy:
ansible-playbook site.yml \
  --vault-id dev@~/.vault_pass_dev \
  --vault-id prod@~/.vault_pass_prod

Xóa vault ID label (tùy chọn)

Labels gây thêm phiền phức hơn giá trị? Hãy loại bỏ chúng:

# Giải mã bằng mật khẩu có nhãn gốc
ansible-vault decrypt vault.yml --vault-id prod@~/.vault_pass_prod

# Mã hóa lại không có nhãn
ansible-vault encrypt vault.yml --ask-vault-pass

Fix 4: Rekey File Vault

Thay đổi mật khẩu — ví dụ đồng nghiệp đã nghỉ việc, hoặc bạn đang chuẩn hóa secrets trên các môi trường — là thao tác chỉ một lệnh:

ansible-vault rekey /path/to/vars/vault.yml
# Yêu cầu mật khẩu hiện tại, sau đó mật khẩu mới

Fix 5: Kiểm Tra ansible.cfg Có Cài Đặt Xung Đột

Có thể có một đường dẫn vault_password_file ẩn trong một trong các file cấu hình của bạn. Nếu nó trỏ đến file cũ hoặc sai, nó sẽ âm thầm ghi đè cờ dòng lệnh của bạn — và bạn sẽ không bao giờ biết tại sao:

grep -r vault /etc/ansible/ansible.cfg ~/.ansible.cfg ./ansible.cfg 2>/dev/null

Cập nhật hoặc xóa bất kỳ đường dẫn cũ nào bạn tìm thấy. File ./ansible.cfg ở cấp dự án có ưu tiên cao hơn ~/.ansible.cfg, vì vậy hãy kiểm tra cả hai.

Kiểm Tra Lại

Trước khi chạy toàn bộ playbook, xác nhận việc giải mã hoạt động riêng lẻ:

# Xem nội dung đã giải mã mà không sửa đổi file
ansible-vault view /path/to/vars/vault.yml --vault-password-file ~/.vault_pass

# Chạy thử playbook
ansible-playbook site.yml --vault-password-file ~/.vault_pass --check

Nếu ansible-vault view xuất ra nội dung file mà không có lỗi, là ổn rồi. Hãy chạy playbook.

Mẹo: Quản Lý Mật Khẩu Vault

Hầu hết các nhóm đều gặp lỗi này nhiều hơn một lần. Đây là những gì giúp tránh nó quay lại:

Để tạo mật khẩu vault mạnh, tôi dùng Password Generator trên ToolCraft. Nó chạy hoàn toàn trên trình duyệt — không có gì được gửi lên server, điều này quan trọng khi bạn đang thiết lập hạ tầng quản lý secrets.

• Lưu trữ mật khẩu vault trong trình quản lý secrets của nhóm (HashiCorp Vault, AWS Secrets Manager, 1Password Teams) — không phải trong file văn bản được commit vào repo
• Chọn quy ước đặt tên vault ID nhất quán — dev, staging, prod — và ghi lại ID nào đã mã hóa file nào
• Thêm vault_password_file = ~/.vault_pass vào ~/.ansible.cfg cá nhân để cờ không bao giờ bị bỏ sót
• Hướng dẫn đồng nghiệp mới qua trình quản lý secrets, không phải qua Slack DM