Модуль community.docker.docker_compose_v2_run — запуск команды в новом контейнере службы Compose

Примечание

Этот модуль входит в коллекцию community.docker (версия 5.2.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install community.docker. Для использования этого модуля требуются дополнительные компоненты; подробную информацию см. в разделе Требования.

Чтобы использовать модуль в плейбуке, укажите: community.docker.docker_compose_v2_run.

Добавлено в community.docker 3.13.0

Краткое описание
Требования
Параметры
Атрибуты
Примечания
См. также
Примеры
Возвращаемые значения

Краткое описание

Использует Docker Compose для запуска команды в новом контейнере службы.
Этот модуль инкапсулирует docker compose run.

Требования

На узле, на котором выполняется этот модуль, должны быть установлены следующие компоненты.

Docker CLI с плагином Docker Compose версии 2.18.0 или новее
PyYAML, если используется definition

Параметры

Параметр	Комментарии
api_version aliases: docker_api_version string	Версия API Docker, работающего на хосте Docker. По умолчанию используется последняя версия API, поддерживаемая этой коллекцией и демоном Docker. Если значение не указано в задаче, вместо него будет использоваться значение переменной среды `DOCKER_API_VERSION`. Если переменная среды не задана, будет использоваться значение по умолчанию. По умолчанию: `"auto"`
argv list / elements=string	Команда для выполнения. Поскольку это список аргументов, кавычки не требуются. `argv` и `command` взаимоисключают друг друга.
build boolean	Собрать образ перед запуском контейнера. Обратите внимание, что сборка может добавить информацию в `stdout` или `stderr`. Возможные значения: `false` ← (по умолчанию) `true`
ca_path aliases: ca_cert, tls_ca_cert, cacert_path path	Для проверки сервера используйте сертификат CA, указав путь к файлу сертификата CA. Если значение не указано в задаче, а переменная среды `DOCKER_CERT_PATH` задана, будет использоваться файл `ca.pem` из каталога, указанного в переменной среды `DOCKER_CERT_PATH`.
cap_add list / elements=string	Возможности Linux, которые нужно добавить контейнеру.
cap_drop list / elements=string	Возможности Linux, которые нужно удалить у контейнера.
chdir string	Каталог, в котором будет выполняться команда.
check_files_existing boolean добавлено в community.docker 3.9.0	Если задано значение `false`, модуль не будет проверять, существует ли один из файлов `compose.yaml`, `compose.yml`, `docker-compose.yaml` или `docker-compose.yml` в `project_src`, если `files` не указан. Это может быть полезно, если для настройки другого имени файла используются файлы среды с `COMPOSE_FILE`. В настоящее время модуль не проверяет наличие `COMPOSE_FILE` в файлах среды или текущей среде. Возможные значения: `false` `true` ← (по умолчанию)
cleanup boolean	Автоматически удалять контейнер после его завершения. Соответствует параметру `--rm` команды `docker compose run`. Возможные значения: `false` ← (по умолчанию) `true`
cli_context string	Контекст Docker CLI, который следует использовать. Взаимоисключающий параметр с `docker_host`.
client_cert aliases: tls_client_cert, cert_path path	Путь к файлу сертификата TLS клиента. Если значение не указано в задаче, а переменная среды `DOCKER_CERT_PATH` задана, будет использоваться файл `cert.pem` из каталога, указанного в переменной среды `DOCKER_CERT_PATH`.
client_key aliases: tls_client_key, key_path path	Путь к файлу ключа TLS клиента. Если значение не указано в задаче, а переменная среды `DOCKER_CERT_PATH` задана, будет использоваться файл `key.pem` из каталога, указанного в переменной среды `DOCKER_CERT_PATH`.
command string	Команда для выполнения. `argv` и `command` взаимоисключают друг друга.
definition dictionary добавлено в community.docker 3.9.0	Файл Compose с описанием одной или нескольких служб, сетей и томов. Взаимоисключающий параметр с `project_src` и `files`. Необходимо указать один из параметров: `project_src` или `definition`. Если этот параметр указан, модулю должен быть доступен PyYAML, а также необходимо указать `project_name`. Обратите внимание, что при использовании этого параметра будет создан временный каталог, который затем будет удален.
detach boolean	Определяет, выполнять ли команду синхронно (`detach=false`, по умолчанию) или асинхронно (`detach=true`). Если задано значение `true`, параметр `stdin` указывать нельзя, а возвращаемые значения `stdout`, `stderr` и `rc` не возвращаются. Вместо них возвращается значение `container_id`. Возможные значения: `false` ← (по умолчанию) `true`
docker_cli path	Путь к Docker CLI. Если не указан, Docker CLI будет найден в `PATH`.
docker_host aliases: docker_url string	URL или путь к сокету Unix, используемый для подключения к API Docker. Для подключения к удаленному хосту укажите строку TCP-подключения. Например, `tcp://192.0.2.23:2376`. Если для шифрования подключения используется TLS, модуль автоматически заменит `tcp` в URL подключения на `https`. Если значение не указано в задаче, вместо него будет использоваться значение переменной среды `DOCKER_HOST`. Если переменная среды не задана, будет использоваться значение по умолчанию. Взаимоисключающий параметр с `cli_context`. Если не указаны ни `docker_host`, ни `cli_context`, используется значение `unix:///var/run/docker.sock`.
entrypoint string	Переопределить точку входа образа контейнера.
env dictionary	Словарь переменных среды и соответствующих значений, передаваемых команде, выполняемой внутри контейнера. Значения, которые парсер YAML может интерпретировать как числа, логические значения или другие типы данных, необходимо заключать в кавычки (например, `"true"`), чтобы избежать потери данных. Обратите внимание: если вы передаете значения с помощью шаблонов Jinja2, например `"{{ value }}"`, необходимо добавить `\| string`, чтобы Ansible не преобразовал строки, такие как `"true"`, обратно в логические значения. Правильный способ — использовать `"{{ value \| string }}"`.
env_files list / elements=path	По умолчанию файлы среды загружаются из файла `.env`, расположенного непосредственно в каталоге `project_src`. С помощью `env_files` можно указать путь к одному или нескольким пользовательским файлам среды. Путь указывается относительно каталога `project_src`.
files list / elements=path добавлено в community.docker 3.7.0	Список имен файлов Compose относительно `project_src`, которые будут использоваться вместо основного файла Compose (`compose.yml`, `compose.yaml`, `docker-compose.yml` или `docker-compose.yaml`). Файлы загружаются и объединяются в указанном порядке. Взаимоисключающий параметр с `definition`.
interactive boolean	Оставлять ли STDIN открытым, даже если он не подключен. Возможные значения: `false` `true` ← (по умолчанию)
labels list / elements=string	Добавить или переопределить метки контейнера.
name string	Назначить контейнеру имя.
no_deps boolean	Не запускать связанные службы. Возможные значения: `false` ← (по умолчанию) `true`
profiles list / elements=string	Список профилей, которые нужно включить при запуске служб. Эквивалентно `docker compose --profile`.
project_name string	Указать имя проекта. Если оно не задано, имя проекта определяется по базовому имени `project_src`. Обязательный параметр, если указан `definition`.
project_src path	Путь к каталогу, содержащему файл Compose (`compose.yml`, `compose.yaml`, `docker-compose.yml` или `docker-compose.yaml`). Если указан `files`, поиск этих файлов будет выполняться в этом каталоге. Взаимоисключающий параметр с `definition`. Необходимо указать один из параметров: `project_src` или `definition`.
publish list / elements=string	Опубликовать порт или порты контейнера на хосте.
quiet_pull boolean	Загружать без вывода сведений о ходе выполнения. Обратите внимание, что загрузка может добавить информацию в `stdout` или `stderr`. Возможные значения: `false` ← (по умолчанию) `true`
remove_orphans boolean	Удалить контейнеры служб, не определенных в файле Compose. Возможные значения: `false` ← (по умолчанию) `true`
service string / required	Служба, в которой будет выполняться команда.
service_ports boolean	Выполнить команду, включив все порты службы и сопоставив их с портами хоста. Возможные значения: `false` ← (по умолчанию) `true`
stdin string	Задать стандартный ввод команды непосредственно указанным значением. Можно использовать только при условии `detach=false`.
stdin_add_newline boolean	Если задано значение `true`, к `stdin` добавляется символ перевода строки. Возможные значения: `false` `true` ← (по умолчанию)
strip_empty_ends boolean	Удалять пустые строки в конце stdout/stderr в результате. Возможные значения: `false` `true` ← (по умолчанию)
tls boolean	Защитить подключение к API с помощью TLS без проверки подлинности сервера хоста Docker. Обратите внимание: если для `validate_certs` также задано значение `true`, этот параметр имеет приоритет. Если значение не указано в задаче, вместо него будет использоваться значение переменной среды `DOCKER_TLS`. Если переменная среды не задана, будет использоваться значение по умолчанию. Возможные значения: `false` ← (по умолчанию) `true`
tls_hostname string	При проверке подлинности сервера хоста Docker укажите ожидаемое имя сервера. Если значение не указано в задаче, вместо него будет использоваться значение переменной среды `DOCKER_TLS_HOSTNAME`. Если переменная среды не задана, будет использоваться значение по умолчанию.
tty boolean	Выделять ли TTY. Возможные значения: `false` `true` ← (по умолчанию)
use_aliases boolean	Использовать сетевые `useAliases` службы в сети или сетях, к которым подключается контейнер. Возможные значения: `false` ← (по умолчанию) `true`
user string	Если указано, пользователь, от имени которого будет выполняться эта команда.
validate_certs aliases: tls_verify boolean	Защитить подключение к API с помощью TLS и проверить подлинность сервера хоста Docker. Если значение не указано в задаче, вместо него будет использоваться значение переменной среды `DOCKER_TLS_VERIFY`. Если переменная среды не задана, будет использоваться значение по умолчанию. Возможные значения: `false` ← (по умолчанию) `true`
volumes list / elements=string	Подключить один или несколько томов.

Атрибуты

Атрибут	Поддержка	Описание
action_group	Группы действий: community.docker.docker, docker	Используйте `group/docker` или `group/community.docker.docker` в `module_defaults`, чтобы задать значения по умолчанию для этого модуля.
check_mode	Поддержка: нет	Может выполняться в режиме `check_mode` и возвращать прогноз статуса изменений без изменения целевого объекта.
diff_mode	Поддержка: нет	В режиме diff будут возвращены сведения об изменениях (или о том, что, возможно, необходимо изменить в `check_mode`).
idempotent	Поддержка: Н/Д Идемпотентность выполняемой команды зависит от самой команды.	При повторном запуске с теми же аргументами вне режима проверки второй вызов указывает на отсутствие изменений. Предполагается, что система, которой управляет модуль или к которой он обращается, не изменилась существенным образом.

Примечания

Примечание

Если необходимо вычислить переменные окружения контейнера в command или argv, команду нужно передать оболочке, например command=/bin/sh -c "echo $ENV_VARIABLE". То же самое следует сделать, если вы хотите использовать шаблоны glob или другие возможности оболочки, такие как перенаправление.
Плагин CLI Docker Compose не имеет стабильного формата вывода (см., например, https://github.com/docker/compose/issues/10872), а для основных операций также отсутствует удобный для машин формат вывода. Модуль пытается решить эту проблему с помощью различных корректировок поведения, зависящих от версии, а также тестирования старых и новых версий плагина CLI Docker Compose. В настоящее время модуль тестируется с несколькими версиями плагина от 2.18.1 до 2.23.3. Точный список версий плагина будет меняться со временем. Новые выпуски плагина CLI Docker Compose могут в любой момент нарушить работу этого модуля.
Подключайтесь к демону Docker, передавая параметры в каждой задаче или задавая переменные окружения. Можно задать DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_TLS, DOCKER_TLS_VERIFY и DOCKER_TIMEOUT. Если вы используете Docker Machine, запустите поставляемый с продуктом скрипт настройки окружения. Он задаст эти переменные. Подробнее см. https://docs.docker.com/machine/reference/env/.
Этот модуль не использует Docker SDK for Python для взаимодействия с демоном Docker. Он напрямую вызывает программу CLI Docker.

См. также

community.docker.docker_compose_v2: Управление многоконтейнерными приложениями Docker с помощью плагина CLI Docker Compose.

Примеры

---
- name: Run a simple command (command)
  community.docker.docker_compose_v2_run:
    service: foo
    command: /bin/bash -c "ls -lah"
    chdir: /root
  register: result

- name: Print stdout
  ansible.builtin.debug:
    var: result.stdout

- name: Run a simple command (argv)
  community.docker.docker_compose_v2_run:
    service: foo
    argv:
      - /bin/bash
      - "-c"
      - "ls -lah > /dev/stderr"
    chdir: /root
  register: result

- name: Print stderr lines
  ansible.builtin.debug:
    var: result.stderr_lines

Возвращаемые значения

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

Ключ	Описание
container_id строка	Идентификатор созданного контейнера. Возвращается: при успехе и `detach=true`
rc целое число	Код завершения команды. Возвращается: при успехе и `detach=false` Пример: `0`
stderr строка	Вывод стандартного потока ошибок команды контейнера. Возвращается: при успехе и `detach=false`
stdout строка	Вывод стандартного потока вывода команды контейнера. Возвращается: при успехе и `detach=false`

Авторы

Felix Fontein (@felixfontein)

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

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/docker/docker_compose_v2_run_module.html