From ad1618633f9af1f2d829be45f5ea0029e6f85fbb Mon Sep 17 00:00:00 2001 From: Jonathan Rosser Date: Thu, 23 Jan 2025 12:05:10 +0000 Subject: [PATCH] Automatically import ssh connection plugin options from the base class It has been necessary to manually keep the OSA connection plugin module options matching those in the builtin ssh connection plugin that it is derived from. It is possible for differences to accumulate over time as ansible versions are updated and this can lead to errors, and difficult using the plugin with different versions of ansible. This patch uses the "documentation fragments" ansible feature, but instead of statically defining the options in the fragment, the builtin ssh connection plugin is loaded and the options section from the DOCUMENTATION string is extracted and re-used. Change-Id: Id1879c706a980c37dc68544f1230bd4733135959 --- plugins/connection/ssh.py | 342 +----------------- plugins/doc_fragments/builtin_ssh_fragment.py | 12 + 2 files changed, 17 insertions(+), 337 deletions(-) create mode 100644 plugins/doc_fragments/builtin_ssh_fragment.py diff --git a/plugins/connection/ssh.py b/plugins/connection/ssh.py index 0026105b..b9c69fc8 100644 --- a/plugins/connection/ssh.py +++ b/plugins/connection/ssh.py @@ -21,6 +21,11 @@ DOCUMENTATION = ''' - This connection plugin allows ansible to communicate to the target machines via normal ssh command line. author: ansible (@core) version_added: historical + + # import all existing options from the ansible.builtin.ssh connection plugin + extends_documentation_fragment: openstack.osa.builtin_ssh_fragment + + # define additional options that extend the builtin connection plugin options: container_name: description: Hostname of a container @@ -38,343 +43,6 @@ DOCUMENTATION = ''' description: Hostname of host running a given container vars: - name: physical_host - host: - description: Hostname/IP to connect to. - default: inventory_hostname - type: string - vars: - - name: inventory_hostname - - name: ansible_host - - name: ansible_ssh_host - - name: delegated_vars['ansible_host'] - - name: delegated_vars['ansible_ssh_host'] - host_key_checking: - description: Determines if SSH should reject or not a connection after checking host keys. - default: True - type: boolean - ini: - - section: defaults - key: 'host_key_checking' - - section: ssh_connection - key: 'host_key_checking' - version_added: '2.5' - env: - - name: ANSIBLE_HOST_KEY_CHECKING - - name: ANSIBLE_SSH_HOST_KEY_CHECKING - version_added: '2.5' - vars: - - name: ansible_host_key_checking - version_added: '2.5' - - name: ansible_ssh_host_key_checking - version_added: '2.5' - password: - description: Authentication password for the O(remote_user). Can be supplied as CLI option. - type: string - vars: - - name: ansible_password - - name: ansible_ssh_pass - - name: ansible_ssh_password - sshpass_prompt: - description: - - Password prompt that sshpass should search for. Supported by sshpass 1.06 and up. - - Defaults to C(Enter PIN for) when pkcs11_provider is set. - default: '' - type: string - ini: - - section: 'ssh_connection' - key: 'sshpass_prompt' - env: - - name: ANSIBLE_SSHPASS_PROMPT - vars: - - name: ansible_sshpass_prompt - version_added: '2.10' - ssh_args: - description: Arguments to pass to all SSH CLI tools. - default: '-C -o ControlMaster=auto -o ControlPersist=60s' - type: string - ini: - - section: 'ssh_connection' - key: 'ssh_args' - env: - - name: ANSIBLE_SSH_ARGS - vars: - - name: ansible_ssh_args - version_added: '2.7' - ssh_common_args: - description: Common extra args for all SSH CLI tools. - type: string - ini: - - section: 'ssh_connection' - key: 'ssh_common_args' - version_added: '2.7' - env: - - name: ANSIBLE_SSH_COMMON_ARGS - version_added: '2.7' - vars: - - name: ansible_ssh_common_args - cli: - - name: ssh_common_args - default: '' - ssh_executable: - default: ssh - description: - - This defines the location of the SSH binary. It defaults to V(ssh) which will use the first SSH binary available in $PATH. - - This option is usually not required, it might be useful when access to system SSH is restricted, - or when using SSH wrappers to connect to remote hosts. - type: string - env: [{name: ANSIBLE_SSH_EXECUTABLE}] - ini: - - {key: ssh_executable, section: ssh_connection} - #const: ANSIBLE_SSH_EXECUTABLE - version_added: "2.2" - vars: - - name: ansible_ssh_executable - version_added: '2.7' - sftp_executable: - default: sftp - description: - - This defines the location of the sftp binary. It defaults to V(sftp) which will use the first binary available in $PATH. - type: string - env: [{name: ANSIBLE_SFTP_EXECUTABLE}] - ini: - - {key: sftp_executable, section: ssh_connection} - version_added: "2.6" - vars: - - name: ansible_sftp_executable - version_added: '2.7' - scp_executable: - default: scp - description: - - This defines the location of the scp binary. It defaults to V(scp) which will use the first binary available in $PATH. - type: string - env: [{name: ANSIBLE_SCP_EXECUTABLE}] - ini: - - {key: scp_executable, section: ssh_connection} - version_added: "2.6" - vars: - - name: ansible_scp_executable - version_added: '2.7' - scp_extra_args: - description: Extra exclusive to the C(scp) CLI - type: string - vars: - - name: ansible_scp_extra_args - env: - - name: ANSIBLE_SCP_EXTRA_ARGS - version_added: '2.7' - ini: - - key: scp_extra_args - section: ssh_connection - version_added: '2.7' - cli: - - name: scp_extra_args - default: '' - sftp_extra_args: - description: Extra exclusive to the C(sftp) CLI - type: string - vars: - - name: ansible_sftp_extra_args - env: - - name: ANSIBLE_SFTP_EXTRA_ARGS - version_added: '2.7' - ini: - - key: sftp_extra_args - section: ssh_connection - version_added: '2.7' - cli: - - name: sftp_extra_args - default: '' - ssh_extra_args: - description: Extra exclusive to the SSH CLI. - type: string - vars: - - name: ansible_ssh_extra_args - env: - - name: ANSIBLE_SSH_EXTRA_ARGS - version_added: '2.7' - ini: - - key: ssh_extra_args - section: ssh_connection - version_added: '2.7' - cli: - - name: ssh_extra_args - default: '' - reconnection_retries: - description: - - Number of attempts to connect. - - Ansible retries connections only if it gets an SSH error with a return code of 255. - - Any errors with return codes other than 255 indicate an issue with program execution. - default: 0 - type: integer - env: - - name: ANSIBLE_SSH_RETRIES - ini: - - section: connection - key: retries - - section: ssh_connection - key: retries - vars: - - name: ansible_ssh_retries - version_added: '2.7' - port: - description: Remote port to connect to. - type: int - ini: - - section: defaults - key: remote_port - env: - - name: ANSIBLE_REMOTE_PORT - vars: - - name: ansible_port - - name: ansible_ssh_port - keyword: - - name: port - remote_user: - description: - - User name with which to login to the remote server, normally set by the remote_user keyword. - - If no user is supplied, Ansible will let the SSH client binary choose the user as it normally. - type: string - ini: - - section: defaults - key: remote_user - env: - - name: ANSIBLE_REMOTE_USER - vars: - - name: ansible_user - - name: ansible_ssh_user - cli: - - name: user - keyword: - - name: remote_user - pipelining: - env: - - name: ANSIBLE_PIPELINING - - name: ANSIBLE_SSH_PIPELINING - ini: - - section: defaults - key: pipelining - - section: connection - key: pipelining - - section: ssh_connection - key: pipelining - vars: - - name: ansible_pipelining - - name: ansible_ssh_pipelining - - private_key_file: - description: - - Path to private key file to use for authentication. - type: string - ini: - - section: defaults - key: private_key_file - env: - - name: ANSIBLE_PRIVATE_KEY_FILE - vars: - - name: ansible_private_key_file - - name: ansible_ssh_private_key_file - cli: - - name: private_key_file - option: '--private-key' - - control_path: - description: - - This is the location to save SSH's ControlPath sockets, it uses SSH's variable substitution. - - Since 2.3, if null (default), ansible will generate a unique hash. Use ``%(directory)s`` to indicate where to use the control dir path setting. - - Before 2.3 it defaulted to ``control_path=%(directory)s/ansible-ssh-%%h-%%p-%%r``. - - Be aware that this setting is ignored if C(-o ControlPath) is set in ssh args. - type: string - env: - - name: ANSIBLE_SSH_CONTROL_PATH - ini: - - key: control_path - section: ssh_connection - vars: - - name: ansible_control_path - version_added: '2.7' - control_path_dir: - default: ~/.ansible/cp - description: - - This sets the directory to use for ssh control path if the control path setting is null. - - Also, provides the ``%(directory)s`` variable for the control path setting. - type: string - env: - - name: ANSIBLE_SSH_CONTROL_PATH_DIR - ini: - - section: ssh_connection - key: control_path_dir - vars: - - name: ansible_control_path_dir - version_added: '2.7' - sftp_batch_mode: - default: true - description: 'TODO: write it' - env: [{name: ANSIBLE_SFTP_BATCH_MODE}] - ini: - - {key: sftp_batch_mode, section: ssh_connection} - type: bool - vars: - - name: ansible_sftp_batch_mode - version_added: '2.7' - ssh_transfer_method: - description: Preferred method to use when transferring files over ssh - choices: - sftp: This is the most reliable way to copy things with SSH. - scp: Deprecated in OpenSSH. For OpenSSH >=9.0 you must add an additional option to enable scp C(scp_extra_args="-O"). - piped: Creates an SSH pipe with C(dd) on either side to copy the data. - smart: Tries each method in order (sftp > scp > piped), until one succeeds or they all fail. - default: smart - type: string - env: [{name: ANSIBLE_SSH_TRANSFER_METHOD}] - ini: - - {key: transfer_method, section: ssh_connection} - vars: - - name: ansible_ssh_transfer_method - version_added: '2.12' - use_tty: - version_added: '2.5' - default: true - description: add -tt to ssh commands to force tty allocation. - env: [{name: ANSIBLE_SSH_USETTY}] - ini: - - {key: usetty, section: ssh_connection} - type: bool - vars: - - name: ansible_ssh_use_tty - version_added: '2.7' - timeout: - default: 10 - description: - - This is the default amount of time we will wait while establishing an SSH connection. - - It also controls how long we can wait to access reading the connection once established (select on the socket). - env: - - name: ANSIBLE_TIMEOUT - - name: ANSIBLE_SSH_TIMEOUT - version_added: '2.11' - ini: - - key: timeout - section: defaults - - key: timeout - section: ssh_connection - version_added: '2.11' - vars: - - name: ansible_ssh_timeout - version_added: '2.11' - cli: - - name: timeout - type: integer - pkcs11_provider: - version_added: '2.12' - default: "" - type: string - description: - - "PKCS11 SmartCard provider such as opensc, example: /usr/local/lib/opensc-pkcs11.so" - - Requires sshpass version 1.06+, sshpass must support the -P option. - env: [{name: ANSIBLE_PKCS11_PROVIDER}] - ini: - - {key: pkcs11_provider, section: ssh_connection} - vars: - - name: ansible_ssh_pkcs11_provider ''' import importlib diff --git a/plugins/doc_fragments/builtin_ssh_fragment.py b/plugins/doc_fragments/builtin_ssh_fragment.py new file mode 100644 index 00000000..2cd75ea7 --- /dev/null +++ b/plugins/doc_fragments/builtin_ssh_fragment.py @@ -0,0 +1,12 @@ +import importlib +import yaml +SSH = importlib.import_module('ansible.plugins.connection.ssh') + +# Extract the options key from the builtin ansible ssh plugin +# DOCUMENTATION variable, and construct a documentation fragment +# that can be re-used in other modules derived from the builtin +# ssh plugin. +class ModuleDocFragment(object): + DOCUMENTATION = yaml.dump({ + "options": yaml.safe_load(SSH.DOCUMENTATION)["options"] + })