From 36c118d1547f15930b58c9356744c28f37cb4dc3 Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Sat, 11 May 2024 15:53:19 +0200
Subject: [PATCH] Deprecate ssl_version. (#853)

---
 changelogs/fragments/853-ssl_version.yml | 4 ++++
 plugins/connection/docker_api.py         | 1 +
 plugins/doc_fragments/docker.py          | 9 +++++++++
 plugins/inventory/docker_containers.py   | 1 +
 plugins/inventory/docker_swarm.py        | 3 +++
 plugins/module_utils/util.py             | 7 ++++++-
 6 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/fragments/853-ssl_version.yml

diff --git a/changelogs/fragments/853-ssl_version.yml b/changelogs/fragments/853-ssl_version.yml
new file mode 100644
index 00000000..60b39701
--- /dev/null
+++ b/changelogs/fragments/853-ssl_version.yml
@@ -0,0 +1,4 @@
+deprecated_features:
+  - "various modules and plugins - the ``ssl_version`` option has been deprecated and will be removed from community.docker 4.0.0.
+     It has already been removed from Docker SDK for Python 7.0.0, and was only necessary in the past to work around SSL/TLS issues
+     (https://github.com/ansible-collections/community.docker/pull/853)."
diff --git a/plugins/connection/docker_api.py b/plugins/connection/docker_api.py
index 3b99281c..a6dec85a 100644
--- a/plugins/connection/docker_api.py
+++ b/plugins/connection/docker_api.py
@@ -21,6 +21,7 @@ notes:
       with Python's C(SSLSocket)s. See U(https://github.com/ansible-collections/community.docker/issues/605) for more information.
 extends_documentation_fragment:
     - community.docker.docker.api_documentation
+    - community.docker.docker.ssl_version_deprecation
     - community.docker.docker.var_names
 options:
     remote_user:
diff --git a/plugins/doc_fragments/docker.py b/plugins/doc_fragments/docker.py
index 92989a97..2c78c5fa 100644
--- a/plugins/doc_fragments/docker.py
+++ b/plugins/doc_fragments/docker.py
@@ -392,3 +392,12 @@ notes:
   - This module does B(not) use the L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) to
     communicate with the Docker daemon. It directly calls the Docker CLI program.
 '''
+
+    # DEPRECATED: this will be removed from community.docker 4.0.0! Use with care!
+    SSL_VERSION_DEPRECATION = '''
+options:
+    ssl_version:
+        deprecated:
+            why: This was necessary a long time ago to handle problems with older TLS/SSL versions. It is no longer necessary nowadays.
+            version: 4.0.0
+'''
diff --git a/plugins/inventory/docker_containers.py b/plugins/inventory/docker_containers.py
index 0cae0547..f353b03b 100644
--- a/plugins/inventory/docker_containers.py
+++ b/plugins/inventory/docker_containers.py
@@ -21,6 +21,7 @@ author:
 extends_documentation_fragment:
     - ansible.builtin.constructed
     - community.docker.docker.api_documentation
+    - community.docker.docker.ssl_version_deprecation
     - community.library_inventory_filtering_v1.inventory_filter
 description:
     - Reads inventories from the Docker API.
diff --git a/plugins/inventory/docker_swarm.py b/plugins/inventory/docker_swarm.py
index acceac86..6d1556ff 100644
--- a/plugins/inventory/docker_swarm.py
+++ b/plugins/inventory/docker_swarm.py
@@ -78,6 +78,9 @@ DOCUMENTATION = '''
                 - Provide a valid SSL version number. Default value determined
                   by L(SSL Python module, https://docs.python.org/3/library/ssl.html).
             type: str
+            deprecated:
+                why: This was necessary a long time ago to handle problems with SSL versions. It is no longer necessary nowadays.
+                version: 4.0.0
         api_version:
             description:
                 - The version of the Docker API running on the Docker Host.
diff --git a/plugins/module_utils/util.py b/plugins/module_utils/util.py
index cad6408d..f519e98f 100644
--- a/plugins/module_utils/util.py
+++ b/plugins/module_utils/util.py
@@ -29,7 +29,12 @@ DOCKER_COMMON_ARGS = dict(
     ca_path=dict(type='path', aliases=['ca_cert', 'tls_ca_cert', 'cacert_path']),
     client_cert=dict(type='path', aliases=['tls_client_cert', 'cert_path']),
     client_key=dict(type='path', aliases=['tls_client_key', 'key_path']),
-    ssl_version=dict(type='str', fallback=(env_fallback, ['DOCKER_SSL_VERSION'])),
+    ssl_version=dict(
+        type='str',
+        fallback=(env_fallback, ['DOCKER_SSL_VERSION']),
+        removed_in_version='4.0.0',
+        removed_from_collection='community.docker',
+    ),
     tls=dict(type='bool', default=DEFAULT_TLS, fallback=(env_fallback, ['DOCKER_TLS'])),
     use_ssh_client=dict(type='bool', default=False),
     validate_certs=dict(type='bool', default=DEFAULT_TLS_VERIFY, fallback=(env_fallback, ['DOCKER_TLS_VERIFY']), aliases=['tls_verify']),