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

Примечание

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

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

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

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

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

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

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

Использует Docker Compose для запуска команды в контейнере сервиса.
Можно использовать для запуска разовых команд в контейнере существующего сервиса; модуль инкапсулирует docker compose exec.

Требования

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

Docker CLI с подключаемым модулем Docker Compose версии 2.18.0 или новее
PyYAML, если используется definition

Параметры

Параметр	Комментарии
api_version псевдонимы: docker_api_version строка	Версия Docker API, работающего на узле Docker. По умолчанию используется последняя версия API, поддерживаемая этой коллекцией и демоном Docker. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_API_VERSION`. Если переменная окружения не задана, будет использоваться значение по умолчанию. По умолчанию: `"auto"`
argv список / элементы=строка	Команда для выполнения. Поскольку это список аргументов, заключать их в кавычки не требуется. Необходимо указать ровно один из параметров `argv` или `command`.
ca_path псевдонимы: ca_cert, tls_ca_cert, cacert_path путь	Используйте сертификат центра сертификации для проверки сервера, указав путь к файлу сертификата центра сертификации. Если значение не указано в задаче, а переменная окружения `DOCKER_CERT_PATH` задана, будет использоваться файл `ca.pem` из каталога, указанного в переменной окружения `DOCKER_CERT_PATH`.
chdir строка	Каталог, в котором будет выполняться команда.
check_files_existing логическое значение добавлено в 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` ← (по умолчанию)
cli_context строка	Контекст Docker CLI, который следует использовать. Взаимоисключающий с `docker_host`.
client_cert псевдонимы: tls_client_cert, cert_path путь	Путь к файлу TLS-сертификата клиента. Если значение не указано в задаче, а переменная окружения `DOCKER_CERT_PATH` задана, будет использоваться файл `cert.pem` из каталога, указанного в переменной окружения `DOCKER_CERT_PATH`.
client_key псевдонимы: tls_client_key, key_path путь	Путь к файлу TLS-ключа клиента. Если значение не указано в задаче, а переменная окружения `DOCKER_CERT_PATH` задана, будет использоваться файл `key.pem` из каталога, указанного в переменной окружения `DOCKER_CERT_PATH`.
command строка	Команда для выполнения. Необходимо указать ровно один из параметров `argv` или `command`.
definition словарь добавлено в community.docker 3.9.0	Файл Compose с описанием одной или нескольких служб, сетей и томов. Взаимоисключающий с `project_src` и `files`. Необходимо указать один из параметров `project_src` и `definition`. Если этот параметр указан, для модуля должен быть доступен PyYAML, а также необходимо указать `project_name`. Обратите внимание, что при использовании этого параметра будет создан временный каталог, который затем будет удалён.
detach логическое значение	Следует ли выполнять команду синхронно (`detach=false`, по умолчанию) или асинхронно (`detach=true`). Если задано значение `true`, параметр `stdin` указывать нельзя, а возвращаемые значения `stdout`, `stderr` и `rc` не возвращаются. Варианты: `false` ← (по умолчанию) `true`
docker_cli путь	Путь к Docker CLI. Если он не указан, Docker CLI будет найден в `PATH`.
docker_host псевдонимы: docker_url строка	URL или путь к сокету Unix, используемый для подключения к Docker API. Для подключения к удалённому узлу укажите строку TCP-подключения. Например, `tcp://192.0.2.23:2376`. Если для шифрования подключения используется TLS, модуль автоматически заменит `tcp` в URL подключения на `https`. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_HOST`. Если переменная окружения не задана, будет использоваться значение по умолчанию. Взаимоисключающий с `cli_context`. Если не указан ни `docker_host`, ни `cli_context`, используется значение `unix:///var/run/docker.sock`.
env словарь	Словарь переменных окружения и соответствующих им значений, передаваемых команде, выполняемой внутри контейнера. Значения, которые парсер YAML может интерпретировать как числа, логические значения или другие типы, необходимо заключать в кавычки (например, `"true"`), чтобы избежать потери данных. Обратите внимание: если вы передаёте значения с помощью шаблонов Jinja2, например `"{{ value }}"`, необходимо добавить `\| string`, чтобы Ansible не преобразовал строки, такие как `"true"`, обратно в логические значения. Правильный вариант — использовать `"{{ value \| string }}"`.
env_files список / элементы=путь	По умолчанию файлы окружения загружаются из файла `.env`, расположенного непосредственно в каталоге `project_src`. Параметр `env_files` позволяет указать путь к одному или нескольким пользовательским файлам окружения. Путь указывается относительно каталога `project_src`.
files список / элементы=путь добавлено в community.docker 3.7.0	Список имён файлов Compose относительно `project_src`, используемых вместо основного файла Compose (`compose.yml`, `compose.yaml`, `docker-compose.yml` или `docker-compose.yaml`). Файлы загружаются и объединяются в указанном порядке. Взаимоисключающий с `definition`.
index целое число	Индекс контейнера, в котором нужно выполнить команду, если у службы несколько реплик.
privileged логическое значение	Следует ли предоставить процессу расширенные привилегии. Варианты: `false` ← (по умолчанию) `true`
profiles список / элементы=строка	Список профилей, которые нужно включить при запуске служб. Эквивалентен `docker compose --profile`.
project_name строка	Задаёт имя проекта. Если оно не указано, имя проекта берётся из базового имени `project_src`. Обязателен, если указан `definition`.
project_src путь	Путь к каталогу, содержащему файл Compose (`compose.yml`, `compose.yaml`, `docker-compose.yml` или `docker-compose.yaml`). Если указан `files`, эти файлы будут искаться в этом каталоге. Взаимоисключающий с `definition`. Необходимо указать один из параметров `project_src` и `definition`.
service строка / обязательный	Служба, в контейнере которой нужно выполнить команду.
stdin строка	Задать стандартный ввод команды напрямую указанным значением. Можно использовать только в том случае, если `detach=false`.
stdin_add_newline логическое значение	Если задано значение `true`, к `stdin` добавляется символ новой строки. Варианты: `false` `true` ← (по умолчанию)
strip_empty_ends логическое значение	Удалять пустые строки в конце stdout/stderr результата. Варианты: `false` `true` ← (по умолчанию)
tls логическое значение	Защитить соединение с API с помощью TLS без проверки подлинности сервера узла Docker. Обратите внимание: если для `validate_certs` также задано значение `true`, оно будет иметь приоритет. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_TLS`. Если переменная окружения не задана, будет использоваться значение по умолчанию. Варианты: `false` ← (по умолчанию) `true`
tls_hostname строка	При проверке подлинности сервера узла Docker укажите ожидаемое имя сервера. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_TLS_HOSTNAME`. Если переменная окружения не задана, будет использоваться значение по умолчанию.
tty логическое значение	Следует ли выделить TTY. Варианты: `false` `true` ← (по умолчанию)
user строка	Если задано, пользователь, от имени которого выполняется команда.
validate_certs псевдонимы: tls_verify логическое значение	Защитить соединение с API с помощью TLS и проверить подлинность сервера узла Docker. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_TLS_VERIFY`. Если переменная окружения не задана, будет использоваться значение по умолчанию. Варианты: `false` ← (по умолчанию) `true`

Атрибуты

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

Примечания

Примечание

Если вам нужно вычислять переменные окружения контейнера в command или argv, необходимо передать команду через оболочку, например command=/bin/sh -c "echo $ENV_VARIABLE". То же самое нужно сделать, если вы хотите использовать шаблоны glob или другие возможности оболочки, например перенаправление.
У подключаемого модуля Docker Compose CLI нет стабильного формата вывода (см., например, https://github.com/docker/compose/issues/10872), а для основных операций нет и удобного для машинной обработки формата вывода. Модуль учитывает это с помощью различных корректировок поведения, зависящих от версии, и тестирования старых и новых версий подключаемого модуля Docker Compose CLI. В настоящее время модуль тестируется с несколькими версиями подключаемого модуля от 2.18.1 до 2.23.3. Точный список версий подключаемого модуля со временем изменится. Новые выпуски подключаемого модуля Docker Compose CLI в любой момент могут нарушить работу этого модуля.
Подключайтесь к демону 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. Он напрямую вызывает программу Docker CLI.

См. также

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

Примеры

---
- name: Run a simple command (command)
  community.docker.docker_compose_v2_exec:
    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_exec:
    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

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

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

Ключ	Описание
rc integer	Код завершения команды. Возвращается: при успехе и `detach=false` Пример: `0`
stderr string	Стандартный поток ошибок команды контейнера. Возвращается: при успехе и `detach=false`
stdout string	Стандартный вывод команды контейнера. Возвращается: при успехе и `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_exec_module.html