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

Примечание

Этот модуль входит в коллекцию community.docker (версия 3.13.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"`
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 путь	Использовать сертификат CA при проверке сервера, указав путь к файлу сертификата CA. Если значение не указано в задаче, а переменная среды `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 list / elements=path added in community.docker 3.7.0	Список имен файлов Compose относительно `project_src` для использования вместо основного файла Compose (`compose.yml`, `compose.yaml`, `docker-compose.yml`, или `docker-compose.yaml`). Файлы загружаются и объединяются в указанном порядке. Взаимоисключающий с `definition`.
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`.
pull string	Загружать ли образы перед запуском. Используется при запуске `docker compose up`. `always` гарантирует, что образы всегда будут загружены, даже если уже присутствуют в демоне Docker. `missing` загружает их только в том случае, если они отсутствуют в демоне Docker. `never` никогда не загружает образы. Если они отсутствуют, модуль завершится с ошибкой при попытке создать контейнеры, которые их требуют. `policy` использует `pull_policy` файла Compose, определенный для сервиса, чтобы определить, что делать. Варианты: `"always"` `"missing"` `"never"` `"policy"` ← (по умолчанию)
recreate string	По умолчанию контейнеры будут пересозданы, когда их конфигурация отличается от определения сервиса. Установка в `never` игнорирует различия в конфигурации и оставляет существующие контейнеры без изменений. Установка в `always` принудительно пересоздает все существующие контейнеры. Варианты: `"always"` `"never"` `"auto"` ← (по умолчанию)
remove_images string	Используйте с `state=absent` для удаления всех образов или только локальных образов. Варианты: `"all"` `"local"`
remove_orphans boolean	Удаляет контейнеры для сервисов, не определенных в файле Compose. Варианты: `false` ← (по умолчанию) `true`
remove_volumes boolean	Используйте с `state=absent` для удаления томов данных. Варианты: `false` ← (по умолчанию) `true`
scale dictionary added in community.docker 3.7.0	Определяет, как масштабировать сервисы при запуске `docker compose up`. Укажите словарь пар ключ/значение, где ключ — имя сервиса, а значение — целое число, указывающее количество контейнеров.
services list / elements=string	Указывает подмножество сервисов, которые нужно использовать.
state string	Требуемое состояние проекта. `present` эквивалентно запуску `docker compose up`. `stopped` эквивалентно запуску `docker compose stop`. `absent` эквивалентно запуску `docker compose down`. `restarted` эквивалентно запуску `docker compose restart`. Варианты: `"absent"` `"stopped"` `"restarted"` `"present"` ← (по умолчанию)
timeout integer	Таймаут в секундах для остановки контейнера при подключении или когда контейнеры уже запущены.
tls boolean	Обеспечивает безопасное соединение с API с помощью TLS без проверки подлинности сервера хоста Docker. Обратите внимание, что если `validate_certs` также установлен в `true`, он будет иметь приоритет. Если значение не указано в задаче, вместо него будет использовано значение переменной окружения `DOCKER_TLS`. Если переменная окружения не установлена, будет использовано значение по умолчанию. Варианты: `false` ← (по умолчанию) `true`
tls_hostname string	При проверке подлинности сервера хоста Docker укажите ожидаемое имя сервера. Если значение не указано в задаче, вместо него будет использовано значение переменной окружения `DOCKER_TLS_HOSTNAME`. Если переменная окружения не установлена, будет использовано значение по умолчанию.

validate_certs aliases: tls_verify boolean	Защитите соединение с API, используя TLS и проверяя подлинность сервера хоста Docker. Если значение не указано в задаче, будет использовано значение переменной среды `DOCKER_TLS_VERIFY` вместо этого. Если переменная среды не установлена, будет использовано значение по умолчанию. Варианты: `false` ← (по умолчанию) `true`
wait boolean added in community.docker 3.8.0	При запуске `docker compose up`, передайте `--wait`, чтобы подождать, пока службы будут запущены/работоспособны. Таймаут может быть задан с помощью параметра `wait_timeout`. Варианты: `false` ← (по умолчанию) `true`
wait_timeout integer added in 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`).

Примечания

Примечание

Плагин 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: Управление многоконтейнерными приложениями Docker с помощью Docker Compose V1.
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 список / элементы=словарь	Список действий, которые были применены. Возвращаемое значение: успех
id строка	Идентификатор ресурса, который был изменён. Возвращаемое значение: успех Пример: `"container"`
status строка	Произошедшее изменение статуса. Возвращаемое значение: успех Может возвращать только: `"Starting"` `"Exiting"` `"Restarting"` `"Creating"` `"Stopping"` `"Killing"` `"Removing"` `"Recreating"` `"Pulling"` `"Building"` Пример: `"Creating"`
what строка	Тип изменённого ресурса. Возвращаемое значение: успех Может возвращать только: `"container"` `"image"` `"network"` `"service"` `"unknown"` `"volume"` Пример: `"container"`
containers список / элементы=словарь	Список контейнеров, связанных со службой. Возвращаемое значение: успех
Command любой	Команда контейнера. Возвращаемое значение: успех
CreatedAt строка	Отметка времени создания контейнера. Возвращаемое значение: успех Пример: `"2024-01-02 12:20:41 +0100 CET"`
ExitCode целое число	Код завершения контейнера. Возвращаемое значение: успех
Health любой	Проверка работоспособности контейнера. Возвращаемое значение: успех
ID строка	Идентификатор контейнера. Возвращаемое значение: успех Пример: `"44a7d607219a60b7db0a4817fb3205dce46e91df2cb4b78a6100b6e27b0d3135"`
Image строка	Изображение контейнера. Возвращаемое значение: успех
Labels словарь	Метки для этого контейнера. Возвращаемое значение: успех
LocalVolumes строка	Количество локальных томов. Возвращаемое значение: успех
Mounts строка	Точки монтирования. Возвращаемое значение: успех
Name строка	Основное имя контейнера. Возвращаемое значение: успех
Names список / элементы=строка	Список имён контейнера. Возвращаемое значение: успех
Networks список / элементы=строка	Список сетей, подключённых к контейнеру. Возвращаемое значение: успех
Ports строка	Список назначений портов в виде строки. Возвращаемое значение: успех
Publishers список / элементы=словарь	Список назначений портов. Возвращаемое значение: успех

Протокол строка	Протокол. Возвращаемое значение: успех Может возвращать только: `"tcp"` `"udp"`
PublishedPort целое число	Порт, который опубликован. Возвращаемое значение: успех
TargetPort целое число	Порт контейнера, к которому сопоставляется опубликованный порт. Возвращаемое значение: успех
URL строка	Интерфейс, к которому привязан порт. Возвращаемое значение: успех
RunningFor строка	Время работы контейнера. Возвращаемое значение: успех
Сервис строка	Имя сервиса. Возвращаемое значение: успех
Размер строка	Размер контейнера. Возвращаемое значение: успех Пример: `"0B"`
Состояние строка	Состояние контейнера. Возвращаемое значение: успех Пример: `"running"`
Статус строка	Статус контейнера. Возвращаемое значение: успех Пример: `"Up About a minute"`
изображения список / элементы=словарь	Список изображений, связанных со службой. Возвращаемое значение: успех
Имя контейнера строка	Имя контейнера, использующего это изображение. Возвращаемое значение: успех
ИД строка	ИД изображения. Возвращаемое значение: успех Пример: `"sha256:c8bccc0af9571ec0d006a43acb5a8d08c4ce42b6cc7194dd6eb167976f501ef1"`
Репозиторий строка	Репозиторий, к которому принадлежит это изображение. Возвращаемое значение: успех
Размер целое число	Размер изображения в байтах. Возвращаемое значение: успех
Тег строка	Тег изображения. Возвращаемое значение: успех

Авторы

Felix Fontein (@felixfontein)

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

© 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/community/docker/docker_compose_v2_module.html