Модуль ansible.builtin.shell – Выполнение команд оболочки на целевых узлах

Примечание

Этот модуль является частью ansible-core и включён во все установки Ansible. В большинстве случаев вы можете использовать короткое имя модуля shell даже без указания ключевого слова collections. Однако рекомендуется использовать полное имя коллекции (FQCN) ansible.builtin.shell для удобной ссылки на документацию по модулю и для предотвращения конфликтов с другими коллекциями, которые могут иметь то же имя модуля.

Описание
Параметры
Атрибуты
Примечания
См. также
Примеры
Значения возврата

Описание

Модуль ansible.builtin.shell принимает имя команды, за которым следует список аргументов, разделённых пробелами.
Требуется либо команда в свободном формате, либо параметр cmd, см. примеры.
Он почти идентичен модулю ansible.builtin.command, но выполняет команду через оболочку (/bin/sh) на удалённом узле.
Для целевых узлов Windows используйте модуль ansible.windows.win_shell.

Примечание

У этого модуля есть соответствующий плагин действия.

Параметры

Параметр	Комментарии
chdir path	Перейти в этот каталог перед выполнением команды.
cmd строка	Команда для выполнения, за которой следуют необязательные аргументы.
creates путь	Имя файла; если оно уже существует, этот шаг не будет выполнен.
executable путь	Изменить оболочку, используемую для выполнения команды. Ожидается абсолютный путь к исполняемому файлу.
free_form строка	Модуль оболочки принимает команду в свободном формате, как строку. Нет параметра с именем «свободная форма». См. примеры использования этого модуля.
removes путь	Имя файла; если оно не существует, этот шаг не будет выполнен.
stdin строка	Установить stdin команды напрямую на указанное значение.
stdin_add_newline логическое добавлен в Ansible 2.8	Добавлять ли перевод строки к данным stdin. Варианты: `false` `true` ← (по умолчанию)

Атрибуты

Атрибут	Поддержка	Описание
check_mode	Поддержка: частичная поскольку сама команда произвольная и не может быть подвергнута семантике режима проверки, она добавляет `creates`/`removes` варианты как обходное решение	Может работать в режиме check_mode и возвращать прогноз о статусе изменения без изменения целевого узла, если не поддерживается, действие будет пропущено.
diff_mode	Поддержка: нет	Возвращает детали о том, что изменилось (или, возможно, необходимо изменить в режиме check_mode), при включённом режиме diff
platform	Платформа: posix	Целевые ОС/семьи, по которым можно выполнять операции.
raw	Поддержка: полная	Указывает, принимает ли действие строку «raw» или «free form» в качестве параметра и имеет ли оно собственное специальное парсирование.

Примечания

Примечание

Если вы хотите безопасно и предсказуемо выполнить команду, лучше использовать модуль ansible.builtin.command вместо этого. Лучшие практики при написании playbooks будут следовать тенденции использования ansible.builtin.command, если модуль ansible.builtin.shell явно не требуется. При выполнении ad-hoc команд используйте своё суждение.
Для очистки любых переменных, передаваемых в модуль оболочки, следует использовать {{ var | quote }} вместо простого {{ var }}, чтобы убедиться, что они не содержат вредоносных элементов, таких как точки с запятой.
Альтернативой использованию встроенных скриптов оболочки с этим модулем является использование модуля ansible.builtin.script, возможно совместно с модулем ansible.builtin.template.
Для перезагрузки систем используйте модули ansible.builtin.reboot или ansible.windows.win_reboot.
Если команда возвращает данные, не соответствующие кодировке UTF-8, их необходимо закодировать, чтобы избежать проблем. Одним из вариантов является передача вывода через base64.

См. также

ansible.builtin.command: Выполнение команд на целевых узлах.
ansible.builtin.raw: Выполняет низкоуровневую и грязную команду.
ansible.builtin.script: Запускает локальный скрипт на удаленном узле после его переноса.
ansible.windows.win_shell: Выполнение команд оболочки на целевых хостах.

Примеры

- name: Execute the command in remote shell; stdout goes to the specified file on the remote
  ansible.builtin.shell: somescript.sh >> somelog.txt

- name: Change the working directory to somedir/ before executing the command
  ansible.builtin.shell: somescript.sh >> somelog.txt
  args:
    chdir: somedir/

# You can also use the 'args' form to provide the options.
- name: This command will change the working directory to somedir/ and will only run when somedir/somelog.txt doesn't exist
  ansible.builtin.shell: somescript.sh >> somelog.txt
  args:
    chdir: somedir/
    creates: somelog.txt

# You can also use the 'cmd' parameter instead of free form format.
- name: This command will change the working directory to somedir/
  ansible.builtin.shell:
    cmd: ls -l | grep log
    chdir: somedir/

- name: Run a command that uses non-posix shell-isms (in this example /bin/sh doesn't handle redirection and wildcards together but bash does)
  ansible.builtin.shell: cat < /tmp/*txt
  args:
    executable: /bin/bash

- name: Run a command using a templated variable (always use quote filter to avoid injection)
  ansible.builtin.shell: cat {{ myfile|quote }}

# You can use shell to run other executables to perform actions inline
- name: Run expect to wait for a successful PXE boot via out-of-band CIMC
  ansible.builtin.shell: |
    set timeout 300
    spawn ssh admin@{{ cimc_host }}

    expect "password:"
    send "{{ cimc_password }}\n"

    expect "\n{{ cimc_name }}"
    send "connect host\n"

    expect "pxeboot.n12"
    send "\n"

    exit 0
  args:
    executable: /usr/bin/expect
  delegate_to: localhost

Значения возврата

Общие значения возврата описаны здесь, следующие поля уникальны для данного модуля:

Ключ	Описание
cmd строка	Команда, выполненная задачей. Возвращается: всегда Пример: `"rabbitmqctl join_cluster rabbit@master"`
delta строка	Время выполнения команды. Возвращается: всегда Пример: `"0:00:00.325771"`
end строка	Время окончания выполнения команды. Возвращается: всегда Пример: `"2016-02-25 09:18:26.755339"`
msg логический тип	изменилось Возвращается: всегда Пример: `true`
rc целое число	Код возврата команды (0 означает успех). Возвращается: всегда Пример: `0`
start строка	Время начала выполнения команды. Возвращается: всегда Пример: `"2016-02-25 09:18:26.429568"`
stderr строка	Стандартная ошибка команды. Возвращается: всегда Пример: `"ls: cannot access foo: No such file or directory"`
stderr_lines список / элементы=строка	Стандартная ошибка команды, разделенная на строки. Возвращается: всегда Пример: `[{"u'ls cannot access foo": "No such file or directory'"}, "u'ls \u2026'"]`
stdout строка	Стандартный вывод команды. Возвращается: всегда Пример: `"Clustering node rabbit@slave1 with rabbit@master \u2026"`
stdout_lines список / элементы=строка	Стандартный вывод команды, разделенный на строки. Возвращается: всегда Пример: `["u'Clustering node rabbit@slave1 with rabbit@master \u2026'"]`

Авторы

Команда Ansible Core
Майкл ДеХан

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/shell_module.html