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

Примечание

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

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

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

Чтобы использовать его в книге задач, укажите: community.docker.docker_compose.

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

УСТАРЕЛО

Удалено в:: версии 4.0.0
Почему:: Этот модуль использует docker-compose v1, который достиг конца жизненного цикла в июле 2022 года.
Альтернатива:: Перейдите на community.docker.docker_compose_v2

Описание

Использует Docker Compose для запуска, остановки и масштабирования служб. Этот модуль требует docker-compose < 2.0.0. Для использования современного плагина Docker Compose CLI используйте модуль community.docker.docker_compose_v2.
Конфигурацию можно прочитать из файла docker-compose.yml или docker-compose.yaml или встрочить, используя опцию definition.
Подробности см. в примерах.
Поддерживает режим проверки.
Этот модуль назывался docker_service до Ansible 2.8. Использование не изменилось.

Требования

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

Docker API >= 1.25
Docker SDK для Python: Обратите внимание, что модуль Python docker-py был заменён на docker (подробнее см. здесь). Обратите внимание, что оба модуля *не должны* устанавливаться одновременно. Также обратите внимание, что при установке и последующем удалении одного из модулей другой может перестать работать, и потребуется его повторная установка.
Docker SDK для Python >= 1.8.0, < 7. Docker SDK для Python 7+ несовместим с docker-compose v1.
PyYAML >= 3.11
docker-compose >= 1.7.0, < 2.0.0

Параметры

Параметр	Комментарии
api_version aliases: docker_api_version string	Версия Docker API, работающего на Docker Host. По умолчанию используется последняя версия API, поддерживаемая Docker SDK для Python и демоном docker. Если значение не указано в задаче, вместо него будет использовано значение переменной среды `DOCKER_API_VERSION`. Если переменная среды не установлена, будет использовано значение по умолчанию. Default: `"auto"`
build boolean	Используйте с `state=present` для постоянной сборки образов перед запуском приложения. Аналогично запуску `docker-compose build` с параметром pull. Образы будут пересобраны только в том случае, если Docker обнаружит изменение в Dockerfile или содержимом каталога сборки. Используйте параметр `nocache` для игнорирования кэша образов при выполнении сборки. Если существующий образ заменен, службы, использующие этот образ, будут пересозданы, если только не `recreate=never`. Choices: `false` ← (default) `true`
ca_path aliases: ca_cert, tls_ca_cert, cacert_path path	Используйте сертификат центра сертификации при выполнении проверки сервера, указав путь к файлу сертификата центра сертификации. Если значение не указано в задаче и переменная среды `DOCKER_CERT_PATH` установлена, будет использоваться файл `ca.pem` из каталога, указанного в переменной среды `DOCKER_CERT_PATH`. Этот параметр назывался `ca_cert` и был переименован в `ca_path` в community.docker 3.6.0. Старое имя было добавлено как псевдоним и его все еще можно использовать.
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`.
debug boolean	Режим отладки Choices: `false` ← (default) `true`
definition dictionary	Файл Compose, описывающий одну или несколько служб, сетей и томов. Взаимоисключающий с `project_src` и `files`.
dependencies boolean	Когда `state` является `present`, укажите, следует ли включать связанные службы. Choices: `false` `true` ← (default)
docker_host aliases: docker_url string	URL или путь сокета Unix, используемый для подключения к Docker API. Для подключения к удаленному хосту укажите строку подключения TCP. Например, `tcp://192.0.2.23:2376`. Если для шифрования соединения используется TLS, модуль автоматически заменит `tcp` в URL подключения на `https`. Если значение не указано в задаче, вместо него будет использовано значение переменной среды `DOCKER_HOST`. Если переменная среды не установлена, будет использовано значение по умолчанию. Default: `"unix:///var/run/docker.sock"`
env_file path added in community.docker 1.9.0	По умолчанию файлы среды загружаются из файла `.env`, расположенного непосредственно в каталоге `project_src`. `env_file` можно использовать для указания пути к пользовательскому файлу среды. Путь указывается относительно каталога `project_src`. Требуется версия `docker-compose` 1.25.0 или выше. Примечание: версии `docker-compose` `<=1.28` загружают файл env из текущего рабочего каталога команды `docker-compose`, а не `project_src`.
files list / elements=path	Список имен файлов Compose относительно `project_src`. Переопределяет `docker-compose.yml` или `docker-compose.yaml`. Файлы загружаются и объединяются в указанном порядке.
hostname_check boolean	Проверять ли имя хоста демона Docker на соответствие имени, указанному в клиентском сертификате. Choices: `false` ← (default) `true`

nocache boolean	Использовать с опцией `build`, чтобы проигнорировать кэш во время сборки образа. Варианты: `false` ← (по умолчанию) `true`
profiles список / элементы=строка добавлен в community.docker 1.8.0	Список профилей для включения при запуске служб. Эквивалентно `docker-compose --profile`. Требуется версия `docker-compose` 1.28.0 или выше.
project_name строка	Укажите имя проекта. Если не указано, имя проекта берётся из базового имени `project_src`. Требуется, когда указан `definition`.
project_src путь	Путь к каталогу, содержащему файл `docker-compose.yml` или `docker-compose.yaml`. Взаимоисключительно с `definition`. Требуется, если не указан `definition`.
pull boolean	Использовать с `state=present`, чтобы всегда подтягивать образы перед запуском приложения. То же, что и выполнение `docker-compose pull`. При подтягивании нового образа, службы, использующие этот образ, будут пересозданы, если `recreate=never`. Варианты: `false` ← (по умолчанию) `true`
recreate строка	По умолчанию контейнеры будут пересозданы, если их конфигурация отличается от определения службы. Установка в `never` игнорирует различия в конфигурации и оставляет существующие контейнеры без изменений. Установка в `always` принудительно пересоздаёт все существующие контейнеры. Варианты: `"always"` `"never"` `"smart"` ← (по умолчанию)
remove_images строка	Использовать с `state=absent` для удаления всех образов или только локальных. Варианты: `"all"` `"local"`
remove_orphans boolean	Удалить контейнеры для служб, не определённых в файле Compose. Варианты: `false` ← (по умолчанию) `true`
remove_volumes boolean	Использовать с `state=absent` для удаления томов данных. Варианты: `false` ← (по умолчанию) `true`
restarted boolean	Использовать с `state=present` для перезапуска всех контейнеров, определённых в файле Compose. Если `services` определён, будут перезапущены только указанные там контейнеры. Варианты: `false` ← (по умолчанию) `true`
scale словарь	Когда `state` `present`, масштабировать службы. Укажите словарь пар "ключ-значение", где ключ - имя службы, а значение - целое число, представляющее количество контейнеров.
services список / элементы=строка	При `state` `present` запустить `docker-compose up` resp. `docker-compose stop` (с `stopped=true`) resp. `docker-compose restart` (с `restarted=true`) на подмножестве служб. Если пусто, что является значением по умолчанию, операция будет выполнена на всех службах, определённых в файле Compose (или встроенном `definition`).
ssl_version строка	Укажите допустимый номер версии SSL. Значение по умолчанию определяется модулем SSL Python. Если значение не указано в задаче, вместо этого будет использовано значение переменной окружения `DOCKER_SSL_VERSION`. Примечание: эта опция больше не поддерживается для Docker SDK for Python 7.0.0+. Указание её с Docker SDK for Python 7.0.0 или более поздней версией приведёт к ошибке.
state строка	Желаемое состояние проекта. Указание `present` равносильно запуску `docker-compose up` resp. `docker-compose stop` (с `stopped=true`) resp. `docker-compose restart` (с `restarted=true`). Указание `absent` равносильно запуску `docker-compose down`. Варианты: `"absent"` `"present"` ← (по умолчанию)
stopped boolean	Использовать с `state=present` для остановки всех контейнеров, определённых в файле Compose. Если `services` определён, будут остановлены только указанные там контейнеры. Требуется версия `docker-compose` 1.17.0 или выше для полной поддержки. Для более старых версий службы сначала запускаются, а затем останавливаются, когда служба должна быть создана как остановленная. Варианты: `false` ← (по умолчанию) `true`

timeout integer	Время ожидания в секундах для завершения контейнера при подключении или когда контейнеры уже запущены. По умолчанию `docker-compose` будет использовать время ожидания `10` секунд, если `default_grace_period` не определено для конкретной службы в `project_src`.
tls boolean	Защитить подключение к API с помощью TLS без проверки подлинности сервера Docker. Обратите внимание, что если `validate_certs` также установлено в `true`, оно будет иметь приоритет. Если значение не указано в задании, будет использовано значение переменной среды `DOCKER_TLS`. Если переменная среды не установлена, будет использовано значение по умолчанию. Варианты: `false` ← (по умолчанию) `true`
tls_hostname string	При проверке подлинности сервера Docker укажите ожидаемое имя сервера. Если значение не указано в задании, будет использовано значение переменной среды `DOCKER_TLS_HOSTNAME`. Если переменная среды не установлена, будет использовано значение по умолчанию. Обратите внимание, что данному параметру было установлено значение по умолчанию `localhost` в более ранних версиях. Оно было удалено в community.docker 3.0.0. Примечание: этот параметр больше не поддерживается для Docker SDK для Python 7.0.0+. Указание его с Docker SDK для Python 7.0.0 или более поздней версией приведет к ошибке.
use_ssh_client boolean added in community.docker 1.5.0	В настоящее время игнорируется для данного модуля, но в будущем может быть внезапно поддержан. Варианты: `false` ← (по умолчанию) `true`
validate_certs aliases: tls_verify boolean	Защитить подключение к 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`), при использовании режима diff.

Примечания

Примечание

Подключение к демону Docker путем предоставления параметров в каждом задании или путем определения переменных среды. Можно определить DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY и DOCKER_TIMEOUT. При использовании docker machine выполните скрипт, поставляемый с продуктом, который настраивает среду. Он установит эти переменные за вас. Более подробную информацию см. на странице https://docs.docker.com/machine/reference/env/.
При подключении к демону Docker с помощью TLS, возможно, потребуется установить дополнительные пакеты Python. Для Docker SDK для Python версии 2.4 или новее это можно сделать, установив docker[tls] с помощью ansible.builtin.pip.
Обратите внимание, что Docker SDK для Python позволяет указать путь к конфигурации Docker только для очень немногих функций. В общем случае он будет использовать $HOME/.docker/config.json, если переменная среды DOCKER_CONFIG не указана, и использовать $DOCKER_CONFIG/config.json в противном случае.
Этот модуль использует Docker SDK для Python для взаимодействия с демоном Docker.

См. также

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

Примеры

# 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:
        project_src: flask
        state: absent

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

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

    - name: Run `docker-compose up` again
      community.docker.docker_compose:
        project_src: flask
        build: false
      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:
        project_src: flask
        build: false
        stopped: true
      register: output

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

    - name: Verify that web and db services are not running
      ansible.builtin.assert:
        that:
          - "not output.services.web.flask_web_1.state.running"
          - "not output.services.db.flask_db_1.state.running"

    - name: Restart services
      community.docker.docker_compose:
        project_src: flask
        build: false
        restarted: true
      register: output

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

    - name: Verify that web and db services are running
      ansible.builtin.assert:
        that:
          - "output.services.web.flask_web_1.state.running"
          - "output.services.db.flask_db_1.state.running"

- name: Scale the web service to 2
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Scale the web service to two instances
      community.docker.docker_compose:
        project_src: flask
        scale:
          web: 2
      register: output

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

- name: Run with inline Compose file version 2
  # https://docs.docker.com/compose/compose-file/compose-file-v2/
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Remove flask project
      community.docker.docker_compose:
        project_src: flask
        state: absent

    - name: Start flask project with inline definition
      community.docker.docker_compose:
        project_name: flask
        definition:
          version: '2'
          services:
            db:
              image: postgres
            web:
              build: "{{ playbook_dir }}/flask"
              command: "python manage.py runserver 0.0.0.0:8000"
              volumes:
                - "{{ playbook_dir }}/flask:/code"
              ports:
                - "8000:8000"
              depends_on:
                - db
      register: output

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

    - name: Verify that the db and web services are running
      ansible.builtin.assert:
        that:
          - "output.services.web.flask_web_1.state.running"
          - "output.services.db.flask_db_1.state.running"

- name: Run with inline Compose file version 1
  # https://docs.docker.com/compose/compose-file/compose-file-v1/
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Remove flask project
      community.docker.docker_compose:
        project_src: flask
        state: absent

    - name: Start flask project with inline definition
      community.docker.docker_compose:
        project_name: flask
        definition:
            db:
              image: postgres
            web:
              build: "{{ playbook_dir }}/flask"
              command: "python manage.py runserver 0.0.0.0:8000"
              volumes:
                - "{{ playbook_dir }}/flask:/code"
              ports:
                - "8000:8000"
              links:
                - db
      register: output

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

    - name: Verify that web and db services are running
      ansible.builtin.assert:
        that:
          - "output.services.web.flask_web_1.state.running"
          - "output.services.db.flask_db_1.state.running"

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

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

Ключ	Описание
действия сложное	Предоставляет действия, которые необходимо выполнить для каждого сервиса, как определено compose. Возвращается: при проверке или `debug=true`
имя_сервиса сложное	Имя сервиса. Возвращается: всегда
действие список / элементы=строка	Дескриптивное имя действия, которое должно быть выполнено для контейнеров сервиса. Возвращается: всегда
id строка	Полный идентификатор контейнера Возвращается: всегда
имя строка	Имя контейнера Возвращается: всегда
короткий_id строка	Кратко обозначенный идентификатор контейнера Возвращается: всегда
сборка_изображения сложное	Предоставляет детали изображения, когда для сервиса создается новое изображение. Возвращается: при сборке изображения
id строка	Хеш изображения Возвращается: всегда
имя строка	Имя изображения Возвращается: всегда
скачанное_изображение сложное	Предоставляет детали изображения, когда для сервиса скачивается новое изображение. Возвращается: при скачивании изображения
id строка	Хеш изображения Возвращается: всегда
имя строка	Имя изображения Возвращается: всегда
сервисы сложное	Словарь, сопоставляющий имя сервиса со словарем контейнеров. Возвращается: успешно
имя_контейнера сложное	Имя контейнера. Формат `project_service_#`. Возвращается: успешно
cmd список / элементы=строка	Один или более команд, которые должны быть выполнены в контейнере. Возвращается: успешно Пример: `["postgres"]`
изображение строка	Имя изображения, из которого был создан контейнер. Возвращается: успешно Пример: `"postgres"`
метки словарь	Метаданные, назначенные контейнеру. Возвращается: успешно Пример: `{"...": null}`
сети список / элементы=словарь	Содержит словарь для каждой сети, членом которой является контейнер. Возвращается: успешно
псевдонимы список / элементы=строка	Псевдонимы, назначенные контейнеру сетью. Возвращается: успешно Пример: `["db"]`
globalIPv6 строка	IPv6-адрес, назначенный контейнеру. Возвращается: успешно Пример: `""`

globalIPv6PrefixLen целое число	Длина подсети IPv6. Возвращаемое значение: success Пример: `0`
IPAddress строка	IP-адрес, назначенный контейнеру. Возвращаемое значение: success Пример: `"172.17.0.2"`
IPPrefixLen целое число	Количество бит, используемых подсетью. Возвращаемое значение: success Пример: `16`
links список / элементы=строка	Список имён контейнеров, к которым связан этот контейнер. Возвращаемое значение: success
macAddress строка	MAC-адрес, назначенный виртуальной сетевой карте. Возвращаемое значение: success Пример: `"02:42:ac:11:00:02"`
state словарь	Информация о текущем состоянии контейнера. Возвращаемое значение: success
running логическое	Запущен ли контейнер с работающим процессом. Возвращаемое значение: success Пример: `true`
status строка	Описание состояния выполнения. Возвращаемое значение: success Пример: `"running"`

Статус

Этот модуль будет удалён в версии 4.0.0. [устаревший]
Для получения дополнительной информации см. УСТАРЕВШИЙ.

Авторы

Chris Houseknecht (@chouseknecht)

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

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