使用ansible.builtin.script无法找到角色内脚本的问题排查

问题说明 #

调用Ansible角色运行脚本时，远程主机提示临时目录中的脚本找不到，本地脚本已放置在角色的files目录下，但执行失败。

目录结构 #

my-project/
  - ansible/
    - roles/
      - install-docker/
        - files/
          - install-docker.sh
        - meta/
          - main.yml
        - tasks/
          - main.yml
  - gate/
    - ansible/
      - docker-setup.yml
  - ansible.cfg

角色任务配置（tasks/main.yml） #

---
- name: Install docker and docker compose
  ansible.builtin.script: "{{ role_path }}/files/install-docker.sh"
  args:
    creates: /etc/apt/keyrings/docker.asc

调用剧本（gate/ansible/docker-setup.yml） #

---
- name: Install docker
  hosts: some-host
  vars:
    root_dir: /home/foo

  roles:
      - install-docker

ansible.cfg配置 #

[defaults]
INVENTORY = local_vagrant
roles_path = ./ansible/roles

[ssh_connection]
pipelining = true

运行命令及错误输出 #

运行命令：

(.venv) foo@foo:~$ cd my-project
(.venv) foo@foo:~/my-project$ ansible-playbook gate/ansible/docker-setup.yml -i production

错误输出：

PLAY [Install docker] ************************************************************************************************************************************************************************************************************************

TASK [Gathering Facts] ***********************************************************************************************************************************************************************************************************************
[WARNING]: Platform linux on host some-host is using the discovered Python interpreter at /usr/bin/python3.12, but future installation of another Python interpreter could change the meaning of that path. See
https://docs.ansible.com/ansible-core/2.17/reference_appendices/interpreter_discovery.html for more information.
ok: [some-host]

TASK [install-docker : Install docker and docker compose] ************************************************************************************************************************************************************************************
An exception occurred during task execution. To see the full traceback, use -vvv. The error was: NoneType: None
fatal: [some-host]: FAILED! => {"changed": true, "msg": "non-zero return code", "rc": 127, "stderr": "Shared connection to xxx.xxx.xxx.xxx closed.\r\n", "stderr_lines": ["Shared connection to xxx.xxx.xxx.xxx closed."], "stdout": "/bin/sh: 1: /home/foo/.ansible/tmp/ansible-tmp-1718466187.643503-255075-226226739385306/install-docker.sh: not found\r\n", "stdout_lines": ["/bin/sh: 1: /home/foo/.ansible/tmp/ansible-tmp-1718466187.643503-255075-226226739385306/install-docker.sh: not found"]}

PLAY RECAP ***********************************************************************************************************************************************************************************************************************************
some-host                   : ok=1    changed=0    unreachable=0    failed=1    skipped=0    rescued=0    ignored=0

问题原因及解决方法 #

原因1：role_path使用方式错误 #

Ansible的script模块在角色环境中会自动从角色的files目录查找文件，手动拼接role_path可能导致路径解析异常，尤其是嵌套目录场景下。

解决方法：修改角色任务中的脚本路径为相对路径：

---
- name: Install docker and docker compose
  ansible.builtin.script: files/install-docker.sh
  args:
    creates: /etc/apt/keyrings/docker.asc

原因2：本地脚本权限不足 #

如果本地install-docker.sh没有读权限，Ansible无法读取并传输到远程临时目录，导致远程找不到文件。

解决方法：给脚本添加读权限（如需远程执行可再加执行权限）：

chmod +r ansible/roles/install-docker/files/install-docker.sh
# 如需远程执行脚本，添加执行权限
chmod +x ansible/roles/install-docker/files/install-docker.sh

原因3：Pipelining开启导致文件传输失败 #

开启pipelining虽能提升性能，但部分场景下会干扰Ansible的文件传输逻辑，导致脚本无法正确上传到远程。

解决方法：临时关闭pipelining测试，可修改ansible.cfg：

[ssh_connection]
pipelining = false

或在剧本中临时设置变量：

---
- name: Install docker
  hosts: some-host
  vars:
    root_dir: /home/foo
    ansible_ssh_pipelining: false

  roles:
      - install-docker

原因4：文件名拼写错误 #

Linux系统区分大小写，检查本地脚本文件名是否与任务中指定的完全一致，例如是否存在大小写或拼写错误。

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