Sửa lỗi "vault password file not found" trong Ansible Vault

Lỗi Gặp Phải

Bạn đang chạy một playbook với các biến được mã hóa bằng vault và đột nhiên gặp:

ERROR! The vault password file /path/to/.vault_pass was not found or is not readable

Lỗi này thường xuất hiện nhất sau khi clone một repo về máy mới, thiết lập CI/CD, hoặc đơn giản là chạy playbook từ sai thư mục. Playbook vẫn chạy tốt hôm qua, bây giờ lại không. Sau đây là cách tôi debug vấn đề này.

Quy Trình Debug

1. Tìm xem Ansible đang tìm file vault password ở đâu

Đường dẫn có thể đến từ ba nơi khác nhau. Kiểm tra theo thứ tự sau:

• ansible.cfg trong thư mục hiện tại hoặc thư mục home của bạn
• Biến môi trường ANSIBLE_VAULT_PASSWORD_FILE
• Cờ CLI --vault-password-file

# Kiểm tra ansible.cfg của bạn
grep -r vault_password_file ansible.cfg ~/.ansible.cfg /etc/ansible/ansible.cfg 2>/dev/null

# Kiểm tra biến môi trường
echo $ANSIBLE_VAULT_PASSWORD_FILE

2. Xác minh file có thực sự tồn tại ở đường dẫn đó không

ls -la /path/to/.vault_pass

No such file or directory có nghĩa là file thực sự không tồn tại — chưa được tạo trên máy này, đã bị xóa, hoặc đường dẫn đơn giản là sai.

File tồn tại nhưng lỗi vẫn còn? Đó là vấn đề phân quyền:

stat /path/to/.vault_pass
# Xem dòng "Access" — cần có quyền đọc cho user đang chạy ansible

3. Kiểm tra xem có phải lỗi do đường dẫn tương đối không

Đây là một bẫy cổ điển. Khi ansible.cfg dùng đường dẫn tương đối như vault_password_file = .vault_pass, Ansible sẽ phân giải nó theo thư mục làm việc hiện tại — không phải vị trí của file config. Chạy playbook từ thư mục khác là sẽ bị lỗi ngay.

# Lỗi — chạy từ thư mục cha
cd /home/user
ansible-playbook myproject/site.yml

# Đúng — chạy từ thư mục gốc của project nơi có .vault_pass
cd /home/user/myproject
ansible-playbook site.yml

Giải Pháp

Giải pháp 1: Tạo file vault password còn thiếu

Trên máy mới hoặc repo vừa clone về, file đơn giản là chưa tồn tại. Bạn cần tạo lại nó. File vault password chỉ là văn bản thuần túy — một dòng, chứa mật khẩu, không có gì khác.

# Tạo file
echo 'your_vault_password_here' > ~/.vault_pass

# Khóa lại — chỉ chủ sở hữu mới được đọc file này
chmod 600 ~/.vault_pass

Mật khẩu phải khớp với mật khẩu đã dùng để mã hóa vault ban đầu. Quên mật khẩu rồi? Dữ liệu sẽ không thể khôi phục được. Đó là vault hoạt động đúng như thiết kế.

Giải pháp 2: Sửa phân quyền

File tồn tại nhưng Ansible vẫn không đọc được:

# Sửa quyền sở hữu và phân quyền
chown $USER ~/.vault_pass
chmod 600 ~/.vault_pass

# Kiểm tra lại
ls -la ~/.vault_pass
# Kết quả hiển thị: -rw------- 1 youruser yourgroup ...

Giải pháp 3: Dùng đường dẫn tuyệt đối trong ansible.cfg

Chuyển sang đường dẫn tuyệt đối sẽ loại bỏ hoàn toàn vấn đề "đang ở thư mục nào":

[defaults]
vault_password_file = /home/youruser/.vault_pass

Dùng dấu tilde cũng được — Ansible mở rộng nó đúng cách:

[defaults]
vault_password_file = ~/.vault_pass

Giải pháp 4: Truyền trực tiếp qua dòng lệnh

Cần chạy ngay mà không muốn chỉnh config? Dùng cờ này:

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

# Hoặc nhập mật khẩu thủ công
ansible-playbook site.yml --ask-vault-pass

Giải pháp 5: Dùng biến môi trường (cho CI/CD)

Các pipeline tự động không nên có file mật khẩu được commit vào repo. Lưu vault password dưới dạng CI secret và ghi vào file tạm lúc chạy — rồi xóa đi khi xong:

# Ví dụ với GitHub Actions
- name: Run playbook
  env:
    VAULT_PASS: ${{ secrets.ANSIBLE_VAULT_PASSWORD }}
  run: |
    echo "$VAULT_PASS" > /tmp/.vault_pass
    chmod 600 /tmp/.vault_pass
    ansible-playbook site.yml --vault-password-file /tmp/.vault_pass
    rm -f /tmp/.vault_pass

Giải pháp 6: Dùng script vault password

Các thiết lập phức tạp hơn — nhiều vault ID, lấy từ AWS Secrets Manager hoặc HashiCorp Vault — có thể dùng một script thực thi thay vì file thông thường. Ansible sẽ chạy script đó và đọc mật khẩu từ stdout:

#!/bin/bash
# get-vault-pass.sh
echo "$VAULT_PASSWORD"

chmod +x get-vault-pass.sh

# ansible.cfg
[defaults]
vault_password_file = ./get-vault-pass.sh

Kiểm Tra Lại

Trước khi chạy toàn bộ playbook, hãy xác nhận bản sửa đã hoạt động bằng cách thử giải mã nhanh:

# Thử xem trực tiếp một file đã mã hóa
ansible-vault view group_vars/all/vault.yml

# Hoặc giải mã ra stdout mà không ghi file
ansible-vault decrypt --output - group_vars/all/vault.yml

Thấy nội dung đã giải mã trên màn hình? Vậy là xong. Vẫn thấy ERROR! Decryption failed? File đã tìm thấy và đọc được — nhưng mật khẩu sai.

Lưu Ý Thực Tế

• Thêm .vault_pass và các pattern tương tự vào .gitignore ngay lập tức. Tuyệt đối không commit file vault password.
• Luôn giữ chmod 600 cho file. Một số phiên bản Ansible từ chối dùng file mật khẩu có quyền đọc toàn cục, và dù thế nào thì đây cũng là thói quen bảo mật tồi.
• Cần tạo vault password ngẫu nhiên và mạnh? Trình tạo mật khẩu của ToolCraft chạy hoàn toàn trên trình duyệt — không gửi dữ liệu lên server — và tạo ra kết quả ngẫu nhiên theo chuẩn mật mã. Đủ tốt để dùng cho vault secrets.
• Trong README của project, hãy ghi rõ vault ID nào tương ứng với file mật khẩu nào. Không cần ghi mật khẩu — chỉ cần ghi sơ đồ ánh xạ. Các thành viên trong nhóm sau này (kể cả chính bạn sáu tháng nữa) sẽ cảm ơn bạn.

Bài Học Rút Ra

Hầu hết các lỗi vault password file not found đều xuất phát từ ba nguyên nhân gốc: file chưa tồn tại trên máy này, đường dẫn trong ansible.cfg là tương đối và bạn đang ở sai thư mục, hoặc phân quyền bị sai.

Giải pháp lâu dài rất đơn giản: dùng đường dẫn tuyệt đối (hoặc ~/.vault_pass) trong ansible.cfg, giữ file ở chmod 600, và lưu vault password ở nơi an toàn như một trình quản lý mật khẩu. Với các project nhóm, hãy chọn một vị trí chuẩn thống nhất — ~/.vault_pass là ổn — và ghi vào README để người tiếp theo thiết lập project biết chính xác cần tạo file gì.