Sửa Lỗi Ansible "Could not find or access 'templates/nginx.conf.j2'"

Mô Tả Lỗi

Bạn chạy một Ansible playbook và nó thất bại ngay lập tức với thông báo:

fatal: [host]: FAILED! => {"changed": false, "msg": "Could not find or access 'templates/nginx.conf.j2' on the Ansible Controller."}

Chín lần trong mười, tác vụ sử dụng ansible.builtin.template (hoặc viết tắt là template) là thủ phạm. Chú ý nội dung thông báo: Ansible tìm kiếm trên controller — máy bạn chạy lệnh ansible-playbook — chứ không phải host từ xa. File đơn giản là không ở nơi Ansible mong đợi.

Nguyên Nhân Gây Lỗi

Ansible đã biết cần tìm kiếm bên trong thư mục con templates/ tương đối với playbook hoặc role của bạn. Điều đó được tích hợp sẵn trong logic tra cứu. Vì vậy, src chỉ nên chứa tên file — nginx.conf.j2, không phải templates/nginx.conf.j2.

Có hai nguyên nhân chính gây ra lỗi này:

• Bạn viết src: templates/nginx.conf.j2, khiến Ansible tìm kiếm templates/templates/nginx.conf.j2. Đường dẫn đó không tồn tại.
• File .j2 nằm sai thư mục — không phải nơi Ansible thực sự tìm kiếm.

Cách Sửa Từng Bước

Bước 1 — Kiểm Tra Cách Gọi Template Module

Kiểm tra trường src trong tác vụ của bạn:

# SAI — đừng thêm tiền tố "templates/"
- name: Deploy nginx config
  ansible.builtin.template:
    src: templates/nginx.conf.j2
    dest: /etc/nginx/nginx.conf

# ĐÚNG — chỉ cần tên file
- name: Deploy nginx config
  ansible.builtin.template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf

Ansible đã tự động tìm trong templates/ cạnh playbook hoặc bên trong role của bạn. Thêm tiền tố sẽ nhân đôi đường dẫn thành templates/templates/nginx.conf.j2 — đường dẫn này không bao giờ tồn tại.

Bước 2 — Xác Nhận File Tồn Tại Đúng Vị Trí

Trường hợp A: Template ở cấp playbook (không dùng roles)

Template phải nằm trong thư mục templates/ ngay cạnh playbook của bạn:

site.yml
templates/
  nginx.conf.j2    ← phải đặt ở đây

Kiểm tra nhanh:

ls -la templates/nginx.conf.j2

Trường hợp B: Bên trong một role

Các tác vụ bên trong một role sẽ tìm trong thư mục templates/ của chính role đó — không phải thư mục gốc dự án:

roles/
  nginx/
    tasks/
      main.yml
    templates/
      nginx.conf.j2    ← phải đặt ở đây

Kiểm tra nhanh:

ls -la roles/nginx/templates/nginx.conf.j2

Lỗi kinh điển: bạn đặt template vào templates/ ở thư mục gốc dự án nhưng lại chạy tác vụ từ bên trong một role. Ansible tìm kiếm trong thư mục của role trước và không bao giờ tìm thấy ở đó.

Bước 3 — Sửa Cấu Trúc Thư Mục

Thiếu thư mục hoặc sai vị trí? Hãy tạo và di chuyển file:

# Cho role tên "nginx"
mkdir -p roles/nginx/templates
mv nginx.conf.j2 roles/nginx/templates/

# Cho template ở cấp playbook
mkdir -p templates
mv nginx.conf.j2 templates/

Bước 4 — Kiểm Tra Lỗi Chính Tả và Phân Biệt Hoa/Thường

Hệ thống file Linux phân biệt chữ hoa và chữ thường. Nginx.conf.j2 và nginx.conf.j2 là hai file hoàn toàn khác nhau. Xác nhận tên file chính xác trên ổ đĩa:

ls templates/
# Phải hiển thị: nginx.conf.j2 (không phải Nginx.conf.j2)

Bước 5 — Dùng Đường Dẫn Tuyệt Đối (Giải Pháp Cuối Cùng)

Template được lưu ở vị trí không chuẩn? Truyền trực tiếp đường dẫn đầy đủ:

- name: Deploy nginx config
  ansible.builtin.template:
    src: /opt/configs/nginx.conf.j2
    dest: /etc/nginx/nginx.conf

Cách này hoạt động, nhưng nó gắn playbook với một máy cụ thể. Tránh dùng trong những thứ bạn định chia sẻ hoặc tái sử dụng.

Xác Nhận Bản Sửa Lỗi

Tăng mức độ chi tiết để xem chính xác đường dẫn Ansible phân giải:

ansible-playbook site.yml -vvv 2>&1 | grep -i "template\|j2"

Khi hoạt động đúng, bạn sẽ thấy kết quả tương tự:

TASK [Deploy nginx config] ****
ok: [host] => changed=true

Muốn kiểm tra mà không thay đổi bất kỳ file nào? Thêm --check:

ansible-playbook site.yml --check

Tra Cứu Nhanh: Ansible Tìm Template Ở Đâu

# Cấp playbook (site.yml ở thư mục gốc dự án)
./templates/
./

# Cấp role (tác vụ bên trong roles/nginx/tasks/main.yml)
roles/nginx/templates/
roles/nginx/
./templates/      ← cũng được kiểm tra, nhưng templates của role có độ ưu tiên cao hơn
./

Ansible duyệt qua danh sách này và dùng kết quả khớp đầu tiên tìm thấy. Thư mục templates/ đã là một phần của quá trình tìm kiếm — đó chính xác là lý do tại sao việc thêm tiền tố vào src gây ra lỗi tra cứu đường dẫn đôi.

Mẹo

• Không bao giờ thêm tiền tố templates/ vào src — đây là nguyên nhân hàng đầu gây ra lỗi này, và rất dễ bỏ qua khi nhìn lướt qua.
• Chuyển tác vụ từ playbook phẳng vào một role? Hãy đồng thời chuyển các template vào thư mục templates/ của role, nếu không chúng sẽ nằm ngoài đường dẫn tìm kiếm của Ansible.
• Các thư mục con bên trong templates/ hoạt động tốt trong src: src: nginx/nginx.conf.j2 phân giải thành templates/nginx/nginx.conf.j2.
• Chạy ansible-playbook --list-tasks để xác nhận role nào sở hữu một tác vụ trước khi bắt đầu tìm kiếm đường dẫn template.