Модуль community.docker.docker_network — управление сетями Docker

Примечание

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

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

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

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

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

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

Создание и удаление сетей Docker, а также подключение к ним контейнеров.
Выполняет в основном ту же функцию, что и подкоманда CLI docker network.

Требования

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

Docker API >= 1.25
paramiko (при использовании SSH с use_ssh_client=false)
pyOpenSSL (при использовании TLS)
pywin32 (при использовании именованных каналов в Windows 32)
requests

Параметры

Параметр	Комментарии
api_version псевдонимы: docker_api_version строка	Версия Docker API, работающая на хосте Docker. По умолчанию используется последняя версия API, поддерживаемая этой коллекцией и демоном Docker. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_API_VERSION`. Если переменная окружения не задана, будет использоваться значение по умолчанию. По умолчанию: `"auto"`
appends псевдонимы: incremental логическое значение	По умолчанию список подключенных контейнеров считается полным, то есть контейнеры, отсутствующие в списке, отключаются от сети. Используйте `appends`, чтобы оставить уже подключенные контейнеры подключенными. Варианты: `false` ← (по умолчанию) `true`
attachable логическое значение	Если этот параметр включен и сеть имеет глобальную область действия, контейнеры, не являющиеся сервисами, на рабочих узлах смогут подключаться к сети. Варианты: `false` `true`
ca_path псевдонимы: ca_cert, tls_ca_cert, cacert_path путь	Укажите путь к файлу сертификата CA, чтобы использовать сертификат 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 путь	Путь к файлу 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`.
config_from строка добавлено в community.docker 3.10.0	Указывает сеть, содержащую только конфигурацию, из которой следует использовать конфигурацию.
config_only логическое значение добавлено в community.docker 3.10.0	Указывает, что эта сеть содержит только конфигурацию. Варианты: `false` `true`
connected псевдонимы: containers список / элементы=строка	Список имен или идентификаторов контейнеров, которые нужно подключить к сети. Обратите внимание: модуль лишь гарантирует подключение этих контейнеров к сети, но не учитывает параметры подключения. Если вы используете определенные IP-адреса и т. п., воспользуйтесь модулем community.docker.docker_container, чтобы убедиться, что контейнеры правильно подключены к этой сети. По умолчанию: `[]`
debug логическое значение	Режим отладки Варианты: `false` ← (по умолчанию) `true`
docker_host псевдонимы: docker_url строка	URL или путь к сокету Unix, используемый для подключения к Docker API. Для подключения к удаленному хосту укажите строку TCP-подключения. Например, `tcp://192.0.2.23:2376`. Если соединение зашифровано с помощью TLS, модуль автоматически заменит `tcp` в URL подключения на `https`. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_HOST`. Если переменная окружения не задана, будет использоваться значение по умолчанию. По умолчанию: `"unix:///var/run/docker.sock"`
driver строка	Укажите тип сети. Docker предоставляет драйверы bridge и overlay, но также можно использовать сторонние драйверы. По умолчанию: `"bridge"`
driver_options словарь	Словарь параметров сети. Допустимые параметры и значения см. в документации Docker. По умолчанию: `{}`
enable_ipv4 логическое значение добавлено в community.docker 4.5.0	Включить работу в сети IPv4. Этот параметр включен по умолчанию, но его можно явно отключить. Требуется Docker API версии 1.47 или новее. Варианты: `false` `true`
enable_ipv6 логическое значение	Включить работу в сети IPv6. Варианты: `false` `true`
force логическое значение	При состоянии `present` все контейнеры существующих сетей будут отключены, сеть будет удалена и создана заново. Этот параметр необходим, если вы изменили настройки IPAM или драйвера и хотите обновить существующую сеть, применив новые параметры. Варианты: `false` ← (по умолчанию) `true`
ingress логическое значение добавлено в community.docker 4.2.0	Включить маршрутизационную сетку Swarm. Варианты: `false` `true`
internal логическое значение	Ограничить внешний доступ к сети. Варианты: `false` `true`
ipam_config список / элементы=словарь	Список блоков конфигурации IPAM. Допустимые параметры и значения см. в документации Docker. Обратите внимание: `ipam_config[].iprange` здесь записано иначе (используется обозначение из Docker SDK for Python).
aux_addresses словарь	Вспомогательные IP-адреса, используемые сетевым драйвером, в виде соответствий имени хоста IP-адресу.
gateway строка	IP-адрес шлюза.
iprange строка	Диапазон IP-адресов в нотации CIDR.
subnet строка	Подсеть IP-адресов в нотации CIDR.
ipam_driver строка	Укажите драйвер IPAM.
ipam_driver_options словарь	Словарь параметров драйвера IPAM.
labels словарь	Словарь меток. По умолчанию: `{}`
name псевдонимы: network_name строка / обязательный	Имя сети, с которой нужно выполнить операцию.
scope строка	Укажите область действия сети. Варианты: `"local"` `"global"` `"swarm"`
state строка	`absent` удаляет сеть. Если к сети подключены контейнеры, они будут отключены от нее. `present` создает сеть, если она еще не существует с указанными параметрами, и подключает список контейнеров, заданный параметром `connected`. Контейнеры, отсутствующие в списке, будут отключены. Если список пуст, к сети не будет подключено ни одного контейнера. Используйте параметр `appends`, чтобы оставить подключенными уже подключенные контейнеры. Используйте параметры `force`, чтобы принудительно пересоздать сеть. Варианты: `"absent"` `"present"` ← (по умолчанию)
timeout целое число	Максимальное время ожидания ответа от API в секундах. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_TIMEOUT`. Если переменная окружения не задана, будет использоваться значение по умолчанию. По умолчанию: `60`
tls логическое значение	Защитить подключение к API с помощью TLS, не проверяя подлинность сервера хоста Docker. Обратите внимание: если параметр `validate_certs` также установлен в значение `true`, он имеет приоритет. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_TLS`. Если переменная окружения не задана, будет использоваться значение по умолчанию. Варианты: `false` ← (по умолчанию) `true`
tls_hostname строка	При проверке подлинности сервера хоста Docker укажите ожидаемое имя сервера. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_TLS_HOSTNAME`. Если переменная окружения не задана, будет использоваться значение по умолчанию. Обратите внимание: в более ранних версиях этот параметр имел значение по умолчанию `localhost`. Оно было удалено в community.docker 3.0.0.
use_ssh_client логическое значение добавлено в community.docker 1.5.0	Для SSH-подключений использовать инструмент CLI `ssh` вместо paramiko. Варианты: `false` ← (по умолчанию) `true`
validate_certs псевдонимы: tls_verify логическое значение	Защитить подключение к 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`).
idempotent	Поддержка: частичная При значении `force=true` модуль не является идемпотентным.	При повторном запуске с теми же аргументами вне режима проверки второй вызов сообщает об отсутствии изменений. Предполагается, что система, контролируемая или запрашиваемая модулем, не изменилась существенным образом.

Примечания

Примечание

При изменении параметров сети модуль отключает от неё все контейнеры, удаляет сеть и создаёт её заново. Он не пытается повторно подключить контейнеры, за исключением перечисленных в (connected, и даже для них не учитывает специальные параметры подключения, такие как фиксированные IP-адреса или MAC-адреса. Если вам нужно лучше контролировать подключение контейнеров к сети, используйте цикл с модулем community.docker.docker_container, перебирая контейнеры, чтобы убедиться, что они подключены правильно.
Модуль не поддерживает Docker Swarm. Это означает, что он не будет пытаться отключать или повторно подключать службы. Если к сети подключены службы, её удаление завершится ошибкой. При изменении параметров сети её необходимо удалить и создать заново, поэтому и эта операция завершится ошибкой.
Подключайтесь к демону 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 SDK или Python, включённый в эту коллекцию.

Примеры

---
- name: Create a network
  community.docker.docker_network:
    name: network_one

- name: Remove all but selected list of containers
  community.docker.docker_network:
    name: network_one
    connected:
      - container_a
      - container_b
      - container_c

- name: Remove a single container
  community.docker.docker_network:
    name: network_one
    connected: "{{ fulllist|difference(['container_a']) }}"

- name: Add a container to a network, leaving existing containers connected
  community.docker.docker_network:
    name: network_one
    connected:
      - container_a
    appends: true

- name: Create a network with driver options
  community.docker.docker_network:
    name: network_two
    driver_options:
      com.docker.network.bridge.name: net2

- name: Create a network with custom IPAM config
  community.docker.docker_network:
    name: network_three
    ipam_config:
      - subnet: 172.23.27.0/24
        gateway: 172.23.27.2
        iprange: 172.23.27.0/26
        aux_addresses:
          host1: 172.23.27.3
          host2: 172.23.27.4

- name: Create a network with labels
  community.docker.docker_network:
    name: network_four
    labels:
      key1: value1
      key2: value2

- name: Create a network with IPv6 IPAM config
  community.docker.docker_network:
    name: network_ipv6_one
    enable_ipv6: true
    ipam_config:
      - subnet: fdd1:ac8c:0557:7ce1::/64

- name: Create a network with IPv6 and custom IPv4 IPAM config
  community.docker.docker_network:
    name: network_ipv6_two
    enable_ipv6: true
    ipam_config:
      - subnet: 172.24.27.0/24
      - subnet: fdd1:ac8c:0557:7ce2::/64

- name: Delete a network, disconnecting all containers
  community.docker.docker_network:
    name: network_one
    state: absent

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

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

Ключ	Описание
network dictionary	Результаты проверки затронутой сети. Возвращается: при успехе Пример: `{}`

Авторы

Ben Keith (@keitwb)
Chris Houseknecht (@chouseknecht)
Dave Bendit (@DBendit)

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

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