From 81e0c531947a2eabe4d5f80d1ab36049c58f2f8b Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Sun, 29 Dec 2024 18:26:28 +0100
Subject: [PATCH 1/2] Add 'idempotent' attribute.

---
 plugins/doc_fragments/attributes.py           | 14 ++++++++++++++
 plugins/modules/current_container_facts.py    |  1 +
 plugins/modules/docker_compose_v2.py          |  4 ++++
 plugins/modules/docker_compose_v2_exec.py     |  4 ++++
 plugins/modules/docker_compose_v2_pull.py     |  2 ++
 plugins/modules/docker_compose_v2_run.py      |  4 ++++
 plugins/modules/docker_config.py              |  8 ++++++--
 plugins/modules/docker_container.py           |  4 ++++
 plugins/modules/docker_container_copy_into.py |  4 ++++
 plugins/modules/docker_container_exec.py      |  4 ++++
 plugins/modules/docker_container_info.py      |  1 +
 plugins/modules/docker_host_info.py           |  1 +
 plugins/modules/docker_image.py               |  8 ++++++++
 plugins/modules/docker_image_build.py         |  4 ++++
 plugins/modules/docker_image_export.py        |  2 ++
 plugins/modules/docker_image_info.py          |  1 +
 plugins/modules/docker_image_load.py          |  2 ++
 plugins/modules/docker_image_pull.py          |  2 ++
 plugins/modules/docker_image_push.py          |  2 ++
 plugins/modules/docker_image_remove.py        |  2 ++
 plugins/modules/docker_image_tag.py           |  2 ++
 plugins/modules/docker_login.py               |  5 +++--
 plugins/modules/docker_network.py             |  4 ++++
 plugins/modules/docker_network_info.py        |  1 +
 plugins/modules/docker_node.py                |  2 ++
 plugins/modules/docker_node_info.py           |  1 +
 plugins/modules/docker_plugin.py              |  2 ++
 plugins/modules/docker_prune.py               |  2 ++
 plugins/modules/docker_secret.py              |  4 ++++
 plugins/modules/docker_stack.py               |  2 ++
 plugins/modules/docker_stack_info.py          |  1 +
 plugins/modules/docker_stack_task_info.py     |  1 +
 plugins/modules/docker_swarm.py               |  2 ++
 plugins/modules/docker_swarm_info.py          |  1 +
 plugins/modules/docker_swarm_service.py       |  2 ++
 plugins/modules/docker_swarm_service_info.py  |  1 +
 plugins/modules/docker_volume.py              |  4 ++++
 plugins/modules/docker_volume_info.py         |  1 +
 38 files changed, 108 insertions(+), 4 deletions(-)

diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py
index e5305b847..0bcd5c34c 100644
--- a/plugins/doc_fragments/attributes.py
+++ b/plugins/doc_fragments/attributes.py
@@ -18,6 +18,20 @@ class ModuleDocFragment(object):
     description: Can run in C(check_mode) and return changed status prediction without modifying target.
   diff_mode:
     description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
+  idempotent:
+    description:
+      - When run twice in a row with the same arguments, the second invocation indicates no change.
+      - This assumes that the system controlled/queried by the module has not changed in a relevant way.
+"""
+
+    # Should be used together with the standard fragment
+    IDEMPOTENT_NOT_MODIFY_STATE = r"""
+options: {}
+attributes:
+  idempotent:
+    support: full
+    details:
+      - This action does not modify state.
 """
 
     # Should be used together with the standard fragment
diff --git a/plugins/modules/current_container_facts.py b/plugins/modules/current_container_facts.py
index 1b05ad0f5..621965add 100644
--- a/plugins/modules/current_container_facts.py
+++ b/plugins/modules/current_container_facts.py
@@ -23,6 +23,7 @@
   - community.docker.attributes
   - community.docker.attributes.facts
   - community.docker.attributes.facts_module
+  - community.docker.attributes.idempotent_not_modify_state
 """
 
 EXAMPLES = r"""
diff --git a/plugins/modules/docker_compose_v2.py b/plugins/modules/docker_compose_v2.py
index 63f2b9746..aaa4d5409 100644
--- a/plugins/modules/docker_compose_v2.py
+++ b/plugins/modules/docker_compose_v2.py
@@ -33,6 +33,10 @@
       - In check mode, pulling the image does not result in a changed result.
   diff_mode:
     support: none
+  idempotent:
+    support: partial
+    details:
+      - If O(state=restarted) or O(recreate=always) the module is not idempotent.
 
 options:
   state:
diff --git a/plugins/modules/docker_compose_v2_exec.py b/plugins/modules/docker_compose_v2_exec.py
index 666fa5d06..b5c274b48 100644
--- a/plugins/modules/docker_compose_v2_exec.py
+++ b/plugins/modules/docker_compose_v2_exec.py
@@ -30,6 +30,10 @@
     support: none
   diff_mode:
     support: none
+  idempotent:
+    support: N/A
+    details:
+      - Whether the executed command is idempotent depends on the command.
 
 options:
   service:
diff --git a/plugins/modules/docker_compose_v2_pull.py b/plugins/modules/docker_compose_v2_pull.py
index 11bed9cf8..2c556c0f0 100644
--- a/plugins/modules/docker_compose_v2_pull.py
+++ b/plugins/modules/docker_compose_v2_pull.py
@@ -32,6 +32,8 @@
         pulling would update the image or not.
   diff_mode:
     support: none
+  idempotent:
+    support: full
 
 options:
   policy:
diff --git a/plugins/modules/docker_compose_v2_run.py b/plugins/modules/docker_compose_v2_run.py
index 6a0c5f9c4..4b8dce27b 100644
--- a/plugins/modules/docker_compose_v2_run.py
+++ b/plugins/modules/docker_compose_v2_run.py
@@ -30,6 +30,10 @@
     support: none
   diff_mode:
     support: none
+  idempotent:
+    support: N/A
+    details:
+      - Whether the executed command is idempotent depends on the command.
 
 options:
   service:
diff --git a/plugins/modules/docker_config.py b/plugins/modules/docker_config.py
index ecc9f404e..6ca6f2295 100644
--- a/plugins/modules/docker_config.py
+++ b/plugins/modules/docker_config.py
@@ -15,8 +15,8 @@
 
 description:
   - Create and remove Docker configs in a Swarm environment. Similar to C(docker config create) and C(docker config rm).
-  - Adds to the metadata of new configs 'ansible_key', an encrypted hash representation of the data, which is then used in
-    future runs to test if a config has changed. If 'ansible_key' is not present, then a config will not be updated unless
+  - Adds to the metadata of new configs C(ansible_key), an encrypted hash representation of the data, which is then used in
+    future runs to test if a config has changed. If C(ansible_key) is not present, then a config will not be updated unless
     the O(force) option is set.
   - Updates to configs are performed by removing the config and creating it again.
 extends_documentation_fragment:
@@ -30,6 +30,10 @@
     support: full
   diff_mode:
     support: none
+  idempotent:
+    support: partial
+    details:
+      - If O(force=true) the module is not idempotent.
 
 options:
   data:
diff --git a/plugins/modules/docker_container.py b/plugins/modules/docker_container.py
index 22c689ff2..586694925 100644
--- a/plugins/modules/docker_container.py
+++ b/plugins/modules/docker_container.py
@@ -37,6 +37,10 @@
       - This behavior can be configured with O(pull_check_mode_behavior).
   diff_mode:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - If O(recreate=true) or O(restart=true) the module is not idempotent.
 
 options:
   auto_remove:
diff --git a/plugins/modules/docker_container_copy_into.py b/plugins/modules/docker_container_copy_into.py
index 09c5e283e..3cf623cfc 100644
--- a/plugins/modules/docker_container_copy_into.py
+++ b/plugins/modules/docker_container_copy_into.py
@@ -29,6 +29,10 @@
       - Additional data will need to be transferred to compute diffs.
       - The module uses R(the MAX_FILE_SIZE_FOR_DIFF ansible-core configuration,MAX_FILE_SIZE_FOR_DIFF) to determine for how
         large files diffs should be computed.
+  idempotent:
+    support: partial
+    details:
+      - If O(force=true) the module is not idempotent.
 
 options:
   container:
diff --git a/plugins/modules/docker_container_exec.py b/plugins/modules/docker_container_exec.py
index aab338562..28e7b16cc 100644
--- a/plugins/modules/docker_container_exec.py
+++ b/plugins/modules/docker_container_exec.py
@@ -27,6 +27,10 @@
     support: none
   diff_mode:
     support: none
+  idempotent:
+    support: N/A
+    details:
+      - Whether the executed command is idempotent depends on the command.
 
 options:
   container:
diff --git a/plugins/modules/docker_container_info.py b/plugins/modules/docker_container_info.py
index ffb4b9e32..27addd4a1 100644
--- a/plugins/modules/docker_container_info.py
+++ b/plugins/modules/docker_container_info.py
@@ -22,6 +22,7 @@
   - community.docker.attributes
   - community.docker.attributes.actiongroup_docker
   - community.docker.attributes.info_module
+  - community.docker.attributes.idempotent_not_modify_state
 
 options:
   name:
diff --git a/plugins/modules/docker_host_info.py b/plugins/modules/docker_host_info.py
index 9d5ede58c..c678989d8 100644
--- a/plugins/modules/docker_host_info.py
+++ b/plugins/modules/docker_host_info.py
@@ -24,6 +24,7 @@
   - community.docker.docker.api_documentation
   - community.docker.attributes
   - community.docker.attributes.actiongroup_docker
+  - community.docker.attributes.idempotent_not_modify_state
 
 attributes:
   check_mode:
diff --git a/plugins/modules/docker_image.py b/plugins/modules/docker_image.py
index 287f2be48..dbce6c217 100644
--- a/plugins/modules/docker_image.py
+++ b/plugins/modules/docker_image.py
@@ -16,6 +16,9 @@
 description:
   - Build, load or pull an image, making the image available for creating containers. Also supports tagging an image, pushing
     an image, and archiving an image to a C(.tar) file.
+  - We recommend to use the individual modules M(community.docker.docker_image_build), M(community.docker.docker_image_export),
+    M(community.docker.docker_image_load), M(community.docker.docker_image_pull), M(community.docker.docker_image_push),
+    M(community.docker.docker_image_remove), and M(community.docker.docker_image_tag) instead of this module.
 notes:
   - Building images is done using Docker daemon's API. It is not possible to use BuildKit / buildx this way. Use M(community.docker.docker_image_build)
     to build images with BuildKit.
@@ -31,6 +34,11 @@
       - When trying to pull an image, the module assumes this is always changed in check mode.
   diff_mode:
     support: none
+  idempotent:
+    support: partial
+    details:
+      - Whether the module is idempotent depends on the exact parameters, in particular of O(force_source) and O(force_tag).
+      # TODO: improve idempotent details!
 
 options:
   source:
diff --git a/plugins/modules/docker_image_build.py b/plugins/modules/docker_image_build.py
index 3280a3c5c..182ab49b4 100644
--- a/plugins/modules/docker_image_build.py
+++ b/plugins/modules/docker_image_build.py
@@ -29,6 +29,10 @@
     support: full
   diff_mode:
     support: none
+  idempotent:
+    support: partial
+    details:
+      - If O(rebuild=always) the module is not idempotent.
 
 options:
   name:
diff --git a/plugins/modules/docker_image_export.py b/plugins/modules/docker_image_export.py
index e66ca7e48..4c0cc041f 100644
--- a/plugins/modules/docker_image_export.py
+++ b/plugins/modules/docker_image_export.py
@@ -28,6 +28,8 @@
     support: full
   diff_mode:
     support: none
+  idempotent:
+    support: full
 
 options:
   names:
diff --git a/plugins/modules/docker_image_info.py b/plugins/modules/docker_image_info.py
index 3bac5d7a0..7ff0ec9a5 100644
--- a/plugins/modules/docker_image_info.py
+++ b/plugins/modules/docker_image_info.py
@@ -27,6 +27,7 @@
   - community.docker.attributes
   - community.docker.attributes.actiongroup_docker
   - community.docker.attributes.info_module
+  - community.docker.attributes.idempotent_not_modify_state
 
 options:
   name:
diff --git a/plugins/modules/docker_image_load.py b/plugins/modules/docker_image_load.py
index 492fc14f2..2ce5b314a 100644
--- a/plugins/modules/docker_image_load.py
+++ b/plugins/modules/docker_image_load.py
@@ -28,6 +28,8 @@
     support: none
   diff_mode:
     support: none
+  idempotent:
+    support: none
 
 options:
   path:
diff --git a/plugins/modules/docker_image_pull.py b/plugins/modules/docker_image_pull.py
index 54af45988..28d22ba4f 100644
--- a/plugins/modules/docker_image_pull.py
+++ b/plugins/modules/docker_image_pull.py
@@ -30,6 +30,8 @@
       - When check mode is combined with diff mode, the pulled image's ID is always shown as V(unknown) in the diff.
   diff_mode:
     support: full
+  idempotent:
+    support: full
 
 options:
   name:
diff --git a/plugins/modules/docker_image_push.py b/plugins/modules/docker_image_push.py
index 84fa0d68f..fee386e96 100644
--- a/plugins/modules/docker_image_push.py
+++ b/plugins/modules/docker_image_push.py
@@ -27,6 +27,8 @@
     support: none
   diff_mode:
     support: none
+  idempotent:
+    support: full
 
 options:
   name:
diff --git a/plugins/modules/docker_image_remove.py b/plugins/modules/docker_image_remove.py
index 70efd4f4e..428bdb621 100644
--- a/plugins/modules/docker_image_remove.py
+++ b/plugins/modules/docker_image_remove.py
@@ -27,6 +27,8 @@
     support: full
   diff_mode:
     support: full
+  idempotent:
+    support: full
 
 options:
   name:
diff --git a/plugins/modules/docker_image_tag.py b/plugins/modules/docker_image_tag.py
index c918e3fbe..f8e3747ab 100644
--- a/plugins/modules/docker_image_tag.py
+++ b/plugins/modules/docker_image_tag.py
@@ -27,6 +27,8 @@
     support: full
   diff_mode:
     support: full
+  idempotent:
+    support: full
 
 options:
   name:
diff --git a/plugins/modules/docker_login.py b/plugins/modules/docker_login.py
index 90b814cbd..d3994f47b 100644
--- a/plugins/modules/docker_login.py
+++ b/plugins/modules/docker_login.py
@@ -31,6 +31,8 @@
     support: full
   diff_mode:
     support: none
+  idempotent:
+    support: full
 
 options:
   registry_url:
@@ -280,8 +282,7 @@ def _login(self, reauth):
         authcfg = self.client._auth_configs.resolve_authconfig(self.registry_url)
         # If we found an existing auth config for this registry and username
         # combination, we can return it immediately unless reauth is requested.
-        if authcfg and authcfg.get('username', None) == self.username \
-                and not reauth:
+        if authcfg and authcfg.get('username') == self.username and not reauth:
             return authcfg
 
         req_data = {
diff --git a/plugins/modules/docker_network.py b/plugins/modules/docker_network.py
index 695a31399..1e1aa4fbc 100644
--- a/plugins/modules/docker_network.py
+++ b/plugins/modules/docker_network.py
@@ -24,6 +24,10 @@
     support: full
   diff_mode:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - If O(force=true) the module is not idempotent.
 
 options:
   name:
diff --git a/plugins/modules/docker_network_info.py b/plugins/modules/docker_network_info.py
index 79ca89d73..5b01e6713 100644
--- a/plugins/modules/docker_network_info.py
+++ b/plugins/modules/docker_network_info.py
@@ -22,6 +22,7 @@
   - community.docker.attributes
   - community.docker.attributes.actiongroup_docker
   - community.docker.attributes.info_module
+  - community.docker.attributes.idempotent_not_modify_state
 
 options:
   name:
diff --git a/plugins/modules/docker_node.py b/plugins/modules/docker_node.py
index e7aab0ee4..917dcbe9e 100644
--- a/plugins/modules/docker_node.py
+++ b/plugins/modules/docker_node.py
@@ -25,6 +25,8 @@
     support: full
   diff_mode:
     support: none
+  idempotent:
+    support: full
 
 options:
   hostname:
diff --git a/plugins/modules/docker_node_info.py b/plugins/modules/docker_node_info.py
index f664f9be7..29434b16a 100644
--- a/plugins/modules/docker_node_info.py
+++ b/plugins/modules/docker_node_info.py
@@ -23,6 +23,7 @@
   - community.docker.attributes
   - community.docker.attributes.actiongroup_docker
   - community.docker.attributes.info_module
+  - community.docker.attributes.idempotent_not_modify_state
 
 options:
   name:
diff --git a/plugins/modules/docker_plugin.py b/plugins/modules/docker_plugin.py
index 718848f16..c116b95a1 100644
--- a/plugins/modules/docker_plugin.py
+++ b/plugins/modules/docker_plugin.py
@@ -29,6 +29,8 @@
     support: full
   diff_mode:
     support: full
+  idempotent:
+    support: full
 
 options:
   plugin_name:
diff --git a/plugins/modules/docker_prune.py b/plugins/modules/docker_prune.py
index 51bdf11a3..bad9c5d83 100644
--- a/plugins/modules/docker_prune.py
+++ b/plugins/modules/docker_prune.py
@@ -26,6 +26,8 @@
     support: none
   diff_mode:
     support: none
+  idempotent:
+    support: full
 
 options:
   containers:
diff --git a/plugins/modules/docker_secret.py b/plugins/modules/docker_secret.py
index 564bdf5cf..78d05a9b1 100644
--- a/plugins/modules/docker_secret.py
+++ b/plugins/modules/docker_secret.py
@@ -30,6 +30,10 @@
     support: full
   diff_mode:
     support: none
+  idempotent:
+    support: partial
+    details:
+      - If O(force=true) the module is not idempotent.
 
 options:
   data:
diff --git a/plugins/modules/docker_stack.py b/plugins/modules/docker_stack.py
index ff5f6c937..6e3accc80 100644
--- a/plugins/modules/docker_stack.py
+++ b/plugins/modules/docker_stack.py
@@ -26,6 +26,8 @@
     support: none
   action_group:
     version_added: 3.6.0
+  idempotent:
+    support: full
 options:
   name:
     description:
diff --git a/plugins/modules/docker_stack_info.py b/plugins/modules/docker_stack_info.py
index 1e97d0b2b..41f7d6c00 100644
--- a/plugins/modules/docker_stack_info.py
+++ b/plugins/modules/docker_stack_info.py
@@ -22,6 +22,7 @@
   - community.docker.attributes
   - community.docker.attributes.actiongroup_docker
   - community.docker.attributes.info_module
+  - community.docker.attributes.idempotent_not_modify_state
 attributes:
   action_group:
     version_added: 3.6.0
diff --git a/plugins/modules/docker_stack_task_info.py b/plugins/modules/docker_stack_task_info.py
index c7dc9242a..a89e074b0 100644
--- a/plugins/modules/docker_stack_task_info.py
+++ b/plugins/modules/docker_stack_task_info.py
@@ -20,6 +20,7 @@
   - community.docker.attributes
   - community.docker.attributes.actiongroup_docker
   - community.docker.attributes.info_module
+  - community.docker.attributes.idempotent_not_modify_state
 attributes:
   action_group:
     version_added: 3.6.0
diff --git a/plugins/modules/docker_swarm.py b/plugins/modules/docker_swarm.py
index 9967c8b40..de3169456 100644
--- a/plugins/modules/docker_swarm.py
+++ b/plugins/modules/docker_swarm.py
@@ -24,6 +24,8 @@
     support: full
   diff_mode:
     support: full
+  idempotent:
+    support: full
 
 options:
   advertise_addr:
diff --git a/plugins/modules/docker_swarm_info.py b/plugins/modules/docker_swarm_info.py
index 0f4278c25..6f8b4af26 100644
--- a/plugins/modules/docker_swarm_info.py
+++ b/plugins/modules/docker_swarm_info.py
@@ -29,6 +29,7 @@
   - community.docker.attributes
   - community.docker.attributes.actiongroup_docker
   - community.docker.attributes.info_module
+  - community.docker.attributes.idempotent_not_modify_state
 
 options:
   nodes:
diff --git a/plugins/modules/docker_swarm_service.py b/plugins/modules/docker_swarm_service.py
index 5d1ca730c..7a8f75e23 100644
--- a/plugins/modules/docker_swarm_service.py
+++ b/plugins/modules/docker_swarm_service.py
@@ -29,6 +29,8 @@
     support: full
   diff_mode:
     support: full
+  idempotent:
+    support: full
 
 options:
   args:
diff --git a/plugins/modules/docker_swarm_service_info.py b/plugins/modules/docker_swarm_service_info.py
index 3c8c95216..66a73f9af 100644
--- a/plugins/modules/docker_swarm_service_info.py
+++ b/plugins/modules/docker_swarm_service_info.py
@@ -23,6 +23,7 @@
   - community.docker.attributes
   - community.docker.attributes.actiongroup_docker
   - community.docker.attributes.info_module
+  - community.docker.attributes.idempotent_not_modify_state
 
 options:
   name:
diff --git a/plugins/modules/docker_volume.py b/plugins/modules/docker_volume.py
index 8f1ac3215..7d46688bc 100644
--- a/plugins/modules/docker_volume.py
+++ b/plugins/modules/docker_volume.py
@@ -25,6 +25,10 @@
     support: full
   diff_mode:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - If O(recreate=always) the module is not idempotent.
 
 options:
   volume_name:
diff --git a/plugins/modules/docker_volume_info.py b/plugins/modules/docker_volume_info.py
index 18e7260e6..04012b052 100644
--- a/plugins/modules/docker_volume_info.py
+++ b/plugins/modules/docker_volume_info.py
@@ -19,6 +19,7 @@
   - community.docker.attributes
   - community.docker.attributes.actiongroup_docker
   - community.docker.attributes.info_module
+  - community.docker.attributes.idempotent_not_modify_state
 
 options:
   name:

From 436818489ebe0d45e8171b3fcd7e5aa8b9a7318e Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Mon, 30 Dec 2024 20:06:53 +0100
Subject: [PATCH 2/2] Mention check mode in attribute description.

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
---
 plugins/doc_fragments/attributes.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py
index 0bcd5c34c..02faa71ea 100644
--- a/plugins/doc_fragments/attributes.py
+++ b/plugins/doc_fragments/attributes.py
@@ -20,7 +20,7 @@ class ModuleDocFragment(object):
     description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
   idempotent:
     description:
-      - When run twice in a row with the same arguments, the second invocation indicates no change.
+      - When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.
       - This assumes that the system controlled/queried by the module has not changed in a relevant way.
 """