Rename ca_cert option to ca_path (#744)

* Rename ca_cert option to ca_path.

* Two more.

changelogs/fragments/744-ca_path.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "The ``ca_cert`` option available to almost all modules and plugins has been renamed to ``ca_path``. The name ``ca_path`` is also used for similar options in ansible-core and other collections. The old name has been added as an alias and can still be used (https://github.com/ansible-collections/community.docker/pull/744)."

docs/docsite/rst/scenario_guide.rst

@@ -63,7 +63,7 @@ Most plugins and modules can be configured by the following parameters:
     validate_certs
         Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server. Default is ``false``.
 
-    cacert_path
+    ca_path
         Use a CA certificate when performing server verification by providing the path to a CA certificate file.
 
     cert_path
@@ -106,7 +106,7 @@ The following example shows how the module default group can be used in a playbo
           tls: true
           validate_certs: true
           tls_hostname: docker.example.com
-          cacert_path: /path/to/cacert.pem
+          ca_path: /path/to/cacert.pem
           # Increase timeout
           timeout: 120
       tasks:

plugins/doc_fragments/docker.py

@@ -48,13 +48,15 @@ options:
               instead. If the environment variable is not set, the default value will be used.
         type: int
         default: 60
-    ca_cert:
+    ca_path:
         description:
             - Use a CA certificate when performing server verification by providing the path to a CA certificate file.
             - If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
               the file C(ca.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
+            - This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker 3.6.0. The old name has
+              been added as an alias and can still be used.
         type: path
-        aliases: [ tls_ca_cert, cacert_path ]
+        aliases: [ ca_cert, tls_ca_cert, cacert_path ]
     client_cert:
         description:
             - Path to the client's TLS certificate file.
@@ -135,9 +137,11 @@ options:
     timeout:
         vars:
             - name: ansible_docker_timeout
-    ca_cert:
+    ca_path:
         vars:
             - name: ansible_docker_ca_cert
+            - name: ansible_docker_ca_path
+              version_added: 3.6.0
     client_cert:
         vars:
             - name: ansible_docker_client_cert
@@ -223,13 +227,15 @@ options:
               instead. If the environment variable is not set, the default value will be used.
         type: int
         default: 60
-    ca_cert:
+    ca_path:
         description:
             - Use a CA certificate when performing server verification by providing the path to a CA certificate file.
             - If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
               the file C(ca.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
+            - This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker 3.6.0. The old name has
+              been added as an alias and can still be used.
         type: path
-        aliases: [ tls_ca_cert, cacert_path ]
+        aliases: [ ca_cert, tls_ca_cert, cacert_path ]
     client_cert:
         description:
             - Path to the client's TLS certificate file.
@@ -330,13 +336,13 @@ options:
         type: str
         default: auto
         aliases: [ docker_api_version ]
-    ca_cert:
+    ca_path:
         description:
             - Use a CA certificate when performing server verification by providing the path to a CA certificate file.
             - If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH) is set,
               the file C(ca.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
         type: path
-        aliases: [ tls_ca_cert, cacert_path ]
+        aliases: [ ca_cert, tls_ca_cert, cacert_path ]
     client_cert:
         description:
             - Path to the client's TLS certificate file.

plugins/inventory/docker_containers.py

@@ -121,7 +121,7 @@ tls: true
 plugin: community.docker.docker_containers
 docker_host: tcp://my-docker-host:2376
 validate_certs: true
-ca_cert: /somewhere/ca.pem
+ca_path: /somewhere/ca.pem
 client_key: /somewhere/key.pem
 client_cert: /somewhere/cert.pem
 

plugins/inventory/docker_swarm.py

@@ -57,11 +57,13 @@ DOCUMENTATION = '''
             description: Path to the client's TLS key file.
             type: path
             aliases: [ tls_client_key, key_path ]
-        ca_cert:
+        ca_path:
-            description: Use a CA certificate when performing server verification by providing the path to a CA
+            description:
-                         certificate file.
+              - Use a CA certificate when performing server verification by providing the path to a CA certificate file.
+              - This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker 3.6.0. The old name has
+                been added as an alias and can still be used.
             type: path
-            aliases: [ tls_ca_cert, cacert_path ]
+            aliases: [ ca_cert, tls_ca_cert, cacert_path ]
         client_cert:
             description: Path to the client's TLS certificate file.
             type: path
@@ -126,7 +128,7 @@ tls: true
 plugin: community.docker.docker_swarm
 docker_host: tcp://my-docker-host:2376
 validate_certs: true
-ca_cert: /somewhere/ca.pem
+ca_path: /somewhere/ca.pem
 client_key: /somewhere/key.pem
 client_cert: /somewhere/cert.pem
 
@@ -176,7 +178,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
             tls=self.get_option('tls'),
             tls_verify=self.get_option('validate_certs'),
             key_path=self.get_option('client_key'),
-            cacert_path=self.get_option('ca_cert'),
+            cacert_path=self.get_option('ca_path'),
             cert_path=self.get_option('client_cert'),
             tls_hostname=self.get_option('tls_hostname'),
             api_version=self.get_option('api_version'),

plugins/module_utils/common.py

@@ -331,7 +331,7 @@ class AnsibleDockerClientBase(Client):
                                          'DOCKER_TLS_HOSTNAME', None, type='str'),
             api_version=self._get_value('api_version', params['api_version'], 'DOCKER_API_VERSION',
                                         'auto', type='str'),
-            cacert_path=self._get_value('cacert_path', params['ca_cert'], 'DOCKER_CERT_PATH', None, type='str'),
+            cacert_path=self._get_value('cacert_path', params['ca_path'], 'DOCKER_CERT_PATH', None, type='str'),
             cert_path=self._get_value('cert_path', params['client_cert'], 'DOCKER_CERT_PATH', None, type='str'),
             key_path=self._get_value('key_path', params['client_key'], 'DOCKER_CERT_PATH', None, type='str'),
             ssl_version=self._get_value('ssl_version', params['ssl_version'], 'DOCKER_SSL_VERSION', None, type='str'),

plugins/module_utils/common_api.py

@@ -202,7 +202,7 @@ class AnsibleDockerClientBase(Client):
                                          'DOCKER_TLS_HOSTNAME', None, type='str'),
             api_version=self._get_value('api_version', params['api_version'], 'DOCKER_API_VERSION',
                                         'auto', type='str'),
-            cacert_path=self._get_value('cacert_path', params['ca_cert'], 'DOCKER_CERT_PATH', None, type='str'),
+            cacert_path=self._get_value('cacert_path', params['ca_path'], 'DOCKER_CERT_PATH', None, type='str'),
             cert_path=self._get_value('cert_path', params['client_cert'], 'DOCKER_CERT_PATH', None, type='str'),
             key_path=self._get_value('key_path', params['client_key'], 'DOCKER_CERT_PATH', None, type='str'),
             ssl_version=self._get_value('ssl_version', params['ssl_version'], 'DOCKER_SSL_VERSION', None, type='str'),

plugins/module_utils/common_cli.py

@@ -33,7 +33,7 @@ DOCKER_COMMON_ARGS = dict(
     docker_host=dict(type='str', default=DEFAULT_DOCKER_HOST, fallback=(env_fallback, ['DOCKER_HOST']), aliases=['docker_url']),
     tls_hostname=dict(type='str', fallback=(env_fallback, ['DOCKER_TLS_HOSTNAME'])),
     api_version=dict(type='str', default='auto', fallback=(env_fallback, ['DOCKER_API_VERSION']), aliases=['docker_api_version']),
-    ca_cert=dict(type='path', aliases=['tls_ca_cert', 'cacert_path']),
+    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']),
     tls=dict(type='bool', default=DEFAULT_TLS, fallback=(env_fallback, ['DOCKER_TLS'])),
@@ -67,8 +67,8 @@ class AnsibleDockerClientBase(object):
             self._cli_base.append('--tlsverify')
         elif common_args['tls']:
             self._cli_base.append('--tls')
-        if common_args['ca_cert']:
+        if common_args['ca_path']:
-            self._cli_base.extend(['--tlscacert', common_args['ca_cert']])
+            self._cli_base.extend(['--tlscacert', common_args['ca_path']])
         if common_args['client_cert']:
             self._cli_base.extend(['--tlscert', common_args['client_cert']])
         if common_args['client_key']:

plugins/module_utils/util.py

@@ -26,7 +26,7 @@ DOCKER_COMMON_ARGS = dict(
     tls_hostname=dict(type='str', fallback=(env_fallback, ['DOCKER_TLS_HOSTNAME'])),
     api_version=dict(type='str', default='auto', fallback=(env_fallback, ['DOCKER_API_VERSION']), aliases=['docker_api_version']),
     timeout=dict(type='int', default=DEFAULT_TIMEOUT_SECONDS, fallback=(env_fallback, ['DOCKER_TIMEOUT'])),
-    ca_cert=dict(type='path', aliases=['tls_ca_cert', 'cacert_path']),
+    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'])),