unify docstring formatting

plugins/inventory/proxmox.py

@@ -9,6 +9,7 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = """
+---
 name: proxmox
 plugin_type: inventory
 short_description: Proxmox VE inventory source
@@ -23,28 +24,34 @@ DOCUMENTATION = """
     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
+  api_host:
+    description:
+      - 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: Skip SSL certificate verification.
-        type: boolean
+    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.
@@ -68,14 +75,15 @@ DOCUMENTATION = """
     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):

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=<GatewayIPv4>] [,gw6=<GatewayIPv6>] [,ip=<IPv4Format/CIDR>] [,ip6=<IPv6Format/CIDR>]").
-      - '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]