From 588cc8359cb32969cca1d855381b4e47cec385b7 Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Thu, 2 Jan 2020 22:50:50 +0100
Subject: [PATCH] Add notes on docker_network connectivity for containers and
 services. (#65840) (#65965)

(cherry picked from commit d3b6db37549517b5d8234e04b247f01e2f9b49f0)
---
 lib/ansible/modules/cloud/docker/docker_network.py | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/lib/ansible/modules/cloud/docker/docker_network.py b/lib/ansible/modules/cloud/docker/docker_network.py
index 2797561ea79..26feddde36c 100644
--- a/lib/ansible/modules/cloud/docker/docker_network.py
+++ b/lib/ansible/modules/cloud/docker/docker_network.py
@@ -31,6 +31,9 @@ options:
   connected:
     description:
       - List of container names or container IDs to connect to a network.
+      - Please note that the module only makes sure that these containers are connected to the network,
+        but does not care about connection options. If you rely on specific IP addresses etc., use the
+        M(docker_container) module to ensure your containers are correctly connected to this network.
     type: list
     aliases:
       - containers
@@ -183,6 +186,15 @@ extends_documentation_fragment:
   - docker
   - docker.docker_py_1_documentation
 
+notes:
+  - When network options are changed, the module disconnects all containers from the network, deletes the network, and re-creates the network.
+    It does not try to reconnect containers, except the ones listed in (I(connected), and even for these, it does not consider specific
+    connection options like fixed IP addresses or MAC addresses. If you need more control over how the containers are connected to the
+    network, loop the M(docker_container) module to loop over your containers to make sure they are connected properly.
+  - The module does not support Docker Swarm, i.e. it will not try to disconnect or reconnect services. If services are connected to the
+    network, deleting the network will fail. When network options are changed, the network has to be deleted and recreated, so this will
+    fail as well.
+
 author:
   - "Ben Keith (@keitwb)"
   - "Chris Houseknecht (@chouseknecht)"