Модуль community.docker.docker_swarm_service — служба Docker Swarm

api_version

aliases: docker_api_version

string

Версия API Docker, работающего на хосте Docker.

По умолчанию используется последняя версия API, поддерживаемая Docker SDK for Python и демоном Docker.

Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения DOCKER_API_VERSION. Если переменная окружения не задана, будет использоваться значение по умолчанию.

По умолчанию: "auto"

args

list / elements=string

Список аргументов, передаваемых контейнеру.

Соответствует параметру ARG в docker service create.

ca_path

aliases: ca_cert, tls_ca_cert, cacert_path

path

Используйте сертификат CA для проверки сервера, указав путь к файлу сертификата CA.

Если значение не указано в задаче, а переменная окружения DOCKER_CERT_PATH задана, будет использоваться файл ca.pem из каталога, указанного в переменной окружения DOCKER_CERT_PATH.

Этот параметр назывался ca_cert и был переименован в ca_path в community.docker 3.6.0. Старое имя добавлено в качестве псевдонима, его по-прежнему можно использовать.

cap_add

list / elements=string

добавлено в community.docker 2.2.0

Список возможностей, добавляемых контейнеру.

Требуется версия API >= 1.41.

cap_drop

list / elements=string

добавлено в community.docker 2.2.0

Список возможностей, удаляемых из контейнера.

Требуется версия API >= 1.41.

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

any

Команда, выполняемая при запуске контейнера.

Команда может быть строкой, списком или списком строк.

Соответствует параметру COMMAND в docker service create.

configs

list / elements=dictionary

Список словарей с описанием конфигураций сервиса.

Соответствует параметру --config в docker service create.

Требуется версия API >= 1.30.

config_id

string

Идентификатор конфигурации.

config_name

string / обязательный

Имя конфигурации, заданное при ее создании.

filename

string

Имя файла с конфигурацией. Если не указано, используется configs[].config_name.

gid

string

GID группы файла конфигурации.

mode

integer

Режим доступа к файлу внутри контейнера. Должно быть восьмеричное число (например, 0644 или 0444).

uid

string

UID владельца файла конфигурации.

container_labels

dictionary

Словарь пар «ключ — значение».

Соответствует параметру --container-label в docker service create.

debug

boolean

Режим отладки.

Варианты:

• false ← (по умолчанию)
• true

dns

list / elements=string

Список пользовательских DNS-серверов.

Соответствует параметру --dns в docker service create.

dns_options

list / elements=string

Список пользовательских параметров DNS.

Соответствует параметру --dns-option в docker service create.

dns_search

list / elements=string

Список пользовательских доменов поиска DNS.

Соответствует параметру --dns-search в docker service create.

docker_host

aliases: docker_url

string

URL или путь к сокету Unix, используемый для подключения к API Docker. Для подключения к удаленному хосту укажите строку TCP-подключения. Например, tcp://192.0.2.23:2376. Если для шифрования соединения используется TLS, модуль автоматически заменит tcp в URL подключения на https.

Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения DOCKER_HOST. Если переменная окружения не задана, будет использоваться значение по умолчанию.

По умолчанию: "unix:///var/run/docker.sock"

endpoint_mode

string

Режим конечной точки сервиса.

Соответствует параметру --endpoint-mode в docker service create.

Варианты:

• "vip"
• "dnsrr"

env

any

Список или словарь переменных окружения сервиса.

Если передан список, каждый элемент должен иметь формат KEY=VALUE.

Если передан словарь, значения, которые YAML-парсер может интерпретировать как числа, логические значения или другие типы, необходимо заключать в кавычки (например, "true"), чтобы избежать потери данных.

Соответствует параметру --env в docker service create.

env_files

list / elements=path

Список путей к файлам, имеющимся на целевом узле и содержащим переменные окружения FOO=BAR.

Порядок элементов списка важен при определении значения переменной, которая встречается более одного раза.

Если переменная также указана в env, значение env будет иметь приоритет.

force_update

boolean

Принудительно обновить, даже если изменения не требуют этого.

Соответствует параметру --force в docker service update.

Варианты:

• false ← (по умолчанию)
• true

groups

list / elements=string

Список дополнительных имен и/или идентификаторов групп, от имени которых будет запущен процесс контейнера.

Соответствует параметру --group в docker service update.

healthcheck

dictionary

Настройка проверки, определяющей, являются ли контейнеры этого сервиса «здоровыми». Подробные сведения о работе проверок состояния см. в документации по инструкции HEALTHCHECK в Dockerfile.

Параметры healthcheck.interval, healthcheck.timeout и healthcheck.start_period задаются как длительности. Длительность указывается строкой в формате, например: 5h34m56s, 1m30s и т. д. Поддерживаются единицы измерения us, ms, s, m и h.

interval

string

Интервал между проверками.

retries

integer

Количество последовательных сбоев, необходимое для признания состояния нездоровым. Принимает целочисленное значение.

start_period

string

Период запуска, в течение которого контейнер инициализируется до начала отсчета повторных проверок состояния.

test

any

Команда для проверки состояния.

Должна быть строкой или списком. Если это список, первым элементом должно быть одно из значений NONE, CMD или CMD-SHELL.

timeout

string

Максимальное время выполнения одной проверки.

hostname

string

Имя хоста контейнера.

Соответствует параметру --hostname в docker service create.

hosts

dictionary

Словарь соответствий имен хостов IP-адресам, где каждое имя хоста является ключом словаря. Каждое имя хоста будет добавлено в файл /etc/hosts контейнера.

Соответствует параметру --host в docker service create.

image

string

Путь к образу сервиса и его тег.

Соответствует параметру IMAGE в docker service create.

init

boolean

Использовать init в каждом контейнере сервиса для передачи сигналов и сбора завершившихся процессов.

Соответствует параметру --init в docker service create.

Требуется версия API >= 1.37.

Варианты:

• false
• true

labels

dictionary

Словарь пар «ключ — значение».

Соответствует параметру --label в docker service create.

limits

dictionary

Настройка ограничений ресурсов сервиса.

cpus

float

Ограничение CPU сервиса. 0 означает отсутствие ограничений.

Соответствует параметру --limit-cpu в docker service create.

memory

string

Ограничение памяти сервиса в формате <number>[<unit>]. Число должно быть положительным целым. Единицей измерения может быть B (байт), K (кибибайт, 1024 Б), M (мебибайт), G (гибибайт), T (тебибайт) или P (пебибайт).

0 означает отсутствие ограничений.

Если единица измерения не указана, используются байты.

Соответствует параметру --limit-memory в docker service create.

logging

dictionary

Настройка ведения журналов для сервиса.

driver

string

Настройка драйвера ведения журналов для сервиса.

Соответствует параметру --log-driver в docker service create.

options

dictionary

Параметры драйвера ведения журналов сервиса.

Соответствует параметру --log-opt в docker service create.

mode

string

Режим репликации сервиса.

При изменении сервис будет удален и создан заново.

Соответствует параметру --mode в docker service create.

Значение replicated-job добавлено в community.docker 4.7.0; для него требуются версия API >= 1.41 и Docker SDK for Python >= 6.0.0.

Варианты:

• "replicated" ← (по умолчанию)
• "global"
• "replicated-job"

mounts

list / elements=dictionary

Список словарей с описанием подключаемых ресурсов сервиса.

Соответствует параметру --mount в docker service create.

driver_config

dictionary

Конфигурация драйвера тома.

Можно использовать только при условии mounts[].type=volume.

name

string

Имя плагина драйвера тома, используемого для тома.

options

dictionary

Параметры в виде пар «ключ — значение», передаваемые драйверу для этого тома.

labels

dictionary

Метки, назначаемые тому.

no_copy

boolean

Отключить копирование данных из контейнера при создании тома.

Можно использовать только при условии mounts[].type=volume.

Варианты:

• false
• true

propagation

string

Режим распространения.

Можно использовать только при условии mounts[].type=bind.

Варианты:

• "shared"
• "slave"
• "private"
• "rshared"
• "rslave"
• "rprivate"

readonly

boolean

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

Варианты:

• false
• true

source

string

Источник монтирования (например, имя тома или путь на хосте).

Необходимо указать, если mounts[].type не равно tmpfs.

target

string / обязательный

Путь в контейнере.

tmpfs_mode

integer

Режим доступа к файлам tmpfs в восьмеричном формате.

Можно использовать только при mounts[].type=tmpfs.

tmpfs_size

string

Размер монтирования tmpfs в формате <number>[<unit>]. Число должно быть положительным целым. Единицей измерения может быть B (байт), K (кибибайт, 1024B), M (мебибайт), G (гибибайт), T (тебибайт) или P (пебибайт).

Можно использовать только при mounts[].type=tmpfs.

type

string

Тип монтирования.

Обратите внимание, что npipe поддерживается только Docker для Windows. Также обратите внимание, что npipe добавлен в Ansible 2.9.

Варианты:

• "bind" ← (по умолчанию)
• "volume"
• "tmpfs"
• "npipe"

name

string / обязательный

Имя службы.

Соответствует параметру --name команды docker service create.

networks

list / elements=any

Список имен сетей службы или словарей.

При передаче словарей допустимы вложенные параметры name (обязательный), aliases и options.

До версии API 1.29 обновление и удаление сетей не поддерживается. При внесении изменений служба будет удалена и создана заново.

Соответствует параметру --network команды docker service create.

placement

dictionary

Настраивает предпочтения и ограничения размещения службы.

constraints

list / elements=string

Список ограничений службы.

Соответствует параметру --constraint команды docker service create.

preferences

list / elements=dictionary

Список предпочтений размещения в виде пар ключ-значение.

Соответствует параметру --placement-pref команды docker service create.

Требуется версия API >= 1.27.

replicas_max_per_node

integer

добавлено в community.docker 1.3.0

Максимальное число задач на узел.

Соответствует параметру --replicas_max_per_node команды docker service create.

Требуется версия API >= 1.40.

publish

list / elements=dictionary

Список словарей с описанием опубликованных портов службы.

Соответствует параметру --publish команды docker service create.

mode

string

Режим публикации.

Требуется версия API >= 1.32.

Варианты:

• "ingress"
• "host"

protocol

string

Используемый протокол.

Варианты:

• "tcp" ← (по умолчанию)
• "udp"

published_port

integer

Порт, который будет доступен извне.

target_port

integer / обязательный

Порт внутри контейнера, который нужно открыть.

read_only

boolean

Подключить корневую файловую систему контейнеров только для чтения.

Соответствует параметру --read-only команды docker service create.

Варианты:

• false
• true

replicas

integer

Количество контейнеров, запущенных в службе. Допустимо только при mode=replicated или mode=replicated-job.

Если задано значение -1 и служба отсутствует, число реплик службы будет установлено в 1.

Если задано значение -1 и служба существует, число ее реплик не изменится.

Соответствует параметру --replicas команды docker service create.

По умолчанию: -1

reservations

dictionary

Настраивает резервирование ресурсов службы.

cpus

float

Резервирование ЦП для службы. Значение 0 означает отсутствие резервирования.

Соответствует параметру --reserve-cpu команды docker service create.

memory

string

Резервирование памяти для службы в формате <number>[<unit>]. Число должно быть положительным целым. Единицей измерения может быть B (байт), K (кибибайт, 1024B), M (мебибайт), G (гибибайт), T (тебибайт) или P (пебибайт).

Значение 0 означает отсутствие резервирования.

Если единица измерения не указана, по умолчанию используются байты.

Соответствует параметру --reserve-memory команды docker service create.

resolve_image

boolean

Следует ли получать текущий дайджест образа из реестра и обновлять его при изменении.

Требуется версия API >= 1.30.

Варианты:

• false ← (по умолчанию)
• true

restart_config

dictionary

Настраивает, нужно ли и как перезапускать контейнеры после их завершения.

condition

string

Условие перезапуска службы.

Соответствует параметру --restart-condition команды docker service create.

Варианты:

• "none"
• "on-failure"
• "any"

delay

string

Задержка между перезапусками.

Принимает строку в формате, например: 5h34m56s, 1m30s и так далее. Поддерживаются единицы us, ms, s, m и h.

Соответствует параметру --restart-delay команды docker service create.

max_attempts

integer

Максимальное число перезапусков службы.

Соответствует параметру --restart-condition команды docker service create.

window

string

Окно оценки политики перезапуска.

Принимает строку в формате, например: 5h34m56s, 1m30s и так далее. Поддерживаются единицы us, ms, s, m и h.

Соответствует параметру --restart-window команды docker service create.

rollback_config

dictionary

Настраивает откат службы в случае неудачного обновления.

delay

string

Задержка между откатами задач.

Принимает строку в формате, например: 5h34m56s, 1m30s и так далее. Поддерживаются единицы us, ms, s, m и h.

Соответствует параметру --rollback-delay команды docker service create.

Требуется версия API >= 1.28.

failure_action

string

Действие при неудачном откате.

Соответствует параметру --rollback-failure-action команды docker service create.

Требуется версия API >= 1.28.

Варианты:

• "continue"
• "pause"

max_failure_ratio

float

Доля задач, которые могут завершиться с ошибкой во время отката.

Соответствует параметру --rollback-max-failure-ratio команды docker service create.

Требуется версия API >= 1.28.

monitor

string

Период наблюдения за ошибками после отката каждой задачи.

Принимает строку в формате, например: 5h34m56s, 1m30s и так далее. Поддерживаются единицы us, ms, s, m и h.

Соответствует параметру --rollback-monitor команды docker service create.

Требуется версия API >= 1.28.

order

string

Определяет порядок операций при откате.

Соответствует параметру --rollback-order команды docker service create.

Требуется версия API >= 1.29.

parallelism

integer

Число контейнеров, откатываемых одновременно. Если задано значение 0, все контейнеры откатываются одновременно.

Соответствует параметру --rollback-parallelism команды docker service create.

Требуется версия API >= 1.28.

secrets

list / elements=dictionary

Список словарей с описанием секретов службы.

Соответствует параметру --secret команды docker service create.

filename

string

Имя файла, содержащего секрет. Если не указано, по умолчанию используется secrets[].secret_name.

Соответствует ключу target объекта docker service create --secret.

gid

string

GID группы файла секрета.

mode

integer

Режим доступа к файлу внутри контейнера. Должно быть указано восьмеричное число (например, 0644 или 0444).

secret_id

string

Идентификатор секрета.

secret_name

string / обязательный

Имя секрета, заданное при его создании.

uid

string

UID владельца файла секрета.

state

string

absent — служба с указанным именем будет удалена, а ее задачи остановлены.

present — проверяет наличие службы с указанным именем и заданными параметрами конфигурации. Для неуказанных параметров конфигурации будут установлены значения Docker по умолчанию.

Варианты:

• "present" ← (по умолчанию)
• "absent"

stop_grace_period

string

Время ожидания перед принудительным завершением контейнера.

Принимает длительность в виде строки в формате, например: 5h34m56s, 1m30s и так далее. Поддерживаются единицы us, ms, s, m и h.

Соответствует параметру --stop-grace-period команды docker service create.

stop_signal

string

Переопределяет сигнал, используемый по умолчанию для остановки контейнера.

Соответствует параметру --stop-signal команды docker service create.

sysctls

dictionary

добавлено в community.docker 3.10.0

Словарь пар ключ-значение.

timeout

integer

Максимальное время в секундах ожидания ответа от API.

Если значение не указано в задаче, вместо него будет использоваться значение переменной среды DOCKER_TIMEOUT. Если переменная среды не задана, будет использовано значение по умолчанию.

По умолчанию: 60

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 for Python 7.0.0+. Его указание в Docker SDK for Python версии 7.0.0 или более новой приведет к ошибке.

tty

boolean

Выделить псевдотерминал (TTY).

Соответствует параметру --tty команды docker service create.

Варианты:

• false
• true

update_config

dictionary

Настраивает способ обновления службы. Полезно для настройки поэтапных обновлений.

delay

string

Задержка поэтапного обновления.

Принимает строку в формате, например: 5h34m56s, 1m30s и так далее. Поддерживаются единицы измерения us, ms, s, m и h.

Соответствует параметру --update-delay команды docker service create.

failure_action

string

Действие, выполняемое в случае сбоя контейнера.

Соответствует параметру --update-failure-action команды docker service create.

Для использования rollback требуется версия API >= 1.29.

Варианты:

• "continue"
• "pause"
• "rollback"

max_failure_ratio

float

Доля задач, которые могут завершиться с ошибкой во время обновления до применения действия при сбое.

Соответствует параметру --update-max-failure-ratio команды docker service create.

monitor

string

Время наблюдения за обновлёнными задачами на предмет сбоев.

Принимает строку в формате, например: 5h34m56s, 1m30s и так далее. Поддерживаются единицы измерения us, ms, s, m и h.

Соответствует параметру --update-monitor команды docker service create.

order

string

Задаёт порядок операций при развёртывании обновлённой задачи.

Соответствует параметру --update-order команды docker service create.

Требуется версия API >= 1.29.

parallelism

integer

Параллелизм поэтапного обновления.

Соответствует параметру --update-parallelism команды docker service create.

use_ssh_client

boolean

добавлено в community.docker 1.5.0

Для SSH-транспорта используйте инструмент командной строки ssh вместо paramiko.

Требуется Docker SDK for Python версии 4.4.0 или новее.

Варианты:

• false ← (по умолчанию)
• true

user

string

Задаёт имя пользователя или UID, используемые для указанной команды.

До Ansible 2.8 значением по умолчанию для этого параметра было root.

Значение по умолчанию удалено, чтобы при отсутствии указанного здесь пользователя использовался пользователь, заданный в образе.

Соответствует параметру --user команды docker service create.

validate_certs

псевдонимы: tls_verify

boolean

Защищает соединение с API с помощью TLS и проверяет подлинность сервера Docker.

Если значение не указано в задаче, вместо него будет использовано значение переменной окружения DOCKER_TLS_VERIFY. Если переменная окружения не задана, будет использовано значение по умолчанию.

Варианты:

• false ← (по умолчанию)
• true

working_dir

string

Путь к рабочему каталогу.

Соответствует параметру --workdir команды docker service create.

action_group

Группы действий: community.docker.docker, docker

Используйте group/docker или group/community.docker.docker в module_defaults, чтобы задать значения по умолчанию для этого модуля.

check_mode

Поддержка: полная

Может работать в режиме check_mode и возвращать прогноз изменения состояния, не изменяя целевой объект.

diff_mode

Поддержка: полная

В режиме diff возвращает сведения об изменениях (или о возможных изменениях в check_mode).

idempotent

Поддержка: полная

При повторном запуске с теми же аргументами вне режима check второй запуск сообщает об отсутствии изменений.

Предполагается, что система, управляемая модулем или запрашиваемая им, не изменилась существенным образом.

changes

list / elements=string

Список изменённых атрибутов службы, если служба была изменена; в противном случае — [].

Возвращается: всегда

Пример: ["container_labels", "replicas"]

rebuilt

boolean

True, если служба была пересоздана (удалена и создана заново).

Возвращается: всегда

Пример: true

swarm_service

dictionary

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

Обратите внимание: факты не входят в зарегистрированные переменные, но доступны напрямую.

Обратите внимание: до Ansible 2.7.9 возвращаемая переменная в документации называлась ansible_swarm_service, хотя модуль фактически возвращал переменную с именем ansible_docker_service. В Ansible 2.7.9 и Ansible 2.8.0 имя переменной было изменено на swarm_service как в коде, так и в документации. В Ansible 2.7.x по-прежнему можно использовать старое имя ansible_docker_service.

Возвращается: всегда

Пример: {"args": ["3600"], "cap_add": null, "cap_drop": ["ALL"], "command": ["sleep"], "configs": null, "constraints": ["node.role == manager", "engine.labels.operatingsystem == ubuntu 14.04"], "container_labels": null, "dns": null, "dns_options": null, "dns_search": null, "endpoint_mode": null, "env": ["ENVVAR1=envvar1", "ENVVAR2=envvar2"], "force_update": null, "groups": null, "healthcheck": {"interval": 90000000000, "retries": 3, "start_period": 30000000000, "test": ["CMD", "curl", "--fail", "http://nginx.host.com"], "timeout": 10000000000}, "healthcheck_disabled": false, "hostname": null, "hosts": null, "image": "alpine:latest@sha256:b3dbf31b77fd99d9c08f780ce6f5282aba076d70a513a8be859d8d3a4d0c92b8", "labels": {"com.example.department": "Finance", "com.example.description": "Accounting webapp"}, "limit_cpu": 0.5, "limit_memory": 52428800, "log_driver": "fluentd", "log_driver_options": {"fluentd-address": "127.0.0.1:24224", "fluentd-async-connect": "true", "tag": "myservice"}, "mode": "replicated", "mounts": [{"driver_config": null, "labels": null, "no_copy": null, "propagation": null, "readonly": false, "source": "/tmp/", "target": "/remote_tmp/", "tmpfs_mode": null, "tmpfs_size": null, "type": "bind"}], "networks": null, "placement_preferences": [{"spread": "node.labels.mylabel"}], "publish": null, "read_only": null, "replicas": 1, "replicas_max_per_node": 1, "reserve_cpu": 0.25, "reserve_memory": 20971520, "restart_policy": "on-failure", "restart_policy_attempts": 3, "restart_policy_delay": 5000000000, "restart_policy_window": 120000000000, "secrets": null, "stop_grace_period": null, "stop_signal": null, "sysctls": null, "tty": null, "update_delay": 10000000000, "update_failure_action": null, "update_max_failure_ratio": null, "update_monitor": null, "update_order": "stop-first", "update_parallelism": 2, "user": null, "working_dir": null}