From eff1f8851c795cb09f504f564587b892a502ad76 Mon Sep 17 00:00:00 2001 From: David Passante Date: Sun, 31 Mar 2019 11:09:15 +0200 Subject: [PATCH] cloudstack: streamline modules doc (part 6) (#54641) * Parameter types added * Copyright format fixes * Doc style fixes * Examples format fixes * validate-module errors fixes --- .../modules/cloud/cloudstack/cs_user.py | 43 ++++++----- .../cloud/cloudstack/cs_vlan_ip_range.py | 31 ++++++-- .../modules/cloud/cloudstack/cs_vmsnapshot.py | 58 +++++++------- .../cloud/cloudstack/cs_vpn_connection.py | 31 +++++--- .../cloudstack/cs_vpn_customer_gateway.py | 36 ++++++--- .../cloud/cloudstack/cs_vpn_gateway.py | 44 +++++------ .../modules/cloud/cloudstack/cs_zone.py | 76 ++++++++++--------- .../modules/cloud/cloudstack/cs_zone_facts.py | 9 ++- test/sanity/validate-modules/ignore.txt | 2 - 9 files changed, 185 insertions(+), 145 deletions(-) diff --git a/lib/ansible/modules/cloud/cloudstack/cs_user.py b/lib/ansible/modules/cloud/cloudstack/cs_user.py index 9081eb0a3e..1b50f203ea 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_user.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_user.py @@ -17,51 +17,60 @@ short_description: Manages users on Apache CloudStack based clouds. description: - Create, update, disable, lock, enable and remove users. version_added: '2.0' -author: "René Moser (@resmo)" +author: René Moser (@resmo) options: username: description: - Username of the user. + type: str required: true account: description: - Account the user will be created under. - - Required on C(state=present). + - Required on I(state=present). + type: str password: description: - Password of the user to be created. - - Required on C(state=present). + - Required on I(state=present). - Only considered on creation and will not be updated if user exists. + type: str first_name: description: - First name of the user. - - Required on C(state=present). + - Required on I(state=present). + type: str last_name: description: - Last name of the user. - - Required on C(state=present). + - Required on I(state=present). + type: str email: description: - Email of the user. - - Required on C(state=present). + - Required on I(state=present). + type: str timezone: description: - Timezone of the user. + type: str keys_registered: description: - If API keys of the user should be generated. - "Note: Keys can not be removed by the API again." - version_added: "2.4" + version_added: '2.4' type: bool default: no domain: description: - Domain the user is related to. + type: str default: ROOT state: description: - State of the user. - C(unlocked) is an alias for C(enabled). + type: str default: present choices: [ present, absent, enabled, disabled, locked, unlocked ] poll_async: @@ -74,8 +83,7 @@ extends_documentation_fragment: cloudstack EXAMPLES = ''' - name: Create an user in domain 'CUSTOMERS' - local_action: - module: cs_user + cs_user: account: developers username: johndoe password: S3Cur3 @@ -83,34 +91,35 @@ EXAMPLES = ''' first_name: John email: john.doe@example.com domain: CUSTOMERS + delegate_to: localhost - name: Lock an existing user in domain 'CUSTOMERS' - local_action: - module: cs_user + cs_user: username: johndoe domain: CUSTOMERS state: locked + delegate_to: localhost - name: Disable an existing user in domain 'CUSTOMERS' - local_action: - module: cs_user + cs_user: username: johndoe domain: CUSTOMERS state: disabled + delegate_to: localhost - name: Enable/unlock an existing user in domain 'CUSTOMERS' - local_action: - module: cs_user + cs_user: username: johndoe domain: CUSTOMERS state: enabled + delegate_to: localhost - name: Remove an user in domain 'CUSTOMERS' - local_action: - module: cs_user + cs_user: name: customer_xy domain: CUSTOMERS state: absent + delegate_to: localhost ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/cloudstack/cs_vlan_ip_range.py b/lib/ansible/modules/cloud/cloudstack/cs_vlan_ip_range.py index 4d3983205b..441a5e2f8c 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_vlan_ip_range.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_vlan_ip_range.py @@ -17,12 +17,13 @@ short_description: Manages VLAN IP ranges on Apache CloudStack based clouds. description: - Create and delete VLAN IP range. version_added: '2.8' -author: "David Passante (@dpassante)" +author: David Passante (@dpassante) options: network: description: - The network name or id. - Required if I(for_virtual_network) and I(physical_network) are not set. + type: str physical_network: description: - The physical network name or id. @@ -31,74 +32,87 @@ options: description: - The beginning IPv4 address in the VLAN IP range. - Only considered on create. + type: str required: true end_ip: description: - The ending IPv4 address in the VLAN IP range. - If not specified, value of I(start_ip) is used. - Only considered on create. + type: str gateway: description: - The gateway of the VLAN IP range. - Required if I(state=present). + type: str netmask: description: - The netmask of the VLAN IP range. - Required if I(state=present). + type: str start_ipv6: description: - The beginning IPv6 address in the IPv6 network range. - Only considered on create. + type: str end_ipv6: description: - The ending IPv6 address in the IPv6 network range. - If not specified, value of I(start_ipv6) is used. - Only considered on create. + type: str gateway_ipv6: description: - The gateway of the IPv6 network. - Only considered on create. + type: str cidr_ipv6: description: - The CIDR of IPv6 network, must be at least /64. + type: str vlan: description: - The ID or VID of the network. - If not specified, will be defaulted to the vlan of the network. + type: str state: description: - State of the network ip range. + type: str default: present choices: [ present, absent ] zone: description: - The Zone ID of the VLAN IP range. - If not set, default zone is used. + type: str domain: description: - Domain of the account owning the VLAN. + type: str account: description: - Account who owns the VLAN. - Mutually exclusive with I(project). + type: str project: description: - Project who owns the VLAN. - Mutually exclusive with I(account). + type: str for_virtual_network: description: - - true if VLAN is of Virtual type, false if Direct. - - If set to C(true) but neither I(physical_network) or I(network) is set CloudStack will try to add the + - C(yes) if VLAN is of Virtual type, C(no) if Direct. + - If set to C(yes) but neither I(physical_network) or I(network) is set CloudStack will try to add the VLAN range to the Physical Network with a Public traffic type. type: bool - default: false + default: no extends_documentation_fragment: cloudstack ''' EXAMPLES = ''' - name: create a VLAN IP range for network test - local_action: - module: cs_vlan_ip_range + cs_vlan_ip_range: network: test vlan: 98 start_ip: 10.2.4.10 @@ -106,15 +120,16 @@ EXAMPLES = ''' gateway: 10.2.4.1 netmask: 255.255.255.0 zone: zone-02 + delegate_to: localhost - name: remove a VLAN IP range for network test - local_action: - module: cs_vlan_ip_range + cs_vlan_ip_range: state: absent network: test start_ip: 10.2.4.10 end_ip: 10.2.4.100 zone: zone-02 + delegate_to: localhost ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/cloudstack/cs_vmsnapshot.py b/lib/ansible/modules/cloud/cloudstack/cs_vmsnapshot.py index a14235eab5..6badf3811b 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_vmsnapshot.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_vmsnapshot.py @@ -2,21 +2,7 @@ # -*- coding: utf-8 -*- # # (c) 2015, René Moser -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see . +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['stableinterface'], @@ -30,78 +16,86 @@ short_description: Manages VM snapshots on Apache CloudStack based clouds. description: - Create, remove and revert VM from snapshots. version_added: '2.0' -author: "René Moser (@resmo)" +author: René Moser (@resmo) options: name: description: - Unique Name of the snapshot. In CloudStack terms display name. + type: str required: true - aliases: ['display_name'] + aliases: [ display_name ] vm: description: - Name of the virtual machine. + type: str required: true description: description: - Description of the snapshot. + type: str snapshot_memory: description: - Snapshot memory if set to true. - default: false + default: no type: bool zone: description: - Name of the zone in which the VM is in. If not set, default zone is used. + type: str project: description: - Name of the project the VM is assigned to. + type: str state: description: - State of the snapshot. - default: 'present' - choices: [ 'present', 'absent', 'revert' ] + type: str + default: present + choices: [ present, absent, revert ] domain: description: - Domain the VM snapshot is related to. + type: str account: description: - Account the VM snapshot is related to. + type: str poll_async: description: - Poll async jobs until job has finished. - required: false - default: true + default: yes type: bool tags: description: - - List of tags. Tags are a list of dictionaries having keys C(key) and C(value). - - "To delete all tags, set a empty list e.g. C(tags: [])." - aliases: [ 'tag' ] - version_added: "2.4" + - List of tags. Tags are a list of dictionaries having keys I(key) and I(value). + - "To delete all tags, set a empty list e.g. I(tags: [])." + type: list + aliases: [ tag ] + version_added: '2.4' extends_documentation_fragment: cloudstack ''' EXAMPLES = ''' - name: Create a VM snapshot of disk and memory before an upgrade - local_action: - module: cs_vmsnapshot + cs_vmsnapshot: name: Snapshot before upgrade vm: web-01 snapshot_memory: yes + delegate_to: localhost - name: Revert a VM to a snapshot after a failed upgrade - local_action: - module: cs_vmsnapshot + cs_vmsnapshot: name: Snapshot before upgrade vm: web-01 state: revert + delegate_to: localhost - name: Remove a VM snapshot after successful upgrade - local_action: - module: cs_vmsnapshot + cs_vmsnapshot: name: Snapshot before upgrade vm: web-01 state: absent + delegate_to: localhost ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/cloudstack/cs_vpn_connection.py b/lib/ansible/modules/cloud/cloudstack/cs_vpn_connection.py index a145749485..62eb8a78ea 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_vpn_connection.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_vpn_connection.py @@ -18,43 +18,54 @@ module: cs_vpn_connection short_description: Manages site-to-site VPN connections on Apache CloudStack based clouds. description: - Create and remove VPN connections. -version_added: "2.5" -author: "René Moser (@resmo)" +version_added: '2.5' +author: René Moser (@resmo) options: vpc: description: - Name of the VPC the VPN connection is related to. + type: str required: true vpn_customer_gateway: description: - Name of the VPN customer gateway. + type: str required: true passive: description: - State of the VPN connection. - - Only considered when C(state=present). + - Only considered when I(state=present). default: no type: bool force: description: - - Activate the VPN gateway if not already activated on C(state=present). + - Activate the VPN gateway if not already activated on I(state=present). - Also see M(cs_vpn_gateway). default: no type: bool state: description: - State of the VPN connection. + type: str default: present choices: [ present, absent ] + zone: + description: + - Name of the zone the VPC is related to. + - If not set, default zone is used. + type: str domain: description: - Domain the VPN connection is related to. + type: str account: description: - Account the VPN connection is related to. + type: str project: description: - Name of the project the VPN connection is related to. + type: str poll_async: description: - Poll async jobs until job has finished. @@ -65,24 +76,24 @@ extends_documentation_fragment: cloudstack EXAMPLES = r''' - name: Create a VPN connection with activated VPN gateway - local_action: - module: cs_vpn_connection + cs_vpn_connection: vpn_customer_gateway: my vpn connection vpc: my vpc + delegate_to: localhost - name: Create a VPN connection and force VPN gateway activation - local_action: - module: cs_vpn_connection + cs_vpn_connection: vpn_customer_gateway: my vpn connection vpc: my vpc force: yes + delegate_to: localhost - name: Remove a vpn connection - local_action: - module: cs_vpn_connection + cs_vpn_connection: vpn_customer_gateway: my vpn connection vpc: my vpc state: absent + delegate_to: localhost ''' RETURN = r''' diff --git a/lib/ansible/modules/cloud/cloudstack/cs_vpn_customer_gateway.py b/lib/ansible/modules/cloud/cloudstack/cs_vpn_customer_gateway.py index 871d7a40aa..7a43c198b6 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_vpn_customer_gateway.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_vpn_customer_gateway.py @@ -18,43 +18,51 @@ module: cs_vpn_customer_gateway short_description: Manages site-to-site VPN customer gateway configurations on Apache CloudStack based clouds. description: - Create, update and remove VPN customer gateways. -version_added: "2.5" -author: "René Moser (@resmo)" +version_added: '2.5' +author: René Moser (@resmo) options: name: description: - Name of the gateway. + type: str required: true cidrs: description: - List of guest CIDRs behind the gateway. - - Required if C(state=present). + - Required if I(state=present). + type: list aliases: [ cidr ] gateway: description: - Public IP address of the gateway. - - Required if C(state=present). + - Required if I(state=present). + type: str esp_policy: description: - ESP policy in the format e.g. C(aes256-sha1;modp1536). - - Required if C(state=present). + - Required if I(state=present). + type: str ike_policy: description: - IKE policy in the format e.g. C(aes256-sha1;modp1536). - - Required if C(state=present). + - Required if I(state=present). + type: str ipsec_psk: description: - IPsec Preshared-Key. - Cannot contain newline or double quotes. - - Required if C(state=present). + - Required if I(state=present). + type: str ike_lifetime: description: - Lifetime in seconds of phase 1 VPN connection. - Defaulted to 86400 by the API on creation if not set. + type: int esp_lifetime: description: - Lifetime in seconds of phase 2 VPN connection. - Defaulted to 3600 by the API on creation if not set. + type: int dpd: description: - Enable Dead Peer Detection. @@ -68,29 +76,32 @@ options: state: description: - State of the VPN customer gateway. + type: str default: present choices: [ present, absent ] domain: description: - Domain the VPN customer gateway is related to. + type: str account: description: - Account the VPN customer gateway is related to. + type: str project: description: - Name of the project the VPN gateway is related to. + type: str poll_async: description: - Poll async jobs until job has finished. - default: true + default: yes type: bool extends_documentation_fragment: cloudstack ''' EXAMPLES = r''' - name: Create a vpn customer gateway - local_action: - module: cs_vpn_customer_gateway + cs_vpn_customer_gateway: name: my vpn customer gateway cidrs: - 192.168.123.0/24 @@ -99,12 +110,13 @@ EXAMPLES = r''' gateway: 10.10.1.1 ike_policy: aes256-sha1;modp1536 ipsec_psk: "S3cr3Tk3Y" + delegate_to: localhost - name: Remove a vpn customer gateway - local_action: - module: cs_vpn_customer_gateway + cs_vpn_customer_gateway: name: my vpn customer gateway state: absent + delegate_to: localhost ''' RETURN = r''' diff --git a/lib/ansible/modules/cloud/cloudstack/cs_vpn_gateway.py b/lib/ansible/modules/cloud/cloudstack/cs_vpn_gateway.py index 97e093b355..3bfa3b75d1 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_vpn_gateway.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_vpn_gateway.py @@ -2,21 +2,7 @@ # -*- coding: utf-8 -*- # # (c) 2017, René Moser -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see . +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], @@ -29,50 +15,56 @@ module: cs_vpn_gateway short_description: Manages site-to-site VPN gateways on Apache CloudStack based clouds. description: - Creates and removes VPN site-to-site gateways. -version_added: "2.4" -author: "René Moser (@resmo)" +version_added: '2.4' +author: René Moser (@resmo) options: vpc: description: - Name of the VPC. + type: str required: true state: description: - State of the VPN gateway. - default: "present" - choices: [ 'present', 'absent' ] + type: str + default: present + choices: [ present, absent ] domain: description: - Domain the VPN gateway is related to. + type: str account: description: - Account the VPN gateway is related to. + type: str project: description: - Name of the project the VPN gateway is related to. + type: str zone: description: - Name of the zone the VPC is related to. - If not set, default zone is used. + type: str poll_async: description: - Poll async jobs until job has finished. type: bool - default: 'yes' + default: yes extends_documentation_fragment: cloudstack ''' EXAMPLES = ''' -# Ensure a vpn gateway is present -- local_action: - module: cs_vpn_gateway +- name: Ensure a vpn gateway is present + cs_vpn_gateway: vpc: my VPC + delegate_to: localhost -# Ensure a vpn gateway is absent -- local_action: - module: cs_vpn_gateway +- name: Ensure a vpn gateway is absent + cs_vpn_gateway: vpc: my VPC state: absent + delegate_to: localhost ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/cloudstack/cs_zone.py b/lib/ansible/modules/cloud/cloudstack/cs_zone.py index 969014660c..258dbfc8f9 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_zone.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_zone.py @@ -2,21 +2,7 @@ # -*- coding: utf-8 -*- # # (c) 2016, René Moser -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see . +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['stableinterface'], @@ -29,88 +15,110 @@ module: cs_zone short_description: Manages zones on Apache CloudStack based clouds. description: - Create, update and remove zones. -version_added: "2.1" -author: "René Moser (@resmo)" +version_added: '2.1' +author: René Moser (@resmo) options: name: description: - Name of the zone. + type: str required: true id: description: - uuid of the existing zone. + type: str state: description: - State of the zone. - default: 'present' - choices: [ 'present', 'enabled', 'disabled', 'absent' ] + type: str + default: present + choices: [ present, enabled, disabled, absent ] domain: description: - Domain the zone is related to. - Zone is a public zone if not set. + type: str network_domain: description: - Network domain for the zone. + type: str network_type: description: - Network type of the zone. + type: str default: basic - choices: [ 'basic', 'advanced' ] + choices: [ basic, advanced ] dns1: description: - First DNS for the zone. - - Required if C(state=present) + - Required if I(state=present) + type: str dns2: description: - Second DNS for the zone. + type: str internal_dns1: description: - First internal DNS for the zone. - - If not set C(dns1) will be used on C(state=present). + - If not set I(dns1) will be used on I(state=present). + type: str internal_dns2: description: - Second internal DNS for the zone. + type: str dns1_ipv6: description: - First DNS for IPv6 for the zone. + type: str dns2_ipv6: description: - Second DNS for IPv6 for the zone. + type: str guest_cidr_address: description: - Guest CIDR address for the zone. + type: str dhcp_provider: description: - DHCP provider for the Zone. + type: str + local_storage_enabled: + description: + - Whether to enable local storage for the zone or not.. + type: bool + securitygroups_enabled: + description: + - Whether the zone is security group enabled or not. + type: bool extends_documentation_fragment: cloudstack ''' EXAMPLES = ''' -# Ensure a zone is present -- local_action: - module: cs_zone +- name: Ensure a zone is present + cs_zone: name: ch-zrh-ix-01 dns1: 8.8.8.8 dns2: 8.8.4.4 network_type: basic + delegate_to: localhost -# Ensure a zone is disabled -- local_action: - module: cs_zone +- name: Ensure a zone is disabled + cs_zone: name: ch-zrh-ix-01 state: disabled + delegate_to: localhost -# Ensure a zone is enabled -- local_action: - module: cs_zone +- name: Ensure a zone is enabled + cs_zone: name: ch-zrh-ix-01 state: enabled + delegate_to: localhost -# Ensure a zone is absent -- local_action: - module: cs_zone +- name: Ensure a zone is absent + cs_zone: name: ch-zrh-ix-01 state: absent + delegate_to: localhost ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/cloudstack/cs_zone_facts.py b/lib/ansible/modules/cloud/cloudstack/cs_zone_facts.py index 77f13f0ce0..92c815e957 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_zone_facts.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_zone_facts.py @@ -16,12 +16,13 @@ short_description: Gathering facts of zones from Apache CloudStack based clouds. description: - Gathering facts from the API of a zone. - Sets Ansible facts accessable by the key C(cloudstack_zone) and since version 2.6 also returns results. -version_added: "2.1" -author: "René Moser (@resmo)" +version_added: '2.1' +author: René Moser (@resmo) options: name: description: - Name of the zone. + type: str required: true aliases: [ zone ] extends_documentation_fragment: cloudstack @@ -29,10 +30,10 @@ extends_documentation_fragment: cloudstack EXAMPLES = ''' - name: Gather facts from a zone - local_action: - module: cs_zone_facts + cs_zone_facts: name: ch-gva-1 register: zone + delegate_to: localhost - name: Show the returned results of the registered variable debug: diff --git a/test/sanity/validate-modules/ignore.txt b/test/sanity/validate-modules/ignore.txt index bdc8d772e9..78a52f05b3 100644 --- a/test/sanity/validate-modules/ignore.txt +++ b/test/sanity/validate-modules/ignore.txt @@ -97,8 +97,6 @@ lib/ansible/modules/cloud/centurylink/clc_server_snapshot.py E335 lib/ansible/modules/cloud/cloudstack/cs_cluster.py E326 lib/ansible/modules/cloud/cloudstack/cs_host.py E326 lib/ansible/modules/cloud/cloudstack/cs_storage_pool.py E326 -lib/ansible/modules/cloud/cloudstack/cs_vpn_connection.py E322 -lib/ansible/modules/cloud/cloudstack/cs_zone.py E322 lib/ansible/modules/cloud/cloudstack/cs_zone.py E326 lib/ansible/modules/cloud/digital_ocean/_digital_ocean.py E322 lib/ansible/modules/cloud/digital_ocean/digital_ocean_floating_ip.py E322