From 37ca6e39914c134224d7c612152ef3a751cf242f Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Mon, 30 Jan 2023 21:03:11 +0100 Subject: [PATCH] unify docstring formatting --- plugins/inventory/proxmox.py | 145 +++++++++++++----------- plugins/modules/openssl_pkcs12.py | 176 +++++++++++++++--------------- plugins/modules/proxmox_kvm.py | 136 +++++++++++++++-------- plugins/modules/ucr.py | 56 +++++----- 4 files changed, 288 insertions(+), 225 deletions(-) diff --git a/plugins/inventory/proxmox.py b/plugins/inventory/proxmox.py index f1e5d05..c813300 100644 --- a/plugins/inventory/proxmox.py +++ b/plugins/inventory/proxmox.py @@ -9,73 +9,81 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type DOCUMENTATION = """ - name: proxmox - plugin_type: inventory - short_description: Proxmox VE inventory source - version_added: 1.1.0 +--- +name: proxmox +plugin_type: inventory +short_description: Proxmox VE inventory source +version_added: 1.1.0 +description: + - Get inventory hosts from the proxmox service. + - "Uses a configuration file as an inventory source, it must end in C(.proxmox.yml) or C(.proxmox.yaml) and has a C(plugin: xoxys.general.proxmox) entry." +extends_documentation_fragment: + - inventory_cache +options: + plugin: + description: The name of this plugin, it should always be set to C(xoxys.general.proxmox) for this plugin to recognize it as it's own. + required: yes + choices: ["xoxys.general.proxmox"] + api_host: description: - - Get inventory hosts from the proxmox service. - - "Uses a configuration file as an inventory source, it must end in C(.proxmox.yml) or C(.proxmox.yaml) and has a C(plugin: xoxys.general.proxmox) entry." - extends_documentation_fragment: - - inventory_cache - options: - plugin: - description: The name of this plugin, it should always be set to C(xoxys.general.proxmox) for this plugin to recognize it as it's own. - required: yes - choices: ["xoxys.general.proxmox"] - server: - description: Proxmox VE server url. - default: "pve.example.com" - type: string - required: yes - env: - - name: PROXMOX_SERVER - user: - description: Proxmox VE authentication user. - type: string - required: yes - env: - - name: PROXMOX_USER - password: - description: Proxmox VE authentication password. - type: string - required: yes - env: - - name: PROXMOX_PASSWORD - verify_ssl: - description: Skip SSL certificate verification. - type: boolean - default: True - auth_timeout: - description: Proxmox VE authentication timeout. - type: int - default: 5 - exclude_vmid: - description: VMID's to exclude from inventory. - type: list - default: [] - elements: str - exclude_state: - description: VM states to exclude from inventory. - type: list - default: [] - elements: str - group: - description: Group to place all hosts into. - type: string - default: proxmox - want_facts: - description: Toggle, if C(true) the plugin will retrieve host facts from the server - type: boolean - default: True + - Specify the target host of the Proxmox VE cluster. + type: str + required: true + api_user: + description: + - Specify the user to authenticate with. + type: str + required: true + api_password: + description: + - Specify the password to authenticate with. + - You can use C(PROXMOX_PASSWORD) environment variable. + type: str + api_token_id: + description: + - Specify the token ID. + type: str + api_token_secret: + description: + - Specify the token secret. + type: str + verify_ssl: + description: + - If C(false), SSL certificates will not be validated. + - This should only be used on personally controlled sites using self-signed certificates. + type: bool + default: True + auth_timeout: + description: Proxmox VE authentication timeout. + type: int + default: 5 + exclude_vmid: + description: VMID's to exclude from inventory. + type: list + default: [] + elements: str + exclude_state: + description: VM states to exclude from inventory. + type: list + default: [] + elements: str + group: + description: Group to place all hosts into. + type: string + default: proxmox + want_facts: + description: Toggle, if C(true) the plugin will retrieve host facts from the server + type: boolean + default: True + """ # noqa EXAMPLES = """ # proxmox.yml plugin: xoxys.general.proxmox -server: pve.example.com -user: admin@pve -password: secure +api_user: root@pam +api_password: secret +api_host: helldorado """ import json @@ -113,17 +121,22 @@ class InventoryModule(BaseInventoryPlugin): NAME = "xoxys.general.proxmox" def _auth(self): - verify_ssl = boolean(self.get_option("verify_ssl"), strict=False) + auth_args = {"user": self.get_option("api_user")} + if not (self.get_option("api_token_id") and self.get_option("api_token_secret")): + auth_args["password"] = self.get_option("api_password") + else: + auth_args["token_name"] = self.get_option("api_token_id") + auth_args["token_value"] = self.get_option("api_token_secret") + verify_ssl = boolean(self.get_option("verify_ssl"), strict=False) if not verify_ssl and HAS_URLLIB3: urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning) return ProxmoxAPI( - self.get_option("server"), - user=self.get_option("user"), - password=self.get_option("password"), + self.get_option("api_host"), verify_ssl=verify_ssl, - timeout=self.get_option("auth_timeout") + timeout=self.get_option("auth_timeout"), + **auth_args ) def _get_version(self): diff --git a/plugins/modules/openssl_pkcs12.py b/plugins/modules/openssl_pkcs12.py index bda9105..7ee2b4e 100644 --- a/plugins/modules/openssl_pkcs12.py +++ b/plugins/modules/openssl_pkcs12.py @@ -17,93 +17,93 @@ author: "Guillaume Delpierre (@gdelpierre)" version_added: 1.1.0 short_description: Generate OpenSSL pkcs12 archive. description: - - "This module allows one to (re-)generate PKCS#12." + - "This module allows one to (re-)generate PKCS#12." requirements: - - "python-pyOpenSSL" + - "python-pyOpenSSL" extends_documentation_fragment: files options: - ca_certificates: - required: False - type: list - elements: str - description: - - List of CA certificate to include. - cert_path: - required: False - type: path - description: - - The path to read certificates and private keys from. - Must be in PEM format. - action: - required: False - default: "export" - choices: ["parse", "export"] - type: str - description: - - Create (export) or parse a PKCS#12. - src: - required: False - type: path - description: - - PKCS#12 file path to parse. - path: - required: True - type: path - description: - - Filename to write the PKCS#12 file to. - force: - required: False - default: False - type: bool - description: - - Should the file be regenerated even it it already exists. - friendly_name: - required: False - type: str - aliases: - - "name" - description: - - Specifies the friendly name for the certificate and private key. - iter_size: - required: False - default: 2048 - type: int - description: - - Number of times to repeat the encryption step. - maciter_size: - required: False - default: 1 - type: int - description: - - Number of times to repeat the MAC step. - mode: - required: False - default: "0400" - type: str - description: - - Default mode for the generated PKCS#12 file. - passphrase: - required: False - type: str - description: - - The PKCS#12 password. - privatekey_path: - required: False - type: path - description: - - File to read private key from. - privatekey_passphrase: - required: False - type: str - description: - - Passphrase source to decrypt any input private keys with. - state: - required: False - default: "present" - choices: ["present", "absent"] - type: str - description: - - Whether the file should exist or not. + ca_certificates: + required: False + type: list + elements: str + description: + - List of CA certificate to include. + cert_path: + required: False + type: path + description: + - The path to read certificates and private keys from. + Must be in PEM format. + action: + required: False + default: "export" + choices: ["parse", "export"] + type: str + description: + - Create (export) or parse a PKCS#12. + src: + required: False + type: path + description: + - PKCS#12 file path to parse. + path: + required: True + type: path + description: + - Filename to write the PKCS#12 file to. + force: + required: False + default: False + type: bool + description: + - Should the file be regenerated even it it already exists. + friendly_name: + required: False + type: str + aliases: + - "name" + description: + - Specifies the friendly name for the certificate and private key. + iter_size: + required: False + default: 2048 + type: int + description: + - Number of times to repeat the encryption step. + maciter_size: + required: False + default: 1 + type: int + description: + - Number of times to repeat the MAC step. + mode: + required: False + default: "0400" + type: str + description: + - Default mode for the generated PKCS#12 file. + passphrase: + required: False + type: str + description: + - The PKCS#12 password. + privatekey_path: + required: False + type: path + description: + - File to read private key from. + privatekey_passphrase: + required: False + type: str + description: + - Passphrase source to decrypt any input private keys with. + state: + required: False + default: "present" + choices: ["present", "absent"] + type: str + description: + - Whether the file should exist or not. """ EXAMPLES = """ @@ -151,10 +151,10 @@ EXAMPLES = """ RETURN = """ filename: - description: Path to the generate PKCS#12 file. - returned: changed or success - type: str - sample: /opt/certs/ansible.p12 + description: Path to the generate PKCS#12 file. + returned: changed or success + type: str + sample: /opt/certs/ansible.p12 """ import errno diff --git a/plugins/modules/proxmox_kvm.py b/plugins/modules/proxmox_kvm.py index da86e2e..75998cc 100644 --- a/plugins/modules/proxmox_kvm.py +++ b/plugins/modules/proxmox_kvm.py @@ -58,7 +58,7 @@ options: - Specify the token secret. type: str version_added: 1.3.0 - validate_certs: + verify_ssl: description: - If C(false), SSL certificates will not be validated. - This should only be used on personally controlled sites using self-signed certificates. @@ -98,7 +98,7 @@ options: description: - Specify the BIOS implementation. type: str - choices: ['seabios', 'ovmf'] + choices: ["seabios", "ovmf"] boot: description: - Specify the boot order -> boot on floppy C(a), hard disk C(c), CD-ROM C(d), or network C(n). @@ -112,22 +112,22 @@ options: type: str cicustom: description: - - 'cloud-init: Specify custom files to replace the automatically generated ones at start.' + - "cloud-init: Specify custom files to replace the automatically generated ones at start." type: str cipassword: description: - - 'cloud-init: password of default user to create.' + - "cloud-init: password of default user to create." type: str citype: description: - - 'cloud-init: Specifies the cloud-init configuration format.' + - "cloud-init: Specifies the cloud-init configuration format." - The default depends on the configured operating system type (C(ostype)). - We use the C(nocloud) format for Linux, and C(configdrive2) for Windows. type: str - choices: ['nocloud', 'configdrive2'] + choices: ["nocloud", "configdrive2"] ciuser: description: - - 'cloud-init: username of default user to create.' + - "cloud-init: username of default user to create." type: str clone: description: @@ -187,7 +187,8 @@ options: option has a default of C(qcow2). If I(proxmox_default_behavior) is set to C(no_defaults), not specifying this option is equivalent to setting it to C(unspecified). type: str - choices: [ "cloop", "cow", "qcow", "qcow2", "qed", "raw", "vmdk", "unspecified" ] + choices: + ["cloop", "cow", "qcow", "qcow2", "qed", "raw", "vmdk", "unspecified"] freeze: description: - Specify if PVE should freeze CPU at startup (use 'c' monitor command to start execution). @@ -198,7 +199,7 @@ options: - For VM templates, we try to create a linked clone by default. - Used only with clone type: bool - default: 'yes' + default: "yes" hostpci: description: - Specify a hash/dictionary of map host pci devices into guest. C(hostpci='{"key":"value", "key":"value"}'). @@ -220,7 +221,7 @@ options: description: - Enable/disable hugepages memory. type: str - choices: ['any', '2', '1024'] + choices: ["any", "2", "1024"] ide: description: - A hash/dictionary of volume used as IDE hard disk or CD-ROM. C(ide='{"key":"value", "key":"value"}'). @@ -232,11 +233,11 @@ options: type: dict ipconfig: description: - - 'cloud-init: Set the IP configuration.' + - "cloud-init: Set the IP configuration." - A hash/dictionary of network ip configurations. C(ipconfig='{"key":"value", "key":"value"}'). - Keys allowed are - C(ipconfig[n]) where 0 ≤ n ≤ network interfaces. - Values allowed are - C("[gw=] [,gw6=] [,ip=] [,ip6=]"). - - 'cloud-init: Specify IP addresses and gateways for the corresponding interface.' + - "cloud-init: Specify IP addresses and gateways for the corresponding interface." - IP addresses use CIDR notation, gateways are optional but they should be in the same subnet of specified IP address. - The special string 'dhcp' can be used for IP addresses to use DHCP, in which case no explicit gateway should be provided. - For IPv6 the special string 'auto' can be used to use stateless autoconfiguration. @@ -261,7 +262,7 @@ options: description: - Lock/unlock the VM. type: str - choices: ['migrate', 'backup', 'snapshot', 'rollback'] + choices: ["migrate", "backup", "snapshot", "rollback"] machine: description: - Specifies the Qemu machine type. @@ -289,7 +290,7 @@ options: type: str nameservers: description: - - 'cloud-init: DNS server IP address(es).' + - "cloud-init: DNS server IP address(es)." - If unset, PVE host settings are used. type: list elements: str @@ -336,7 +337,21 @@ options: - If I(proxmox_default_behavior) is set to C(compatiblity) (the default value), this option has a default of C(l26). type: str - choices: ['other', 'wxp', 'w2k', 'w2k3', 'w2k8', 'wvista', 'win7', 'win8', 'win10', 'l24', 'l26', 'solaris'] + choices: + [ + "other", + "wxp", + "w2k", + "w2k3", + "w2k8", + "wvista", + "win7", + "win8", + "win10", + "l24", + "l26", + "solaris", + ] parallel: description: - A hash/dictionary of map host parallel devices. C(parallel='{"key":"value", "key":"value"}'). @@ -377,10 +392,18 @@ options: description: - Specifies the SCSI controller model. type: str - choices: ['lsi', 'lsi53c810', 'virtio-scsi-pci', 'virtio-scsi-single', 'megasas', 'pvscsi'] + choices: + [ + "lsi", + "lsi53c810", + "virtio-scsi-pci", + "virtio-scsi-single", + "megasas", + "pvscsi", + ] searchdomains: description: - - 'cloud-init: Sets DNS search domain(s).' + - "cloud-init: Sets DNS search domain(s)." - If unset, PVE host settings are used. type: list elements: str @@ -419,7 +442,7 @@ options: type: int sshkeys: description: - - 'cloud-init: SSH key to assign to the default user. NOT TESTED with multiple keys but a multi-line value should work.' + - "cloud-init: SSH key to assign to the default user. NOT TESTED with multiple keys but a multi-line value should work." type: str startdate: description: @@ -437,7 +460,7 @@ options: - Indicates desired state of the instance. - If C(current), the current state of the VM will be fetched. You can access it with C(results.status) type: str - choices: ['present', 'started', 'absent', 'stopped', 'restarted','current'] + choices: ["present", "started", "absent", "stopped", "restarted", "current"] default: present storage: description: @@ -481,7 +504,7 @@ options: - If C(yes), the VM will be updated with new value. - Update of C(pool) is disabled. It needs an additional API endpoint not covered by this module. type: bool - default: 'no' + default: "no" vcpus: description: - Sets number of hotplugged vcpus. @@ -492,7 +515,20 @@ options: - If I(proxmox_default_behavior) is set to C(compatiblity) (the default value), this option has a default of C(std). type: str - choices: ['std', 'cirrus', 'vmware', 'qxl', 'serial0', 'serial1', 'serial2', 'serial3', 'qxl2', 'qxl3', 'qxl4'] + choices: + [ + "std", + "cirrus", + "vmware", + "qxl", + "serial0", + "serial1", + "serial2", + "serial3", + "qxl2", + "qxl3", + "qxl4", + ] virtio: description: - A hash/dictionary of volume used as VIRTIO hard disk. C(virtio='{"key":"value", "key":"value"}'). @@ -545,8 +581,8 @@ EXAMPLES = """ name: spynal node: sabrewulf net: - net0: 'virtio,bridge=vmbr1,rate=200' - net1: 'e1000,bridge=vmbr2' + net0: "virtio,bridge=vmbr1,rate=200" + net1: "e1000,bridge=vmbr2" - name: Create new VM with one network interface, three virto hard disk, 4 cores, and 2 vcpus xoxys.general.proxmox_kvm: @@ -556,11 +592,11 @@ EXAMPLES = """ name: spynal node: sabrewulf net: - net0: 'virtio,bridge=vmbr1,rate=200' + net0: "virtio,bridge=vmbr1,rate=200" virtio: - virtio0: 'VMs_LVM:10' - virtio1: 'VMs:2,format=qcow2' - virtio2: 'VMs:5,format=raw' + virtio0: "VMs_LVM:10" + virtio1: "VMs:2,format=qcow2" + virtio2: "VMs:5,format=raw" cores: 4 vcpus: 2 @@ -635,15 +671,15 @@ EXAMPLES = """ api_host: helldorado name: spynal ide: - ide2: 'local:cloudinit,format=qcow2' + ide2: "local:cloudinit,format=qcow2" ciuser: mylinuxuser cipassword: supersecret - searchdomains: 'mydomain.internal' + searchdomains: "mydomain.internal" nameservers: 1.1.1.1 net: - net0: 'virtio,bridge=vmbr1,tag=77' + net0: "virtio,bridge=vmbr1,tag=77" ipconfig: - ipconfig0: 'ip=192.168.1.1/24,gw=192.168.1.1' + ipconfig0: "ip=192.168.1.1/24,gw=192.168.1.1" - name: Create new VM using Cloud-Init with an ssh key xoxys.general.proxmox_kvm: @@ -653,16 +689,16 @@ EXAMPLES = """ api_host: helldorado name: spynal ide: - ide2: 'local:cloudinit,format=qcow2' - sshkeys: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILJkVm98B71lD5XHfihwcYHE9TVpsJmK1vR1JcaU82L+' - searchdomains: 'mydomain.internal' + ide2: "local:cloudinit,format=qcow2" + sshkeys: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILJkVm98B71lD5XHfihwcYHE9TVpsJmK1vR1JcaU82L+" + searchdomains: "mydomain.internal" nameservers: - - '1.1.1.1' - - '8.8.8.8' + - "1.1.1.1" + - "8.8.8.8" net: - net0: 'virtio,bridge=vmbr1,tag=77' + net0: "virtio,bridge=vmbr1,tag=77" ipconfig: - ipconfig0: 'ip=192.168.1.1/24' + ipconfig0: "ip=192.168.1.1/24" - name: Start VM xoxys.general.proxmox_kvm: @@ -737,7 +773,7 @@ EXAMPLES = """ api_host: helldorado name: spynal node: sabrewulf - delete: 'args,template,cpulimit' + delete: "args,template,cpulimit" - name: Revert a pending change xoxys.general.proxmox_kvm: @@ -746,7 +782,8 @@ EXAMPLES = """ api_host: helldorado name: spynal node: sabrewulf - revert: 'template,cpulimit' + revert: "template,cpulimit" + """ RETURN = """ @@ -782,6 +819,16 @@ try: except ImportError: HAS_PROXMOXER = False +try: + from requests.packages import urllib3 + HAS_URLLIB3 = True +except ImportError: + try: + import urllib3 + HAS_URLLIB3 = True + except ImportError: + HAS_URLLIB3 = False + from ansible.module_utils._text import to_native from ansible.module_utils.basic import AnsibleModule, env_fallback @@ -1120,7 +1167,7 @@ def main(): template=dict(type="bool"), timeout=dict(type="int", default=30), update=dict(type="bool", default=False), - validate_certs=dict(type="bool", default=True), + verify_ssl=dict(type="bool", default=True), vcpus=dict(type="int"), vga=dict( choices=[ @@ -1161,7 +1208,7 @@ def main(): state = module.params["state"] update = bool(module.params["update"]) vmid = module.params["vmid"] - validate_certs = module.params["validate_certs"] + verify_ssl = module.params["verify_ssl"] if module.params["proxmox_default_behavior"] is None: module.params["proxmox_default_behavior"] = "compatibility" @@ -1197,8 +1244,11 @@ def main(): auth_args["token_name"] = api_token_id auth_args["token_value"] = api_token_secret + if not verify_ssl and HAS_URLLIB3: + urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning) + try: - proxmox = ProxmoxAPI(api_host, verify_ssl=validate_certs, **auth_args) + proxmox = ProxmoxAPI(api_host, verify_ssl=verify_ssl, **auth_args) global PVE_MAJOR_VERSION version = proxmox_version(proxmox) PVE_MAJOR_VERSION = 3 if version < LooseVersion("4.0") else version.version[0] diff --git a/plugins/modules/ucr.py b/plugins/modules/ucr.py index ba7ed86..5d5dfaf 100644 --- a/plugins/modules/ucr.py +++ b/plugins/modules/ucr.py @@ -16,30 +16,30 @@ module: ucr short_description: Manage variables in univention configuration registry. version_added: 1.1.0 description: - - "This module allows to manage variables inside the univention configuration registry - on a univention corporate server (UCS)." + - "This module allows to manage variables inside the univention configuration registry + on a univention corporate server (UCS)." options: - path: - description: - - Path for the variable - aliases: - - name - required: True - type: str - value: - description: - - New value of the variable - required: False - type: str - state: - required: False - default: "present" - choices: ["present", "absent"] - type: str - description: - - Whether the variable should be exist or not. + path: + description: + - Path for the variable + aliases: + - name + required: True + type: str + value: + description: + - New value of the variable + required: False + type: str + state: + required: False + default: "present" + choices: ["present", "absent"] + type: str + description: + - Whether the variable should be exist or not. author: - - Robert Kaussow (@xoxys) + - Robert Kaussow (@xoxys) """ EXAMPLES = """ @@ -58,13 +58,13 @@ EXAMPLES = """ RETURN = """ original_message: - description: The original name param that was passed in - type: str - returned: success + description: The original name param that was passed in + type: str + returned: success message: - description: The output message that the sample module generates - type: str - returned: success + description: The output message that the sample module generates + type: str + returned: success """ from ansible.module_utils.basic import AnsibleModule