Модуль community.docker.docker_swarm — управление кластером Swarm

Примечание

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

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

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

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

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

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

Создание нового кластера Swarm.
Добавление/удаление узлов или менеджеров в существующем кластере.

Требования

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

Docker API >= 1.25
Docker SDK для Python: обратите внимание, что модуль Python docker-py заменён модулем docker (подробности см. здесь). Этот модуль не работает с docker-py.
Docker SDK для Python >= 2.0.0

Параметры

Параметр	Комментарии
advertise_addr string	Адрес, доступный извне и объявляемый другим узлам. Это может быть адрес с портом в формате `192.168.1.1:4567` или интерфейс с последующим номером порта, например `eth0:4567`. Если номер порта не указан, используется номер порта из адреса прослушивания. Если `advertise_addr` не указан, он по возможности определяется автоматически. Используется только при инициализации или присоединении к swarm. Поэтому этот параметр не учитывается при проверке идемпотентности.
api_version псевдонимы: docker_api_version string	Версия Docker API, запущенная на хосте Docker. По умолчанию используется последняя версия API, поддерживаемая Docker SDK для Python и демоном Docker. Если значение не указано в задаче, вместо него будет использоваться значение переменной среды `DOCKER_API_VERSION`. Если переменная среды не задана, будет использоваться значение по умолчанию. По умолчанию: `"auto"`
autolock_managers boolean	Если параметр установлен, генерируется ключ, который используется для блокировки данных, хранящихся на менеджерах. Значение по умолчанию в Docker — `false`. Для получения ключа разблокировки можно использовать community.docker.docker_swarm_info. Варианты: `false` `true`
ca_force_rotate integer	Целое число, предназначенное для принудительной генерации Swarm нового сертификата и ключа подписывающего центра сертификации, если они не указаны. Значение по умолчанию в Docker — `0`. Требуется версия API >= 1.30.
ca_path псевдонимы: ca_cert, tls_ca_cert, cacert_path path	Для проверки подлинности сервера с помощью сертификата центра сертификации укажите путь к файлу сертификата CA. Если значение не указано в задаче, а переменная среды `DOCKER_CERT_PATH` задана, будет использован файл `ca.pem` из каталога, указанного в переменной среды `DOCKER_CERT_PATH`. Ранее этот параметр назывался `ca_cert`, а в community.docker 3.6.0 был переименован в `ca_path`. Старое имя добавлено как псевдоним и по-прежнему может использоваться.
client_cert псевдонимы: tls_client_cert, cert_path path	Путь к файлу сертификата TLS клиента. Если значение не указано в задаче, а переменная среды `DOCKER_CERT_PATH` задана, будет использован файл `cert.pem` из каталога, указанного в переменной среды `DOCKER_CERT_PATH`.
client_key псевдонимы: tls_client_key, key_path path	Путь к файлу ключа TLS клиента. Если значение не указано в задаче, а переменная среды `DOCKER_CERT_PATH` задана, будет использован файл `key.pem` из каталога, указанного в переменной среды `DOCKER_CERT_PATH`.
data_path_addr string добавлено в community.docker 2.5.0	Адрес или интерфейс, используемый для передачи данных. Это может быть адрес в формате `192.168.1.1` или интерфейс, например `eth0`. Используется только при инициализации или присоединении к swarm. Поэтому этот параметр не учитывается при проверке идемпотентности. Требуется версия API >= 1.30.
data_path_port integer добавлено в community.docker 3.1.0	Порт, используемый для передачи данных. Здесь должен быть указан номер порта, например `9789`. Используется только при инициализации swarm. Поэтому этот параметр не учитывается при проверке идемпотентности. Требуется версия API >= 1.40.
debug boolean	Режим отладки. Варианты: `false` ← (по умолчанию) `true`
default_addr_pool list / элементы=string	Пул адресов по умолчанию в формате CIDR. Используется только при инициализации swarm. Поэтому этот параметр не учитывается при проверке идемпотентности. Требуется версия API >= 1.39.
dispatcher_heartbeat_period integer	Интервал (в наносекундах), с которым агент отправляет сигнал проверки связи диспетчеру. Значение по умолчанию в Docker — 5 секунд, что соответствует значению `5000000000`.
docker_host псевдонимы: docker_url string	URL или путь к сокету Unix для подключения к Docker API. Для подключения к удалённому хосту укажите строку TCP-подключения. Например, `tcp://192.0.2.23:2376`. Если для шифрования соединения используется TLS, модуль автоматически заменит `tcp` в URL подключения на `https`. Если значение не указано в задаче, вместо него будет использоваться значение переменной среды `DOCKER_HOST`. Если переменная среды не задана, будет использоваться значение по умолчанию. По умолчанию: `"unix:///var/run/docker.sock"`
election_tick integer	Количество тактов (в секундах), в течение которых отсутствие лидера приводит к запуску новых выборов. Значение по умолчанию в Docker — `10` секунд.
force boolean	Используйте со значением state `present`, чтобы принудительно создать новый Swarm, даже если узел уже входит в другой. Используйте со значением state `absent`, чтобы покинуть swarm, даже если этот узел является менеджером. Варианты: `false` ← (по умолчанию) `true`
heartbeat_tick integer	Количество тактов (в секундах) между сигналами проверки связи. Значение по умолчанию в Docker — `1` секунд.
join_token string	Токен Swarm для присоединения к кластеру swarm. Используется с `state=join`. Если это значение указано, соответствующее возвращаемое значение будет скрыто Ansible. Это происходит потому, что данное значение не регистрируется в журнале.
keep_old_snapshots integer	Количество снимков, сохраняемых помимо текущего снимка. Значение по умолчанию в Docker — `0`.
labels dictionary	Определяемые пользователем метаданные «ключ/значение». Операции с метками в этом модуле применяются к кластеру Docker Swarm. Используйте модуль community.docker.docker_node для добавления, изменения или удаления меток узлов swarm. Требуется версия API >= 1.32.
listen_addr string	Адрес прослушивания, используемый для связи между менеджерами. Это может быть адрес с портом в формате `192.168.1.1:4567` или интерфейс с последующим номером порта, например `eth0:4567`. Если номер порта не указан, используется порт прослушивания swarm по умолчанию. Используется только при инициализации или присоединении к swarm. Поэтому этот параметр не учитывается при проверке идемпотентности. По умолчанию: `"0.0.0.0:2377"`
log_entries_for_slow_followers integer	Количество записей журнала, сохраняемых для синхронизации отстающих ведомых узлов после создания снимка.
name string	Имя swarm.
node_cert_expiry integer	Срок действия сертификатов узлов, заданный в наносекундах. Значение по умолчанию в Docker — 90 дней, что соответствует значению `7776000000000000`.
node_id string	Идентификатор Swarm узла, который нужно удалить. Используется с `state=remove`.
remote_addrs list / элементы=string	Удалённый адрес одного или нескольких узлов-менеджеров существующего Swarm, к которому нужно подключиться. Используется с `state=join`.
rotate_manager_token boolean	Сменить токен присоединения менеджера. Варианты: `false` ← (по умолчанию) `true`
rotate_worker_token boolean	Сменить токен присоединения рабочего узла. Варианты: `false` ← (по умолчанию) `true`
signing_ca_cert string	Желаемый сертификат подписывающего центра сертификации для всех конечных TLS-сертификатов узлов swarm в формате PEM. Здесь нужно указать не путь к сертификату, а его содержимое. Требуется версия API >= 1.30.
signing_ca_key string	Желаемый ключ подписывающего центра сертификации для всех конечных TLS-сертификатов узлов swarm в формате PEM. Здесь нужно указать не путь к ключу, а его содержимое. Требуется версия API >= 1.30.
snapshot_interval integer	Количество записей журнала между снимками. Значение по умолчанию в Docker — `10000`.
state string	Укажите `present`, чтобы создать/обновить кластер. Укажите `join`, чтобы присоединиться к существующему кластеру. Укажите `absent`, чтобы покинуть существующий кластер. Укажите `remove`, чтобы удалить отсутствующий узел из кластера. Обратите внимание, что для удаления требуется Docker SDK для Python >= 2.4.0. Перед удалением менеджера его можно понизить до уровня рабочего узла с помощью community.docker.docker_node. Варианты: `"present"` ← (по умолчанию) `"join"` `"absent"` `"remove"`
subnet_size integer	Длина маски подсети пула адресов по умолчанию. Используется только при инициализации swarm. Поэтому этот параметр не учитывается при проверке идемпотентности. Требуется версия API >= 1.39.
task_history_retention_limit integer	Максимальное количество сохраняемых записей истории задач. Значение по умолчанию в Docker — `5`.
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 для Python 7.0.0 и новее. Его указание приведёт к ошибке.
use_ssh_client boolean добавлено в community.docker 1.5.0	Для транспорта SSH использовать инструмент командной строки `ssh` вместо paramiko. Требуется Docker SDK для Python версии 4.4.0 или новее. Варианты: `false` ← (по умолчанию) `true`
validate_certs псевдонимы: 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	Поддержка: полная	В режиме diff будут возвращены сведения о том, что изменилось (или, возможно, должно измениться в `check_mode`).
idempotent	Поддержка: полная	При последовательном запуске дважды вне режима проверки с одинаковыми аргументами второй запуск не указывает на наличие изменений. Предполагается, что система, которой управляет модуль или к которой он обращается, не изменилась существенным образом.

Примечания

Примечание

Подключайтесь к демону 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 с использованием TLS может потребоваться установить дополнительные пакеты Python. Для Docker SDK for Python версии 2.4 или новее это можно сделать, установив docker[tls] с помощью ansible.builtin.pip.
Обратите внимание, что Docker SDK for Python позволяет указывать путь к конфигурации Docker лишь для очень небольшого числа функций. Как правило, если переменная окружения DOCKER_CONFIG не задана, используется $HOME/.docker/config.json, в противном случае используется $DOCKER_CONFIG/config.json.
Этот модуль использует Docker SDK for Python для взаимодействия с демоном Docker.

Примеры

---
- name: Init a new swarm with default parameters
  community.docker.docker_swarm:
    state: present

- name: Update swarm configuration
  community.docker.docker_swarm:
    state: present
    election_tick: 5

- name: Add nodes
  community.docker.docker_swarm:
    state: join
    advertise_addr: 192.168.1.2
    join_token: SWMTKN-1--xxxxx
    remote_addrs: ['192.168.1.1:2377']

- name: Leave swarm for a node
  community.docker.docker_swarm:
    state: absent

- name: Remove a swarm manager
  community.docker.docker_swarm:
    state: absent
    force: true

- name: Remove node from swarm
  community.docker.docker_swarm:
    state: remove
    node_id: mynode

- name: Init a new swarm with different data path interface
  community.docker.docker_swarm:
    state: present
    advertise_addr: eth0
    data_path_addr: ens10

- name: Init a new swarm with a different data path port
  community.docker.docker_swarm:
    state: present
    data_path_port: 9789

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

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

Ключ	Описание
actions list / elements=string	Содержит действия, выполненные в swarm. Возвращается: если действие завершилось с ошибкой. Пример: `["This cluster is already a swarm cluster"]`
swarm_facts dictionary	Сведения о swarm. Возвращается: при успешном выполнении
JoinTokens dictionary	Токены для подключения к Swarm. Возвращается: при успешном выполнении
Manager string	Токен для добавления в кластер нового узла manager. Примечание: если для этого значения указано `join_token`, здесь будет возвращён не токен, а `VALUE_SPECIFIED_IN_NO_LOG_PARAMETER`. Если вы передаёте `join_token`, убедитесь, что ваша playbook/роль не зависит от этого возвращаемого значения! Возвращается: при успешном выполнении Пример: `"SWMTKN-1--xxxxx"`
Worker string	Токен для добавления в кластер нового узла worker. Примечание: если для этого значения указано `join_token`, здесь будет возвращён не токен, а `VALUE_SPECIFIED_IN_NO_LOG_PARAMETER`. Если вы передаёте `join_token`, убедитесь, что ваша playbook/роль не зависит от этого возвращаемого значения! Возвращается: при успешном выполнении Пример: `"SWMTKN-1--xxxxx"`
UnlockKey string	Ключ разблокировки swarm, если `autolock_managers=true`. Возвращается: при успешном выполнении, если `autolock_managers=true` и swarm инициализирован, или если `autolock_managers` изменилось. Пример: `"SWMKEY-1-xxx"`

Авторы

Thierry Bouvet (@tbouvet)
Piotr Wojciechowski (@WojciechowskiPiotr)

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

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