ansible.builtin.script module – Runs a local script on a remote node after transferring it
Note
This module is part of ansible-core
and included in all Ansible
installations. In most cases, you can use the short
module name
script
even without specifying the collections keyword.
However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.script
for easy linking to the
module documentation and to avoid conflicting with other collections that may have
the same module name.
Synopsis
The ansible.builtin.script module takes the script name followed by a list of space-delimited arguments.
Either a free-form command or
cmd
parameter is required, see the examples.The local script at the path will be transferred to the remote node and then executed.
The given script will be processed through the shell environment on the remote node.
This module does not require Python on the remote system, much like the ansible.builtin.raw module.
This module is also supported for Windows targets.
Note
This module has a corresponding action plugin.
Parameters
Parameter |
Comments |
---|---|
Change into this directory on the remote node before running the script. |
|
Path to the local script to run followed by optional arguments. |
|
A filename on the remote node, when it already exists, this step will not be run. |
|
This option controls the autodecryption of source files using vault. Choices:
|
|
Name or path of an executable to invoke the script with. |
|
Path to the local script file followed by optional arguments. |
|
A filename on the remote node, when it does not exist, this step will not be run. |
Attributes
Attribute |
Support |
Description |
---|---|---|
Can run in check_mode and return changed status prediction without modifying target |
||
Support: none |
Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
|
Platforms: all This action is one of the few that requires no Python on the remote as it passes the command directly into the connection string |
Target OS/families that can be operated against |
|
Support: full |
Indicates if an action takes a ‘raw’ or ‘free form’ string as an option and has it’s own special parsing of it |
|
Support: none |
Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption |
|
Support: full |
Can automatically decrypt Ansible vaulted files |
Notes
Note
It is usually preferable to write Ansible modules rather than pushing scripts. Convert your script to an Ansible module for bonus points!
The ansible.builtin.ssh connection plugin will force pseudo-tty allocation via
-tt
when scripts are executed. Pseudo-ttys do not have a stderr channel and all stderr is sent to stdout. If you depend on separated stdout and stderr result keys, please switch to a set of tasks that comprises ansible.builtin.copy with ansible.builtin.command instead of using ansible.builtin.script.If the path to the local script contains spaces, it needs to be quoted.
This module is also supported for Windows targets.
If the script returns non-UTF-8 data, it must be encoded to avoid issues. One option is to pipe the output through
base64
.
See Also
See also
- ansible.builtin.shell
Execute shell commands on targets.
- ansible.windows.win_shell
Execute shell commands on target hosts.
Examples
- name: Run a script with arguments (free form)
ansible.builtin.script: /some/local/script.sh --some-argument 1234
- name: Run a script with arguments (using 'cmd' parameter)
ansible.builtin.script:
cmd: /some/local/script.sh --some-argument 1234
- name: Run a script only if file.txt does not exist on the remote node
ansible.builtin.script: /some/local/create_file.sh --some-argument 1234
args:
creates: /the/created/file.txt
- name: Run a script only if file.txt exists on the remote node
ansible.builtin.script: /some/local/remove_file.sh --some-argument 1234
args:
removes: /the/removed/file.txt
- name: Run a script using an executable in a non-system path
ansible.builtin.script: /some/local/script
args:
executable: /some/remote/executable
- name: Run a script using an executable in a system path
ansible.builtin.script: /some/local/script.py
args:
executable: python3
- name: Run a Powershell script on a Windows host
script: subdirectories/under/path/with/your/playbook/script.ps1