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

Примечание

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

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

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

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

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

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

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

Использует Docker Compose для запуска или остановки служб.

Требования

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

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

Параметры

Параметр	Комментарии
api_version псевдонимы: docker_api_version строка	Версия Docker API, работающего на хосте Docker. По умолчанию используется последняя версия API, поддерживаемая этой коллекцией и службой Docker. Если значение не указано в задаче, вместо него будет использовано значение переменной окружения `DOCKER_API_VERSION`. Если переменная окружения не задана, будет использовано значение по умолчанию. По умолчанию: `"auto"`
assume_yes логическое значение добавлено в community.docker 4.5.0	Если значение равно `assume_yes=true`, передать `-y`/`--yes`, чтобы считать ответом на все запросы «да» и выполнить команду в неинтерактивном режиме. Сейчас запрос появляется, когда том, не соответствующий требованиям, нужно создать заново. Значение `assume_yes=false` приводит к ответу «нет», и существующий том будет повторно использован. Этот параметр доступен только в Docker Compose 2.32.0 или новее. Варианты: `false` ← (по умолчанию) `true`
build строка	Нужно ли собирать образы перед запуском контейнеров. Используется при выполнении `docker compose up`. `always` всегда выполняет сборку перед запуском контейнеров. Эквивалентно параметру `--build` команды `docker compose up`. `never` никогда не выполняет сборку перед запуском контейнеров. Эквивалентно параметру `--no-build` команды `docker compose up`. `policy` использует политику, заданную в файле Compose. Варианты: `"always"` `"never"` `"policy"` ← (по умолчанию)
ca_path псевдонимы: ca_cert, tls_ca_cert, cacert_path путь	Используйте сертификат ЦС для проверки сервера, указав путь к файлу сертификата ЦС. Если значение не указано в задаче, а переменная окружения `DOCKER_CERT_PATH` задана, будет использован файл `ca.pem` из каталога, указанного в переменной окружения `DOCKER_CERT_PATH`.
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`.
definition словарь добавлено в community.docker 3.9.0	Файл Compose с описанием одной или нескольких служб, сетей и томов. Несовместим с `project_src` и `files`. Необходимо указать один из параметров: `project_src` или `definition`. Если этот параметр указан, для модуля должен быть доступен PyYAML, а также необходимо указать `project_name`. Обратите внимание, что при использовании этого параметра будет создан временный каталог, который затем будет удален.
dependencies логическое значение	Если `state` равно `present` или `restarted`, указывает, включать ли связанные службы. Варианты: `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_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`.
ignore_build_events логическое значение добавлено в community.docker 4.2.0	Игнорирует события сборки образов при определении изменений. Если `state=present` и `ignore_build_events=true`, а также `build=always`, пересборка, не вызывающая перезапуск контейнера, больше не приводит к `changed=true`. Обратите внимание, что Docker Compose 2.31.0 — первая версия Compose 2.x, которая генерирует события сборки. В более ранних версиях поведение всегда соответствует `ignore_build_events=true`. Варианты: `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`.
pull строка	Нужно ли загружать образы перед запуском. Используется при выполнении `docker compose up`. `always` обеспечивает загрузку образов в любом случае, даже если они уже есть в службе Docker. `missing` загружает образы, только если их нет в службе Docker. `never` никогда не загружает образы. Если их нет, модуль завершится с ошибкой при попытке создать необходимые контейнеры. `policy` использует значение `pull_policy`, заданное для службы в файле Compose, чтобы определить нужное действие. Варианты: `"always"` `"missing"` `"never"` `"policy"` ← (по умолчанию)
recreate строка	По умолчанию контейнеры создаются заново, если их конфигурация отличается от описания службы. Значение `never` игнорирует различия в конфигурации и оставляет существующие контейнеры без изменений. Значение `always` принудительно пересоздает все существующие контейнеры. Варианты: `"always"` `"never"` `"auto"` ← (по умолчанию)
remove_images строка	Используйте вместе с `state=absent`, чтобы удалить все образы или только локальные образы. Варианты: `"all"` `"local"`
remove_orphans логическое значение	Удалить контейнеры служб, не определенных в файле Compose. Варианты: `false` ← (по умолчанию) `true`
remove_volumes логическое значение	Используйте вместе с `state=absent`, чтобы удалить тома данных. Варианты: `false` ← (по умолчанию) `true`
renew_anon_volumes логическое значение добавлено в community.docker 4.0.0	Пересоздавать анонимные тома вместо повторного использования томов из предыдущих контейнеров. `true` эквивалентно параметру `--renew-anon-volumes` команды `docker compose up`. Варианты: `false` ← (по умолчанию) `true`
scale словарь добавлено в community.docker 3.7.0	Задает масштаб служб при выполнении `docker compose up`. Укажите словарь пар «ключ/значение», где ключ — имя службы, а значение — целое число контейнеров.
services список / элементы=строка	Указывает подмножество служб, к которым следует применить действие.
state строка	Требуемое состояние проекта. `present` эквивалентно выполнению `docker compose up`. `stopped` эквивалентно выполнению `docker compose stop`. `absent` эквивалентно выполнению `docker compose down`. `restarted` эквивалентно выполнению `docker compose restart`. Варианты: `"absent"` `"stopped"` `"restarted"` `"present"` ← (по умолчанию)
timeout целое число	Время ожидания в секундах при остановке контейнеров в подключенном режиме или если контейнеры уже запущены.
tls логическое значение	Защитить соединение с API с помощью TLS без проверки подлинности сервера хоста Docker. Обратите внимание: если для `validate_certs` также задано значение `true`, оно будет иметь приоритет. Если значение не указано в задаче, вместо него будет использовано значение переменной окружения `DOCKER_TLS`. Если переменная окружения не задана, будет использовано значение по умолчанию. Варианты: `false` ← (по умолчанию) `true`
tls_hostname строка	При проверке подлинности сервера хоста Docker укажите ожидаемое имя сервера. Если значение не указано в задаче, вместо него будет использовано значение переменной окружения `DOCKER_TLS_HOSTNAME`. Если переменная окружения не задана, будет использовано значение по умолчанию.
validate_certs псевдонимы: tls_verify логическое значение	Защитить соединение с API с помощью TLS и проверить подлинность сервера хоста Docker. Если значение не указано в задаче, вместо него будет использовано значение переменной окружения `DOCKER_TLS_VERIFY`. Если переменная окружения не задана, будет использовано значение по умолчанию. Варианты: `false` ← (по умолчанию) `true`
wait логическое значение добавлено в community.docker 3.8.0	При выполнении `docker compose up` передать `--wait`, чтобы дождаться запуска служб и перехода в состояние готовности. Время ожидания можно задать параметром `wait_timeout`. Варианты: `false` ← (по умолчанию) `true`
wait_timeout целое число добавлено в community.docker 3.8.0	Если `wait=true`, ждать не дольше указанного количества секунд.

Атрибуты

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

Примечания

Примечание

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

См. также

community.docker.docker_compose_v2_pull: Загрузить проект Docker Compose.

Примеры

---
# Examples use the django example at https://docs.docker.com/compose/django. Follow it to create the
# flask directory

- name: Run using a project directory
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Tear down existing services
      community.docker.docker_compose_v2:
        project_src: flask
        state: absent

    - name: Create and start services
      community.docker.docker_compose_v2:
        project_src: flask
      register: output

    - name: Show results
      ansible.builtin.debug:
        var: output

    - name: Run `docker compose up` again
      community.docker.docker_compose_v2:
        project_src: flask
      register: output

    - name: Show results
      ansible.builtin.debug:
        var: output

    - ansible.builtin.assert:
        that: not output.changed

    - name: Stop all services
      community.docker.docker_compose_v2:
        project_src: flask
        state: stopped
      register: output

    - name: Show results
      ansible.builtin.debug:
        var: output

    - name: Verify that web and db services are not running
      ansible.builtin.assert:
        that:
          - web_container.State != 'running'
          - db_container.State != 'running'
      vars:
        web_container: >-
          {{ output.containers | selectattr("Service", "equalto", "web") | first }}
        db_container: >-
          {{ output.containers | selectattr("Service", "equalto", "db") | first }}

    - name: Restart services
      community.docker.docker_compose_v2:
        project_src: flask
        state: restarted
      register: output

    - name: Show results
      ansible.builtin.debug:
        var: output

    - name: Verify that web and db services are running
      ansible.builtin.assert:
        that:
          - web_container.State == 'running'
          - db_container.State == 'running'
      vars:
        web_container: >-
          {{ output.containers | selectattr("Service", "equalto", "web") | first }}
        db_container: >-
          {{ output.containers | selectattr("Service", "equalto", "db") | first }}

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

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

Ключ	Описание
actions list / elements=dictionary	Список выполненных действий. Возвращается: success
id string	Идентификатор изменённого ресурса. Возвращается: success Пример: `"container"`
status string	Произошедшее изменение статуса. Возвращается: success Возможные значения: `"Starting"` `"Exiting"` `"Restarting"` `"Creating"` `"Stopping"` `"Killing"` `"Removing"` `"Recreating"` `"Pulling"` `"Building"` Пример: `"Creating"`
what string	Тип изменённого ресурса. Возвращается: success Возможные значения: `"container"` `"image"` `"network"` `"service"` `"unknown"` `"volume"` Пример: `"container"`
containers list / elements=dictionary	Список контейнеров, связанных со службой. Возвращается: success
Command any	Команда контейнера. Возвращается: success
CreatedAt string	Время создания контейнера. Возвращается: success Пример: `"2024-01-02 12:20:41 +0100 CET"`
ExitCode integer	Код завершения контейнера. Возвращается: success
Health any	Проверка состояния контейнера. Возвращается: success
ID string	Идентификатор контейнера. Возвращается: success Пример: `"44a7d607219a60b7db0a4817fb3205dce46e91df2cb4b78a6100b6e27b0d3135"`
Image string	Образ контейнера. Возвращается: success
Labels dictionary	Метки этого контейнера. Возвращается: success
LocalVolumes string	Количество локальных томов. Возвращается: success
Mounts string	Точки монтирования. Возвращается: success
Name string	Основное имя контейнера. Возвращается: success
Names list / elements=string	Список имён контейнера. Возвращается: success
Networks list / elements=string	Список сетей, подключённых к этому контейнеру. Возвращается: success
Ports string	Список сопоставлений портов в виде строки. Возвращается: success
Publishers list / elements=dictionary	Список назначений портов. Возвращается: success
Protocol string	Протокол. Возвращается: success Возможные значения: `"tcp"` `"udp"`
PublishedPort integer	Опубликованный порт. Возвращается: success
TargetPort integer	Порт контейнера, на который перенаправляется опубликованный порт. Возвращается: success
URL string	Интерфейс, к которому привязан порт. Возвращается: success
RunningFor string	Время работы контейнера. Возвращается: success
Service string	Имя службы. Возвращается: success
Size string	Размер контейнера. Возвращается: success Пример: `"0B"`
State string	Состояние контейнера. Возвращается: success Пример: `"running"`
Status string	Статус контейнера. Возвращается: success Пример: `"Up About a minute"`
images list / elements=dictionary	Список образов, связанных со службой. Возвращается: success
ContainerName string	Имя контейнера, в котором используется этот образ. Возвращается: success
ID string	Идентификатор образа. Возвращается: success Пример: `"sha256:c8bccc0af9571ec0d006a43acb5a8d08c4ce42b6cc7194dd6eb167976f501ef1"`
Repository string	Репозиторий, к которому относится этот образ. Возвращается: success
Size integer	Размер образа в байтах. Возвращается: success
Tag string	Тег образа. Возвращается: success

Авторы

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_module.html