From 5abeb9659b1dfeb3ba44f9b70c9e9cc44dfb0e05 Mon Sep 17 00:00:00 2001 From: David Passante Date: Wed, 20 Feb 2019 16:53:31 +0100 Subject: [PATCH] cloudstack: streamline modules doc (#52509) * cloudstack: streamline modules doc (first 5) * Remove the "local_action" style from the examples --- .../modules/cloud/cloudstack/cs_account.py | 90 +++++++++---------- .../cloud/cloudstack/cs_affinitygroup.py | 43 ++++----- .../modules/cloud/cloudstack/cs_cluster.py | 79 ++++++++-------- .../cloud/cloudstack/cs_configuration.py | 53 +++++------ .../cloud/cloudstack/cs_disk_offering.py | 51 ++++++----- .../modules/cloud/cloudstack/cs_domain.py | 44 ++++----- 6 files changed, 173 insertions(+), 187 deletions(-) diff --git a/lib/ansible/modules/cloud/cloudstack/cs_account.py b/lib/ansible/modules/cloud/cloudstack/cs_account.py index 8dcf0ed06d..5e9632ba35 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_account.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_account.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,80 +16,93 @@ short_description: Manages accounts on Apache CloudStack based clouds. description: - Create, disable, lock, enable and remove accounts. version_added: '2.0' -author: "René Moser (@resmo)" +author: René Moser (@resmo) options: name: description: - Name of account. + type: str required: true username: description: - Username of the user to be created if account did not exist. - Required on I(state=present). + type: str password: description: - Password of the user to be created if account did not exist. - Required on I(state=present) if I(ldap_domain) is not set. + type: str first_name: description: - First name of the user to be created if account did not exist. - Required on I(state=present) if I(ldap_domain) is not set. + type: str last_name: description: - Last name of the user to be created if account did not exist. - Required on I(state=present) if I(ldap_domain) is not set. + type: str email: description: - Email of the user to be created if account did not exist. - Required on I(state=present) if I(ldap_domain) is not set. + type: str timezone: description: - Timezone of the user to be created if account did not exist. + type: str network_domain: description: - Network domain of the account. + type: str account_type: description: - Type of the account. - default: 'user' - choices: [ 'user', 'root_admin', 'domain_admin' ] + type: str + choices: [ user, root_admin, domain_admin ] + default: user domain: description: - Domain the account is related to. - default: 'ROOT' + type: str + default: ROOT role: description: - Creates the account under the specified role name or id. + type: str version_added: 2.8 ldap_domain: description: - Name of the LDAP group or OU to bind. - If set, account will be linked to LDAP. + type: str version_added: 2.8 ldap_type: description: - Type of the ldap name. GROUP or OU, defaults to GROUP. - default: 'GROUP' - choices: [ 'GROUP', 'OU' ] + type: str + choices: [ GROUP, OU ] + default: GROUP version_added: 2.8 state: description: - State of the account. - C(unlocked) is an alias for C(enabled). - default: 'present' - choices: [ 'present', 'absent', 'enabled', 'disabled', 'locked', 'unlocked' ] + type: str + choices: [ present, absent, enabled, disabled, locked, unlocked ] + default: present poll_async: description: - Poll async jobs until job has finished. type: bool - default: 'yes' + default: yes extends_documentation_fragment: cloudstack ''' EXAMPLES = ''' -# create an account in domain 'CUSTOMERS' -- local_action: - module: cs_account +- name: create an account in domain 'CUSTOMERS' + cs_account: name: customer_xy username: customer_xy password: S3Cur3 @@ -112,50 +111,51 @@ EXAMPLES = ''' email: john.doe@example.com domain: CUSTOMERS role: Domain Admin + delegate_to: localhost -# Lock an existing account in domain 'CUSTOMERS' -- local_action: - module: cs_account +- name: Lock an existing account in domain 'CUSTOMERS' + cs_account: name: customer_xy domain: CUSTOMERS state: locked + delegate_to: localhost -# Disable an existing account in domain 'CUSTOMERS' -- local_action: - module: cs_account +- name: Disable an existing account in domain 'CUSTOMERS' + cs_account: name: customer_xy domain: CUSTOMERS state: disabled + delegate_to: localhost -# Enable an existing account in domain 'CUSTOMERS' -- local_action: - module: cs_account +- name: Enable an existing account in domain 'CUSTOMERS' + cs_account: name: customer_xy domain: CUSTOMERS state: enabled + delegate_to: localhost -# Remove an account in domain 'CUSTOMERS' -- local_action: - module: cs_account +- name: Remove an account in domain 'CUSTOMERS' + cs_account: name: customer_xy domain: CUSTOMERS state: absent + delegate_to: localhost -# Create a single user LDAP account in domain 'CUSTOMERS' -- local_action: - module: cs_account +- name: Create a single user LDAP account in domain 'CUSTOMERS' + cs_account: name: customer_xy username: customer_xy domain: CUSTOMERS ldap_domain: cn=customer_xy,cn=team_xy,ou=People,dc=domain,dc=local + delegate_to: localhost -# Create a LDAP account in domain 'CUSTOMERS' and bind it to a LDAP group -- local_action: - module: cs_account +- name: Create a LDAP account in domain 'CUSTOMERS' and bind it to a LDAP group + cs_account: name: team_xy username: customer_xy domain: CUSTOMERS ldap_domain: cn=team_xy,ou=People,dc=domain,dc=local + delegate_to: localhost ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/cloudstack/cs_affinitygroup.py b/lib/ansible/modules/cloud/cloudstack/cs_affinitygroup.py index 75067e6572..d8d2c7e17f 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_affinitygroup.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_affinitygroup.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,53 +16,60 @@ short_description: Manages affinity groups on Apache CloudStack based clouds. description: - Create and remove affinity groups. version_added: '2.0' -author: "René Moser (@resmo)" +author: René Moser (@resmo) options: name: description: - Name of the affinity group. + type: str required: true affinity_type: description: - Type of the affinity group. If not specified, first found affinity type is used. + type: str aliases: [ affinty_type ] description: description: - Description of the affinity group. + type: str state: description: - State of the affinity group. - default: 'present' - choices: [ 'present', 'absent' ] + type: str + choices: [ present, absent ] + default: present domain: description: - Domain the affinity group is related to. + type: str account: description: - Account the affinity group is related to. + type: str project: description: - Name of the project the affinity group is related to. + type: str poll_async: description: - Poll async jobs until job has finished. type: bool - default: 'yes' + default: yes extends_documentation_fragment: cloudstack ''' EXAMPLES = ''' -# Create a affinity group -- local_action: - module: cs_affinitygroup +- name: Create a affinity group + cs_affinitygroup: name: haproxy affinity_type: host anti-affinity + delegate_to: localhost -# Remove a affinity group -- local_action: - module: cs_affinitygroup +- name: Remove a affinity group + cs_affinitygroup: name: haproxy state: absent + delegate_to: localhost ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/cloudstack/cs_cluster.py b/lib/ansible/modules/cloud/cloudstack/cs_cluster.py index 07e158dc98..441a8948e5 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_cluster.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_cluster.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,112 +15,131 @@ module: cs_cluster short_description: Manages host clusters on Apache CloudStack based clouds. description: - Create, update and remove clusters. -version_added: "2.1" -author: "René Moser (@resmo)" +version_added: '2.1' +author: René Moser (@resmo) options: name: description: - name of the cluster. + type: str required: true zone: description: - Name of the zone in which the cluster belongs to. - If not set, default zone is used. + type: str pod: description: - Name of the pod in which the cluster belongs to. + type: str cluster_type: description: - Type of the cluster. - - Required if C(state=present) - choices: [ 'CloudManaged', 'ExternalManaged' ] + - Required if I(state=present) + type: str + choices: [ CloudManaged, ExternalManaged ] hypervisor: description: - Name the hypervisor to be used. - - Required if C(state=present). - choices: [ 'KVM', 'VMware', 'BareMetal', 'XenServer', 'LXC', 'HyperV', 'UCS', 'OVM' ] + - Required if I(state=present). + type: str + choices: [ KVM, VMware, BareMetal, XenServer, LXC, HyperV, UCS, OVM ] url: description: - URL for the cluster + type: str username: description: - Username for the cluster. + type: str password: description: - Password for the cluster. + type: str guest_vswitch_name: description: - Name of virtual switch used for guest traffic in the cluster. - This would override zone wide traffic label setting. + type: str guest_vswitch_type: description: - Type of virtual switch used for guest traffic in the cluster. - Allowed values are, vmwaresvs (for VMware standard vSwitch) and vmwaredvs (for VMware distributed vSwitch) - choices: [ 'vmwaresvs', 'vmwaredvs' ] + type: str + choices: [ vmwaresvs, vmwaredvs ] public_vswitch_name: description: - Name of virtual switch used for public traffic in the cluster. - This would override zone wide traffic label setting. + type: str public_vswitch_type: description: - Type of virtual switch used for public traffic in the cluster. - Allowed values are, vmwaresvs (for VMware standard vSwitch) and vmwaredvs (for VMware distributed vSwitch) - choices: [ 'vmwaresvs', 'vmwaredvs' ] + type: str + choices: [ vmwaresvs, vmwaredvs ] vms_ip_address: description: - IP address of the VSM associated with this cluster. + type: str vms_username: description: - Username for the VSM associated with this cluster. + type: str vms_password: description: - Password for the VSM associated with this cluster. + type: str ovm3_cluster: description: - Ovm3 native OCFS2 clustering enabled for cluster. + type: str ovm3_pool: description: - Ovm3 native pooling enabled for cluster. + type: str ovm3_vip: description: - Ovm3 vip to use for pool (and cluster). + type: str state: description: - State of the cluster. - default: 'present' - choices: [ 'present', 'absent', 'disabled', 'enabled' ] + type: str + choices: [ present, absent, disabled, enabled ] + default: present extends_documentation_fragment: cloudstack ''' EXAMPLES = ''' -# Ensure a cluster is present -- local_action: - module: cs_cluster +- name: Ensure a cluster is present + cs_cluster: name: kvm-cluster-01 zone: ch-zrh-ix-01 hypervisor: KVM cluster_type: CloudManaged + delegate_to: localhost -# Ensure a cluster is disabled -- local_action: - module: cs_cluster +- name: Ensure a cluster is disabled + cs_cluster: name: kvm-cluster-01 zone: ch-zrh-ix-01 state: disabled + delegate_to: localhost -# Ensure a cluster is enabled -- local_action: - module: cs_cluster +- name: Ensure a cluster is enabled + cs_cluster: name: kvm-cluster-01 zone: ch-zrh-ix-01 state: enabled + delegate_to: localhost -# Ensure a cluster is absent -- local_action: - module: cs_cluster +- name: Ensure a cluster is absent + cs_cluster: name: kvm-cluster-01 zone: ch-zrh-ix-01 state: absent + delegate_to: localhost ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/cloudstack/cs_configuration.py b/lib/ansible/modules/cloud/cloudstack/cs_configuration.py index aad0ae1af5..b227bbd38a 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_configuration.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_configuration.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,65 +15,72 @@ module: cs_configuration short_description: Manages configuration on Apache CloudStack based clouds. description: - Manages global, zone, account, storage and cluster configurations. -version_added: "2.1" -author: "René Moser (@resmo)" +version_added: '2.1' +author: René Moser (@resmo) options: name: description: - Name of the configuration. + type: str required: true value: description: - Value of the configuration. + type: str required: true account: description: - Ensure the value for corresponding account. + type: str domain: description: - Domain the account is related to. - - Only considered if C(account) is used. + - Only considered if I(account) is used. + type: str default: ROOT zone: description: - Ensure the value for corresponding zone. + type: str storage: description: - Ensure the value for corresponding storage pool. + type: str cluster: description: - Ensure the value for corresponding cluster. + type: str extends_documentation_fragment: cloudstack ''' EXAMPLES = ''' -# Ensure global configuration -- local_action: - module: cs_configuration +- name: Ensure global configuration + cs_configuration: name: router.reboot.when.outofband.migrated value: false + delegate_to: localhost -# Ensure zone configuration -- local_action: - module: cs_configuration +- name: Ensure zone configuration + cs_configuration: name: router.reboot.when.outofband.migrated zone: ch-gva-01 value: true + delegate_to: localhost -# Ensure storage configuration -- local_action: - module: cs_configuration +- name: Ensure storage configuration + cs_configuration: name: storage.overprovisioning.factor storage: storage01 value: 2.0 + delegate_to: localhost -# Ensure account configuration -- local_action: - module: cs_configuration +- name: Ensure account configuration + cs_configuration: name: allow.public.user.templates value: false account: acme inc domain: customers + delegate_to: localhost ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/cloudstack/cs_disk_offering.py b/lib/ansible/modules/cloud/cloudstack/cs_disk_offering.py index 889866f309..da4bd1f6b5 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_disk_offering.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_disk_offering.py @@ -19,78 +19,85 @@ description: - Create and delete disk offerings for guest VMs. - Update display_text or display_offering of existing disk offering. short_description: Manages disk offerings on Apache CloudStack based clouds. -version_added: "2.7" +version_added: '2.7' author: - - "David Passante (@dpassante)" - - "René Moser (@resmo)" + - David Passante (@dpassante) + - René Moser (@resmo) options: disk_size: description: - Size of the disk offering in GB (1GB = 1,073,741,824 bytes). + type: int bytes_read_rate: description: - Bytes read rate of the disk offering. + type: int bytes_write_rate: description: - Bytes write rate of the disk offering. + type: int display_text: description: - Display text of the disk offering. - If not set, C(name) will be used as C(display_text) while creating. + type: str domain: description: - Domain the disk offering is related to. - Public for all domains and subdomains if not set. + type: str hypervisor_snapshot_reserve: description: - Hypervisor snapshot reserve space as a percent of a volume. - Only for managed storage using Xen or VMware. + type: int customized: description: - Whether disk offering iops is custom or not. type: bool - default: false + default: no iops_read_rate: description: - IO requests read rate of the disk offering. + type: int iops_write_rate: description: - IO requests write rate of the disk offering. + type: int iops_max: description: - Max. iops of the disk offering. + type: int iops_min: description: - Min. iops of the disk offering. + type: int name: description: - Name of the disk offering. + type: str required: true provisioning_type: description: - Provisioning type used to create volumes. - choices: - - thin - - sparse - - fat + type: str + choices: [ thin, sparse, fat ] state: description: - State of the disk offering. - choices: - - present - - absent + type: str + choices: [ present, absent ] default: present storage_type: description: - The storage type of the disk offering. - choices: - - local - - shared + type: str + choices: [ local, shared ] storage_tags: description: - The storage tags for this disk offering. - aliases: - - storage_tag + type: list + aliases: [ storage_tag ] display_offering: description: - An optional field, whether to display the offering to the end user or not. @@ -100,27 +107,27 @@ extends_documentation_fragment: cloudstack EXAMPLES = ''' - name: Create a disk offering with local storage - local_action: - module: cs_disk_offering + cs_disk_offering: name: small display_text: Small 10GB disk_size: 10 storage_type: local + delegate_to: localhost - name: Create or update a disk offering with shared storage - local_action: - module: cs_disk_offering + cs_disk_offering: name: small display_text: Small 10GB disk_size: 10 storage_type: shared storage_tags: SAN01 + delegate_to: localhost - name: Remove a disk offering - local_action: - module: cs_disk_offering + cs_disk_offering: name: small state: absent + delegate_to: localhost ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/cloudstack/cs_domain.py b/lib/ansible/modules/cloud/cloudstack/cs_domain.py index 783076b612..8eb50ccd93 100644 --- a/lib/ansible/modules/cloud/cloudstack/cs_domain.py +++ b/lib/ansible/modules/cloud/cloudstack/cs_domain.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,54 +16,56 @@ short_description: Manages domains on Apache CloudStack based clouds. description: - Create, update and remove domains. version_added: '2.0' -author: "René Moser (@resmo)" +author: René Moser (@resmo) options: path: description: - Path of the domain. - Prefix C(ROOT/) or C(/ROOT/) in path is optional. + type: str required: true network_domain: description: - Network domain for networks in the domain. + type: str clean_up: description: - Clean up all domain resources like child domains and accounts. - - Considered on C(state=absent). - default: false + - Considered on I(state=absent). type: bool + default: no state: description: - State of the domain. - required: false - default: 'present' - choices: [ 'present', 'absent' ] + type: str + choices: [ present, absent ] + default: present poll_async: description: - Poll async jobs until job has finished. - default: true type: bool + default: yes extends_documentation_fragment: cloudstack ''' EXAMPLES = ''' - name: Create a domain - local_action: - module: cs_domain + cs_domain: path: ROOT/customers network_domain: customers.example.com + delegate_to: localhost - name: Create another subdomain - local_action: - module: cs_domain + cs_domain: path: ROOT/customers/xy network_domain: xy.customers.example.com + delegate_to: localhost - name: Remove a domain - local_action: - module: cs_domain + cs_domain: path: ROOT/customers/xy state: absent + delegate_to: localhost ''' RETURN = '''