Sửa lỗi Ansible 'this task has extra params': Sai cú pháp Free-Form Module

Lỗi Gặp Phải

ERROR! this task 'copy' has extra params, which is only allowed in the following modules: raw, meta, include, include_tasks, import_tasks

Chạy ansible-playbook và lệnh dừng lại ngay — không có thử kết nối, không có output từ host, không có gì cả. Lỗi nằm ở định nghĩa task, không phải trên remote host.

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

Ansible module nhận tham số theo hai cách:

• Free-form (chuỗi inline): chỉ hợp lệ với command, shell, raw, script. Một chuỗi duy nhất, cùng dòng với module key.
• Key=value hoặc YAML dict: dành cho mọi trường hợp còn lại — copy, file, apt, template, v.v.

Lỗi xảy ra khi bạn trộn lẫn hai kiểu này. Thường là do tham số được đặt ở cấp task thay vì lồng vào trong module, hoặc chuỗi inline được kết hợp với YAML key trong cùng một task block. Chỉ cần một tham số đặt sai vị trí là đủ gây lỗi.

Các Tình Huống Thường Gặp

Tình huống 1: Key thừa đặt ở cấp task thay vì cấp module

# SAI
- name: Copy config file
  copy: src=files/app.conf dest=/etc/app/app.conf
  mode: '0644'         # <-- cấp task, không phải trong copy:
  owner: root

mode và owner nằm ở task dict thay vì bên trong module. Ansible coi chúng là các key không xác định ở cấp task và báo lỗi.

Tình huống 2: Chuỗi free-form trộn với YAML dict key

# SAI
- name: Copy config file
  copy: src=files/app.conf dest=/etc/app/app.conf
    mode: '0644'

Trộn chuỗi key=value inline với YAML thụt lề bên dưới cùng một module key sẽ làm trình phân tích cú pháp bị lỗi. Hãy chọn một kiểu và dùng nhất quán.

Tình huống 3: Lỗi đánh máy — còn sót module key thứ hai trong task block

# SAI
- name: Restart nginx
  service:
    name: nginx
    state: restarted
  copy:                  # <-- còn sót từ lần cắt-dán
    src: files/nginx.conf
    dest: /etc/nginx/nginx.conf

Một task chỉ được có một module. Module key thứ hai (copy: ở đây) trở thành tham số thừa không được nhận dạng — lỗi kinh điển do copy-paste.

Cách Sửa

Lồng tất cả tham số vào trong module theo cú pháp YAML dict

# ĐÚNG
- name: Copy config file
  copy:
    src: files/app.conf
    dest: /etc/app/app.conf
    mode: '0644'
    owner: root

Mọi tham số đều nằm trong copy: theo dạng key thụt lề. Ở cùng cấp thụt lề với copy:, chỉ có các từ khóa task chuẩn: name, when, notify, tags, become, v.v.

Key=value inline cũng được — nhưng phải viết tất cả trên một dòng

# ĐÚNG — tất cả tham số inline
- name: Copy config file
  copy: src=files/app.conf dest=/etc/app/app.conf mode='0644' owner=root

Khi có hơn ba bốn tham số, cách này sẽ trở thành một chuỗi dài khó đọc. Dùng YAML dict dễ đọc và dễ review hơn trong pull request.

Module free-form (command, shell) hoạt động khác

# ĐÚNG — shell/command dùng free-form
- name: Check disk usage
  shell: df -h /

# ĐÚNG — tùy chọn có cấu trúc đặt trong args:, không trộn inline
- name: Run script with timeout
  command: /opt/scripts/deploy.sh
  args:
    chdir: /opt/scripts

Ngay cả với module free-form, các tùy chọn có cấu trúc như chdir hay stdin vẫn phải đặt trong args:. Không được viết inline cùng với chuỗi lệnh.

Chẩn Đoán Nhanh

Ansible nêu tên task bị lỗi trong thông báo lỗi. Tìm task đó trong playbook và kiểm tra:

• Bất kỳ key nào ở cấp cao nhất của task mà không phải từ khóa Ansible chuẩn (name, when, register, loop, notify, tags, become, ignore_errors, v.v.)
• Tham số module bị đặt cao hơn một cấp thụt lề so với yêu cầu
• Hai module key trong cùng một task block

Trước khi động đến bất kỳ remote host nào, hãy chạy kiểm tra cú pháp:

ansible-playbook site.yml --syntax-check

Không có kết nối SSH, không có rủi ro — chỉ là phân tích nhanh YAML của bạn.

Xác Nhận Sau Khi Sửa

# Kiểm tra cú pháp — không được có lỗi
ansible-playbook site.yml --syntax-check

# Output mong đợi
playbook: site.yml

# Chạy thử để xác nhận task sẽ thực thi đúng
ansible-playbook site.yml --check --diff

--syntax-check thoát sạch nghĩa là lỗi extra params đã được giải quyết. Tiếp theo dùng --check --diff để xem chính xác task sẽ thay đổi gì — vẫn không cần kết nối đến remote host.

Mẹo Tránh Lỗi Trong Tương Lai

• Mặc định dùng cú pháp YAML dict cho các module không phải free-form. Cách này giúp lộ rõ lỗi thụt lề ngay khi nhìn vào.
• Thêm --syntax-check vào pipeline CI. Nó phát hiện toàn bộ lớp lỗi này trong chưa đến một giây, trước khi PR được merge.
• Chạy ansible-lint trên máy local. Cài bằng pip install ansible-lint, rồi chạy ansible-lint site.yml. Công cụ này gắn cờ cú pháp trộn lẫn và hàng chục vấn đề style khác.
• Cài extension VS Code Ansible (Red Hat). Lỗi cấu trúc hiện ra dưới dạng gạch đỏ ngay khi bạn gõ — không cần chạy lệnh gì thêm.