ACI: Various changes to module documentation and guide

lib/ansible/modules/network/aci/aci_aaa_user.py

@@ -17,15 +17,16 @@
 short_description: Manage AAA users (aaa:User)
 description:
 - Manage AAA users.
-- More information from the internal APIC class I(aaa:User) at
-  U(https://developer.cisco.com/docs/apic-mim-ref/).
-author:
-- Dag Wieers (@dagwieers)
 notes:
 - This module is not idempotent when C(aaa_password) is being used
   (even if that password was already set identically). This
   appears to be an inconsistency wrt. the idempotent nature
-  of the APIC REST API.
+  of the APIC REST API. The vendor has been informed.
+  More information in :ref:`the ACI documentation <aci_guide_known_issues>`.
+- More information from the internal APIC class I(aaa:User) at
+  U(https://developer.cisco.com/docs/apic-mim-ref/).
+author:
+- Dag Wieers (@dagwieers)
 requirements:
   - python-dateutil
 version_added: '2.5'
@@ -246,7 +247,7 @@ def main():
         aaa_password=dict(type='str', no_log=True),
         aaa_password_lifetime=dict(type='int'),
         aaa_password_update_required=dict(type='bool'),
-        aaa_user=dict(type='str', required=True, aliases=['name']),
+        aaa_user=dict(type='str', required=True, aliases=['name']),  # Not required for querying all objects
         clear_password_history=dict(type='bool'),
         description=dict(type='str', aliases=['descr']),
         email=dict(type='str'),
@@ -306,7 +307,6 @@ def main():
     aci.get_existing()
 
     if state == 'present':
-        # Filter out module params with null values
         aci.payload(
             aci_class='aaaUser',
             class_config=dict(
@@ -325,10 +325,8 @@ def main():
             ),
         )
 
-        # Generate config diff which will be used as POST request body
         aci.get_diff(aci_class='aaaUser')
 
-        # Submit changes if module not in check_mode and the proposed is different than existing
         aci.post_config()
 
     elif state == 'absent':

lib/ansible/modules/network/aci/aci_aaa_user_certificate.py

@@ -16,15 +16,15 @@
 module: aci_aaa_user_certificate
 short_description: Manage AAA user certificates (aaa:UserCert)
 description:
-- Manage AAA user and appuser certificates.
+- Manage AAA user certificates.
+notes:
+- The C(aaa_user) must exist before using this module in your playbook.
+  The M(aci_aaa_user) module can be used for this.
 - More information from the internal APIC class I(aaa:UserCert) at
   U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
 version_added: '2.5'
-notes:
-- The C(aaa_user) must exist before using this module in your playbook.
-  The M(aci_aaa_user) module can be used for this.
 options:
   aaa_user:
     description:
@@ -212,10 +212,10 @@
 def main():
     argument_spec = aci_argument_spec()
     argument_spec.update(
-        aaa_user=dict(type='str', required=True),
+        aaa_user=dict(type='str', required=True),  # Not required for querying all objects
         aaa_user_type=dict(type='str', default='user', choices=['appuser', 'user']),
-        certificate=dict(type='str', aliases=['cert_data', 'certificate_data']),
-        certificate_name=dict(type='str', aliases=['cert_name']),
+        certificate=dict(type='str', aliases=['cert_data', 'certificate_data']),  # Not required for querying all objects
+        certificate_name=dict(type='str', aliases=['cert_name']),  # Not required for querying all objects
         state=dict(type='str', default='present', choices=['absent', 'present', 'query']),
     )
 
@@ -252,7 +252,6 @@ def main():
     aci.get_existing()
 
     if state == 'present':
-        # Filter out module params with null values
         aci.payload(
             aci_class='aaaUserCert',
             class_config=dict(
@@ -261,10 +260,8 @@ def main():
             ),
         )
 
-        # Generate config diff which will be used as POST request body
         aci.get_diff(aci_class='aaaUserCert')
 
-        # Submit changes if module not in check_mode and the proposed is different than existing
         aci.post_config()
 
     elif state == 'absent':

lib/ansible/modules/network/aci/aci_access_port_to_interface_policy_leaf_profile.py

@@ -17,6 +17,7 @@
 short_description: Manage Fabric interface policy leaf profile interface selectors on Cisco ACI fabrics (infra:HPortS, infra:RsAccBaseGrp, infra:PortBlk)
 description:
 - Manage Fabric interface policy leaf profile interface selectors on Cisco ACI fabrics.
+notes:
 - More information from the internal APIC class I(infra:HPortS, infra:RsAccBaseGrp, infra:PortBlk) at
   U(https://developer.cisco.com/media/mim-ref).
 author:
@@ -36,7 +37,6 @@
   description:
     description:
     - The description to assign to the C(access_port_selector)
-    required: no
   leaf_port_blk:
     description:
     - The name of the Fabric access policy leaf interface profile access port block.
@@ -59,7 +59,6 @@
   policy_group:
     description:
     - The name of the fabric access policy group to be associated with the leaf interface profile interface selector.
-    required: no
     aliases: [ policy_group_name ]
   state:
     description:
@@ -227,8 +226,8 @@
 def main():
     argument_spec = aci_argument_spec()
     argument_spec.update({
-        'leaf_interface_profile': dict(type='str', aliases=['leaf_interface_profile_name']),
-        'access_port_selector': dict(type='str', aliases=['name', 'access_port_selector_name']),
+        'leaf_interface_profile': dict(type='str', aliases=['leaf_interface_profile_name']),  # Not required for querying all objects
+        'access_port_selector': dict(type='str', aliases=['name', 'access_port_selector_name']),  # Not required for querying all objects
         'description': dict(typ='str'),
         'leaf_port_blk': dict(type='str', aliases=['leaf_port_blk_name']),
         'leaf_port_blk_description': dict(type='str'),
@@ -277,7 +276,6 @@ def main():
     aci.get_existing()
 
     if state == 'present':
-        # Filter out module parameters with null values
         aci.payload(
             aci_class='infraHPortS',
             class_config=dict(
@@ -292,23 +290,21 @@ def main():
                             name=leaf_port_blk,
                             fromPort=from_,
                             toPort=to_,
-                        )
-                    )
+                        ),
+                    ),
                 ),
                 dict(
                     infraRsAccBaseGrp=dict(
                         attributes=dict(
                             tDn='uni/infra/funcprof/accportgrp-{0}'.format(policy_group),
-                        )
-                    )
+                        ),
+                    ),
                 ),
             ],
         )
 
-        # Generate config diff which will be used as POST request body
         aci.get_diff(aci_class='infraHPortS')
 
-        # Submit changes if module not in check_mode and the proposed is different than existing
         aci.post_config()
 
     elif state == 'absent':

lib/ansible/modules/network/aci/aci_aep.py

@@ -17,13 +17,12 @@
 description:
 - Connect to external virtual and physical domains by using
   attachable Access Entity Profiles (AEP) on Cisco ACI fabrics.
+notes:
 - More information from the internal APIC classes I(infra:AttEntityP) and I(infra:ProvAcc) at
   U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Swetha Chunduri (@schunduri)
 version_added: '2.4'
-requirements:
-- ACI Fabric 1.0(3f)+
 options:
   aep:
     description:
@@ -198,7 +197,7 @@
 def main():
     argument_spec = aci_argument_spec()
     argument_spec.update(
-        aep=dict(type='str', aliases=['name', 'aep_name']),  # not required for querying all AEPs
+        aep=dict(type='str', aliases=['name', 'aep_name']),  # Not required for querying all objects
         description=dict(type='str', aliases=['descr']),
         infra_vlan=dict(type='bool', aliases=['infrastructure_vlan']),
         state=dict(type='str', default='present', choices=['absent', 'present', 'query']),
@@ -237,7 +236,6 @@ def main():
     aci.get_existing()
 
     if state == 'present':
-        # Filter out module parameters with null values
         aci.payload(
             aci_class='infraAttEntityP',
             class_config=dict(
@@ -247,10 +245,8 @@ def main():
             child_configs=child_configs,
         )
 
-        # Generate config diff which will be used as POST request body
         aci.get_diff(aci_class='infraAttEntityP')
 
-        # Submit changes if module not in check_mode and the proposed is different than existing
         aci.post_config()
 
     elif state == 'absent':

lib/ansible/modules/network/aci/aci_aep_to_domain.py

@@ -17,14 +17,14 @@
 short_description: Bind AEPs to Physical or Virtual Domains on Cisco ACI fabrics (infra:RsDomP)
 description:
 - Bind AEPs to Physical or Virtual Domains on Cisco ACI fabrics.
+notes:
+- The C(aep) and C(domain) parameters should exist before using this module.
+  The M(aci_aep) and M(aci_domain) can be used for these.
 - More information from the internal APIC class I(infra:RsDomP) at
   U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
 version_added: '2.5'
-notes:
-- The C(aep) and C(domain) parameters should exist before using this module.
-  The M(aci_aep) and M(aci_domain) can be used for these.
 options:
   aep:
     description:
@@ -215,9 +215,9 @@
 def main():
     argument_spec = aci_argument_spec()
     argument_spec.update(
-        aep=dict(type='str', aliases=['aep_name']),
-        domain=dict(type='str', aliases=['domain_name', 'domain_profile']),
-        domain_type=dict(type='str', choices=['fc', 'l2dom', 'l3dom', 'phys', 'vmm'], aliases=['type']),
+        aep=dict(type='str', aliases=['aep_name']),  # Not required for querying all objects
+        domain=dict(type='str', aliases=['domain_name', 'domain_profile']),  # Not required for querying all objects
+        domain_type=dict(type='str', choices=['fc', 'l2dom', 'l3dom', 'phys', 'vmm'], aliases=['type']),  # Not required for querying all objects
         state=dict(type='str', default='present', choices=['absent', 'present', 'query']),
         vm_provider=dict(type='str', choices=['cloudfoundry', 'kubernetes', 'microsoft', 'openshift', 'openstack', 'redhat', 'vmware']),
     )
@@ -278,16 +278,13 @@ def main():
     aci.get_existing()
 
     if state == 'present':
-        # Filter out module params with null values
         aci.payload(
             aci_class='infraRsDomP',
             class_config=dict(tDn=domain_mo),
         )
 
-        # Generate config diff which will be used as POST request body
         aci.get_diff(aci_class='infraRsDomP')
 
-        # Submit changes if module not in check_mode and the proposed is different than existing
         aci.post_config()
 
     elif state == 'absent':

lib/ansible/modules/network/aci/aci_ap.py

@@ -16,15 +16,15 @@
 short_description: Manage top level Application Profile (AP) objects on Cisco ACI fabrics (fv:Ap)
 description:
 - Manage top level Application Profile (AP) objects on Cisco ACI fabrics
+notes:
+- This module does not manage EPGs, see M(aci_epg) to do this.
+- The C(tenant) used must exist before using this module in your playbook.
+  The M(aci_tenant) module can be used for this.
 - More information from the internal APIC class I(fv:Ap) at
   U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Swetha Chunduri (@schunduri)
 version_added: '2.4'
-notes:
-- This module does not manage EPGs, see M(aci_epg) to do this.
-- The C(tenant) used must exist before using this module in your playbook.
-  The M(aci_tenant) module can be used for this.
 options:
    tenant:
      description:
@@ -198,8 +198,8 @@
 def main():
     argument_spec = aci_argument_spec()
     argument_spec.update(
-        tenant=dict(type='str', aliases=['tenant_name']),  # tenant not required for querying all APs
-        ap=dict(type='str', aliases=['app_profile', 'app_profile_name', 'name']),
+        tenant=dict(type='str', aliases=['tenant_name']),  # Not required for querying all objects
+        ap=dict(type='str', aliases=['app_profile', 'app_profile_name', 'name']),  # Not required for querying all objects
         description=dict(type='str', aliases=['descr'], required=False),
         state=dict(type='str', default='present', choices=['absent', 'present', 'query']),
         method=dict(type='str', choices=['delete', 'get', 'post'], aliases=['action'], removed_in_version='2.6'),  # Deprecated starting from v2.6
@@ -215,7 +215,6 @@ def main():
         ],
     )
 
-    # tenant = module.params['tenant']
     ap = module.params['ap']
     description = module.params['description']
     state = module.params['state']
@@ -240,7 +239,6 @@ def main():
     aci.get_existing()
 
     if state == 'present':
-        # Filter out module parameters with null values
         aci.payload(
             aci_class='fvAp',
             class_config=dict(
@@ -249,10 +247,8 @@ def main():
             ),
         )
 
-        # Generate config diff which will be used as POST request body
         aci.get_diff(aci_class='fvAp')
 
-        # Submit changes if module not in check_mode and the proposed is different than existing
         aci.post_config()
 
     elif state == 'absent':

lib/ansible/modules/network/aci/aci_bd.py

@@ -16,14 +16,14 @@
 short_description: Manage Bridge Domains (BD) on Cisco ACI Fabrics (fv:BD)
 description:
 - Manages Bridge Domains (BD) on Cisco ACI Fabrics.
+notes:
+- The C(tenant) used must exist before using this module in your playbook.
+  The M(aci_tenant) module can be used for this.
 - More information from the internal APIC class I(fv:BD) at
   U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
 version_added: '2.4'
-notes:
-- The C(tenant) used must exist before using this module in your playbook.
-  The M(aci_tenant) module can be used for this.
 options:
   arp_flooding:
     description:
@@ -319,7 +319,7 @@ def main():
     argument_spec = aci_argument_spec()
     argument_spec.update(
         arp_flooding=dict(type='bool'),
-        bd=dict(type='str', aliases=['bd_name', 'name']),
+        bd=dict(type='str', aliases=['bd_name', 'name']),  # Not required for querying all objects
         bd_type=dict(type='str', choices=['ethernet', 'fc']),
         description=dict(type='str'),
         enable_multicast=dict(type='bool'),
@@ -337,7 +337,7 @@ def main():
         mac_address=dict(type='str', aliases=['mac']),
         multi_dest=dict(choices=['bd-flood', 'drop', 'encap-flood']),
         state=dict(choices=['absent', 'present', 'query'], type='str', default='present'),
-        tenant=dict(type='str', aliases=['tenant_name']),
+        tenant=dict(type='str', aliases=['tenant_name']),  # Not required for querying all objects
         vrf=dict(type='str', aliases=['vrf_name']),
         gateway_ip=dict(type='str', removed_in_version='2.4'),  # Deprecated starting from v2.4
         scope=dict(type='str', removed_in_version='2.4'),  # Deprecated starting from v2.4
@@ -409,7 +409,6 @@ def main():
     aci.get_existing()
 
     if state == 'present':
-        # Filter out module params with null values
         aci.payload(
             aci_class='fvBD',
             class_config=dict(
@@ -436,10 +435,8 @@ def main():
             ],
         )
 
-        # generate config diff which will be used as POST request body
         aci.get_diff(aci_class='fvBD')
 
-        # submit changes if module not in check_mode and the proposed is different than existing
         aci.post_config()
 
     elif state == 'absent':