cloudstack: streamline modules doc (#52509)

* cloudstack: streamline modules doc (first 5) * Remove the "local_action" style from the examples
7 years ago · 5abeb9659b
parent 924f5b5467
commit 5abeb9659b
6 changed files with 173 additions and 187 deletions
--- 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 <mail@renemoser.net>
-#
-# 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 <http://www.gnu.org/licenses/>.
+# 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 = '''
--- 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 <mail@renemoser.net>
-#
-# 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 <http://www.gnu.org/licenses/>.
+# 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 = '''
--- 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 <mail@renemoser.net>
-#
-# 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 <http://www.gnu.org/licenses/>.
+# 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 = '''
--- 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 <mail@renemoser.net>
-#
-# 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 <http://www.gnu.org/licenses/>.
+# 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 = '''
--- 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 = '''
--- 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 <mail@renemoser.net>
-#
-# 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 <http://www.gnu.org/licenses/>.
+# 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 = '''