From 4a5293503e8a6a57e5fb4d22845d7bdae86d46c6 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 6 Jan 2024 17:03:39 +0100 Subject: [PATCH] Rename ca_cert option to ca_path (#744) * Rename ca_cert option to ca_path. * Two more. --- changelogs/fragments/744-ca_path.yml | 2 ++ docs/docsite/rst/scenario_guide.rst | 4 ++-- plugins/doc_fragments/docker.py | 20 +++++++++++++------- plugins/inventory/docker_containers.py | 2 +- plugins/inventory/docker_swarm.py | 14 ++++++++------ plugins/module_utils/common.py | 2 +- plugins/module_utils/common_api.py | 2 +- plugins/module_utils/common_cli.py | 6 +++--- plugins/module_utils/util.py | 2 +- 9 files changed, 32 insertions(+), 22 deletions(-) create mode 100644 changelogs/fragments/744-ca_path.yml diff --git a/changelogs/fragments/744-ca_path.yml b/changelogs/fragments/744-ca_path.yml new file mode 100644 index 00000000..2decbc6a --- /dev/null +++ b/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)." diff --git a/docs/docsite/rst/scenario_guide.rst b/docs/docsite/rst/scenario_guide.rst index 11684664..6b2d0dc8 100644 --- a/docs/docsite/rst/scenario_guide.rst +++ b/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: diff --git a/plugins/doc_fragments/docker.py b/plugins/doc_fragments/docker.py index 99cb9f1d..92989a97 100644 --- a/plugins/doc_fragments/docker.py +++ b/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. diff --git a/plugins/inventory/docker_containers.py b/plugins/inventory/docker_containers.py index 0d319397..254e1685 100644 --- a/plugins/inventory/docker_containers.py +++ b/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 diff --git a/plugins/inventory/docker_swarm.py b/plugins/inventory/docker_swarm.py index 8733a8e1..f8c34581 100644 --- a/plugins/inventory/docker_swarm.py +++ b/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: - description: Use a CA certificate when performing server verification by providing the path to a CA - certificate file. + ca_path: + description: + - 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'), diff --git a/plugins/module_utils/common.py b/plugins/module_utils/common.py index 7f6ed14f..d1dcf3e6 100644 --- a/plugins/module_utils/common.py +++ b/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'), diff --git a/plugins/module_utils/common_api.py b/plugins/module_utils/common_api.py index 1d63b541..b5ea42fa 100644 --- a/plugins/module_utils/common_api.py +++ b/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'), diff --git a/plugins/module_utils/common_cli.py b/plugins/module_utils/common_cli.py index 5d5da556..60d53987 100644 --- a/plugins/module_utils/common_cli.py +++ b/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']: - self._cli_base.extend(['--tlscacert', common_args['ca_cert']]) + if common_args['ca_path']: + 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']: diff --git a/plugins/module_utils/util.py b/plugins/module_utils/util.py index a2b3e907..efd3301f 100644 --- a/plugins/module_utils/util.py +++ b/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'])),