diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py index e5305b84..02faa71e 100644 --- a/plugins/doc_fragments/attributes.py +++ b/plugins/doc_fragments/attributes.py @@ -18,6 +18,20 @@ attributes: 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 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. +""" + + # 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 1b05ad0f..621965ad 100644 --- a/plugins/modules/current_container_facts.py +++ b/plugins/modules/current_container_facts.py @@ -23,6 +23,7 @@ extends_documentation_fragment: - 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 63f2b974..aaa4d540 100644 --- a/plugins/modules/docker_compose_v2.py +++ b/plugins/modules/docker_compose_v2.py @@ -33,6 +33,10 @@ attributes: - 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 666fa5d0..b5c274b4 100644 --- a/plugins/modules/docker_compose_v2_exec.py +++ b/plugins/modules/docker_compose_v2_exec.py @@ -30,6 +30,10 @@ attributes: 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 11bed9cf..2c556c0f 100644 --- a/plugins/modules/docker_compose_v2_pull.py +++ b/plugins/modules/docker_compose_v2_pull.py @@ -32,6 +32,8 @@ attributes: 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 6a0c5f9c..4b8dce27 100644 --- a/plugins/modules/docker_compose_v2_run.py +++ b/plugins/modules/docker_compose_v2_run.py @@ -30,6 +30,10 @@ attributes: 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 ecc9f404..6ca6f229 100644 --- a/plugins/modules/docker_config.py +++ b/plugins/modules/docker_config.py @@ -15,8 +15,8 @@ short_description: Manage docker configs 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 @@ attributes: 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 22c689ff..58669492 100644 --- a/plugins/modules/docker_container.py +++ b/plugins/modules/docker_container.py @@ -37,6 +37,10 @@ attributes: - 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 09c5e283..3cf623cf 100644 --- a/plugins/modules/docker_container_copy_into.py +++ b/plugins/modules/docker_container_copy_into.py @@ -29,6 +29,10 @@ attributes: - 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 aab33856..28e7b16c 100644 --- a/plugins/modules/docker_container_exec.py +++ b/plugins/modules/docker_container_exec.py @@ -27,6 +27,10 @@ attributes: 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 ffb4b9e3..27addd4a 100644 --- a/plugins/modules/docker_container_info.py +++ b/plugins/modules/docker_container_info.py @@ -22,6 +22,7 @@ extends_documentation_fragment: - 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 9d5ede58..c678989d 100644 --- a/plugins/modules/docker_host_info.py +++ b/plugins/modules/docker_host_info.py @@ -24,6 +24,7 @@ extends_documentation_fragment: - 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 287f2be4..dbce6c21 100644 --- a/plugins/modules/docker_image.py +++ b/plugins/modules/docker_image.py @@ -16,6 +16,9 @@ short_description: Manage docker images 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 @@ attributes: - 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 3280a3c5..182ab49b 100644 --- a/plugins/modules/docker_image_build.py +++ b/plugins/modules/docker_image_build.py @@ -29,6 +29,10 @@ attributes: 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 e66ca7e4..4c0cc041 100644 --- a/plugins/modules/docker_image_export.py +++ b/plugins/modules/docker_image_export.py @@ -28,6 +28,8 @@ attributes: 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 3bac5d7a..7ff0ec9a 100644 --- a/plugins/modules/docker_image_info.py +++ b/plugins/modules/docker_image_info.py @@ -27,6 +27,7 @@ extends_documentation_fragment: - 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 492fc14f..2ce5b314 100644 --- a/plugins/modules/docker_image_load.py +++ b/plugins/modules/docker_image_load.py @@ -28,6 +28,8 @@ attributes: 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 54af4598..28d22ba4 100644 --- a/plugins/modules/docker_image_pull.py +++ b/plugins/modules/docker_image_pull.py @@ -30,6 +30,8 @@ attributes: - 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 84fa0d68..fee386e9 100644 --- a/plugins/modules/docker_image_push.py +++ b/plugins/modules/docker_image_push.py @@ -27,6 +27,8 @@ attributes: 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 70efd4f4..428bdb62 100644 --- a/plugins/modules/docker_image_remove.py +++ b/plugins/modules/docker_image_remove.py @@ -27,6 +27,8 @@ attributes: 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 c918e3fb..f8e3747a 100644 --- a/plugins/modules/docker_image_tag.py +++ b/plugins/modules/docker_image_tag.py @@ -27,6 +27,8 @@ attributes: 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 90b814cb..d3994f47 100644 --- a/plugins/modules/docker_login.py +++ b/plugins/modules/docker_login.py @@ -31,6 +31,8 @@ attributes: support: full diff_mode: support: none + idempotent: + support: full options: registry_url: @@ -280,8 +282,7 @@ class LoginManager(DockerBaseClass): 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 695a3139..1e1aa4fb 100644 --- a/plugins/modules/docker_network.py +++ b/plugins/modules/docker_network.py @@ -24,6 +24,10 @@ attributes: 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 79ca89d7..5b01e671 100644 --- a/plugins/modules/docker_network_info.py +++ b/plugins/modules/docker_network_info.py @@ -22,6 +22,7 @@ extends_documentation_fragment: - 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 e7aab0ee..917dcbe9 100644 --- a/plugins/modules/docker_node.py +++ b/plugins/modules/docker_node.py @@ -25,6 +25,8 @@ attributes: 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 f664f9be..29434b16 100644 --- a/plugins/modules/docker_node_info.py +++ b/plugins/modules/docker_node_info.py @@ -23,6 +23,7 @@ extends_documentation_fragment: - 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 718848f1..c116b95a 100644 --- a/plugins/modules/docker_plugin.py +++ b/plugins/modules/docker_plugin.py @@ -29,6 +29,8 @@ attributes: 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 51bdf11a..bad9c5d8 100644 --- a/plugins/modules/docker_prune.py +++ b/plugins/modules/docker_prune.py @@ -26,6 +26,8 @@ attributes: 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 564bdf5c..78d05a9b 100644 --- a/plugins/modules/docker_secret.py +++ b/plugins/modules/docker_secret.py @@ -30,6 +30,10 @@ attributes: 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 ff5f6c93..6e3accc8 100644 --- a/plugins/modules/docker_stack.py +++ b/plugins/modules/docker_stack.py @@ -26,6 +26,8 @@ attributes: 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 1e97d0b2..41f7d6c0 100644 --- a/plugins/modules/docker_stack_info.py +++ b/plugins/modules/docker_stack_info.py @@ -22,6 +22,7 @@ extends_documentation_fragment: - 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 c7dc9242..a89e074b 100644 --- a/plugins/modules/docker_stack_task_info.py +++ b/plugins/modules/docker_stack_task_info.py @@ -20,6 +20,7 @@ extends_documentation_fragment: - 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 9967c8b4..de316945 100644 --- a/plugins/modules/docker_swarm.py +++ b/plugins/modules/docker_swarm.py @@ -24,6 +24,8 @@ attributes: 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 0f4278c2..6f8b4af2 100644 --- a/plugins/modules/docker_swarm_info.py +++ b/plugins/modules/docker_swarm_info.py @@ -29,6 +29,7 @@ extends_documentation_fragment: - 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 5d1ca730..7a8f75e2 100644 --- a/plugins/modules/docker_swarm_service.py +++ b/plugins/modules/docker_swarm_service.py @@ -29,6 +29,8 @@ attributes: 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 3c8c9521..66a73f9a 100644 --- a/plugins/modules/docker_swarm_service_info.py +++ b/plugins/modules/docker_swarm_service_info.py @@ -23,6 +23,7 @@ extends_documentation_fragment: - 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 8f1ac321..7d46688b 100644 --- a/plugins/modules/docker_volume.py +++ b/plugins/modules/docker_volume.py @@ -25,6 +25,10 @@ attributes: 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 18e7260e..04012b05 100644 --- a/plugins/modules/docker_volume_info.py +++ b/plugins/modules/docker_volume_info.py @@ -19,6 +19,7 @@ extends_documentation_fragment: - community.docker.attributes - community.docker.attributes.actiongroup_docker - community.docker.attributes.info_module + - community.docker.attributes.idempotent_not_modify_state options: name: