Ansible报未引用的crystal变量未定义错误如何排查

问题背景 #

我正在修改一个可正常运行的Ansible playbook中的两个任务，目标是按循环变量agency遍历每个机构，登记对应主机上指定文件是否存在，后续仅为不存在对应文件的机构生成该文件。

注意：出于隐私考虑，代码中的部分路径和引用已做修改。

相关任务代码 #

- name: Register if file.asp exists for each agency
  win_stat:
    path: "C:/path/file_{{ agency.agency_name|upper }}_{{ env_name|upper }}.asp"
  register: reportASP_status
  with_items:
    "{{ agencies }}"
  loop_control:
    loop_var: agency
    label: "{{ agency.agency_name }}"

- name: Generate file.asp locally
  template:
    newline_sequence: "\r\n"
    src: file.asp.j2
    dest: "path/crystal/file_{{ item.agency.agency_name|upper }}_{{ env_name|upper }}.asp"
  loop: "{{ reportASP_status.results }}"
  loop_control:
    label: "{{ item.agency.agency_name }}"
  run_once: true
  delegate_to: localhost
  when:
    not item.stat.exists

错误现象 #

登记文件状态的任务运行正常，输出reportASP_status变量可确认所有状态均已成功注册。生成文件的任务可正确跳过已存在的文件，但遇到需要生成的文件时，任务执行失败，报错信息如下：

{
    "ansible_loop_var": "item",
    "changed": false,
    "item": {
        "agency": {
            "agency_name": "IDontHaveIt",
            "credentials": {
                "report": {
                    "password": 1234567,
                    "username": "username"
                }
            },
            "database_fqdn": "one.db.com",
            "database_name": "IDontHaveIt"
        },
        "ansible_loop_var": "agency",
        "changed": false,
        "failed": false,
        "invocation": {
            "module_args": {
                "checksum_algorithm": "sha1",
                "follow": false,
                "get_checksum": true,
                "path": "C:/PATH/file_IDONTHAVEIT_LOCALDEV.asp"
            }
        },
        "stat": {
            "exists": false
        }
    },
    "msg": "AnsibleUndefinedVariable: 'crystal' is undefined"
}

我从未定义过名为crystal的变量，也未在上述两个任务的代码中引用该变量，使用--debug和-vvv参数运行playbook也未获得更多有效错误信息。请问针对这类未主动引用的变量触发的未定义错误，该如何着手排查？

排查方案 #

• 优先检查Jinja2模板文件file.asp.j2的内容：template模块的报错首先定位模板内部的变量引用，你任务参数中的path/crystal/是静态路径字符串，不会被解析为变量，crystal变量几乎都是来自模板内部的错误引用。
• 排查模板语法错误：确认模板中是否存在漏加引号的字符串，比如原本需要写为静态值的crystal没有加单/双引号，被Jinja2误识别为变量。
• 扩大变量排查范围：检查当前play关联的所有变量源，包括inventory配置、主机/组变量文件、vars字段定义、vars_files导入的文件、命令行-e传入的变量，确认是否有拼写错误导致无意中调用了crystal变量。
• 模板验证测试：将file.asp.j2替换为只有静态文本的测试模板，重新运行任务，如果报错消失即可100%定位问题出在原模板内部，无需再排查任务配置。
• 开启模板调试：在ansible.cfg中添加配置jinja2_extensions = jinja2.ext.debug，在模板开头加入{% debug %}标签，运行任务时会输出模板渲染阶段所有可用变量，可快速定位错误引用的位置。

内容的提问来源于stack exchange，提问作者AbianG