ACI: Asorted fixes to documentation (#36681)

docs/docsite/rst/scenario_guides/guide_aci.rst

@@ -16,12 +16,12 @@ The Cisco Application Centric Infrastructure (ACI) allows application requiremen
 
 Application Policy Infrastructure Controller (APIC)
 ...................................................
-The Cisco Application Policy Infrastructure Controller (APIC) API enables applications to directly connect with a secure, shared, high-performance resource pool that includes network, compute, and storage capabilities.
-
 The APIC manages the scalable ACI multi-tenant fabric. The APIC provides a unified point of automation and management, policy programming, application deployment, and health monitoring for the fabric. The APIC, which is implemented as a replicated synchronized clustered controller, optimizes performance, supports any application anywhere, and provides unified operation of the physical and virtual infrastructure.
 
 The APIC enables network administrators to easily define the optimal network for applications. Data center operators can clearly see how applications consume network resources, easily isolate and troubleshoot application and infrastructure problems, and monitor and profile resource usage patterns.
 
+The Cisco Application Policy Infrastructure Controller (APIC) API enables applications to directly connect with a secure, shared, high-performance resource pool that includes network, compute, and storage capabilities.
+
 
 ACI Fabric
 ..........
@@ -400,15 +400,16 @@ The below example waits until the cluster is fully-fit. In this example you know
 
 APIC error messages
 -------------------
-The following error messages may occur and this section can help you understand what exactly is going on.
+The following error messages may occur and this section can help you understand what exactly is going on and how to fix/avoid them.
 
     APIC Error 122: unknown managed object class 'polUni'
-        In case you receive this error while you are certain your :ref:`aci_rest <aci_rest>` payload and object classes are seemingly correct, the issue might be that your payload is not in fact correct JSON (e.g. the sent payload is using single quotes, rather than double quotes), and as a result the APIC is not correctly parsing your object classes from the payload. One way to avoid this is by using a YAML or an XML formatted payload.
+        In case you receive this error while you are certain your :ref:`aci_rest <aci_rest>` payload and object classes are seemingly correct, the issue might be that your payload is not in fact correct JSON (e.g. the sent payload is using single quotes, rather than double quotes), and as a result the APIC is not correctly parsing your object classes from the payload. One way to avoid this is by using a YAML or an XML formatted payload, which are easier to construct correctly and modify later.
 
 
     APIC Error 400: invalid data at line '1'. Attributes are missing, tag 'attributes' must be specified first, before any other tag
         Although the JSON specification allows unordered elements, the APIC REST API requires that the JSON ``attributes`` element precede the ``children`` array or other elements. So you need to ensure that your payload conforms to this requirement. Sorting your dictionary keys will do the trick just fine. If you don't have any attributes, it may be necessary to add: ``attributes: {}`` as the APIC does expect the entry to proceed any ``children``.
 
+
     APIC Error 801: property descr of uni/tn-TENANT/ap-AP failed validation for value 'A "legacy" network'
         Some values in the APIC have strict format-rules to comply to, and the internal APIC validation check for the provided value failed. In the above case, the ``description`` parameter (internally known as ``descr``) only accepts values conforming to `Regex: [a-zA-Z0-9\\!#$%()*,-./:;@ _{|}~?&+]+ <https://pubhub-prod.s3.amazonaws.com/media/apic-mim-ref/docs/MO-fvAp.html#descr>`_, in general it must not include quotes or square brackets.
 
@@ -417,9 +418,9 @@ The following error messages may occur and this section can help you understand
 
 Known issues
 ------------
-The :ref:`aci_rest <aci_rest>` module is a wrapper around the APIC REST API. As a result any issues related to the APIC will be reflected in the use of :ref:`the aci_rest module <aci_rest>`.
+The :ref:`aci_rest <aci_rest>` module is a wrapper around the APIC REST API. As a result any issues related to the APIC will be reflected in the use of this module.
 
-All below issues either have been reported to the vendor, or can simply be avoided.
+All below issues either have been reported to the vendor, and most can simply be avoided.
 
     Too many consecutive API calls may result in connection throttling
         Starting with ACI v3.1 the APIC will actively throttle password-based authenticated connection rates over a specific treshold. This is as part of an anti-DDOS measure but can act up when using Ansible with ACI using password-based authentication. Currently, one solution is to increase this treshold within the nginx configuration, but using signature-based authentication is recommended.
@@ -457,14 +458,14 @@ You will find our roadmap, an overview of open ACI issues and pull-requests and
 .. seealso::
 
    :ref:`network_guide`
-       Ansible for Network Automation
+       A detailed guide on how to use Ansible for automating network infrastructure.
    :ref:`List of ACI modules <aci_network_modules>`
-       A complete list of supported ACI modules
+       A complete list of supported ACI modules.
    `ACI community <https://github.com/ansible/community/wiki/Network:-ACI>`_
-       The Ansible ACI community wiki page, includes roadmap, ideas and development documentation
+       The Ansible ACI community wiki page, includes roadmap, ideas and development documentation.
    `Network Working Group <https://github.com/ansible/community/tree/master/group-network>`_
-       The Ansible Network community page, includes contact information and meeting information
+       The Ansible Network community page, includes contact information and meeting information.
    `#ansible-network <https://webchat.freenode.net/?channels=ansible-network>`_
-       The #ansible-network IRC chat channel on Freenode.net
+       The #ansible-network IRC chat channel on Freenode.net.
    `User Mailing List <http://groups.google.com/group/ansible-project>`_
        Have a question?  Stop by the google group!

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

@@ -16,7 +16,7 @@ DOCUMENTATION = r'''
 module: aci_aaa_user
 short_description: Manage AAA users (aaa:User)
 description:
-- Manage AAA users.
+- Manage AAA users on Cisco ACI fabrics.
 notes:
 - This module is not idempotent when C(aaa_password) is being used
   (even if that password was already set identically). This

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

@@ -16,7 +16,7 @@ DOCUMENTATION = r'''
 module: aci_aaa_user_certificate
 short_description: Manage AAA user certificates (aaa:UserCert)
 description:
-- Manage AAA user certificates.
+- Manage AAA user certificates on Cisco ACI fabrics.
 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.

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

@@ -15,7 +15,7 @@ DOCUMENTATION = r'''
 module: aci_bd
 short_description: Manage Bridge Domains (BD) objects (fv:BD)
 description:
-- Manages Bridge Domains (BD) on Cisco ACI Fabrics.
+- 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.

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

@@ -15,7 +15,7 @@ DOCUMENTATION = r'''
 module: aci_config_rollback
 short_description: Provides rollback and rollback preview functionality (config:ImportP)
 description:
-- Provides rollback and rollback preview functionality for Cisco ACI fabric.
+- Provides rollback and rollback preview functionality for Cisco ACI fabrics.
 - Config Rollbacks are done using snapshots C(aci_snapshot) with the configImportP class.
 notes:
 - More information from the internal APIC class I(config:ImportP) at

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

@@ -15,7 +15,7 @@ DOCUMENTATION = r'''
 module: aci_domain
 short_description: Manage physical, virtual, bridged, routed or FC domain profiles (phys:DomP, vmm:DomP, l2ext:DomP, l3ext:DomP, fc:DomP)
 description:
-- Manage physical, virtual, bridged, routed or FC domain profiles.
+- Manage physical, virtual, bridged, routed or FC domain profiles on Cisco ACI fabrics.
 notes:
 - More information from the internal APIC classes I(phys:DomP),
   I(vmm:DomP), I(l2ext:DomP), I(l3ext:DomP), I(fc:DomP) at

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

@@ -38,7 +38,7 @@ options:
     description:
     - Name of the end point group.
     required: yes
-    aliases: [ name, epg_name ]
+    aliases: [ epg_name, name ]
   bd:
     description:
     - Name of the bridge domain being associated with the EPG.
@@ -116,7 +116,7 @@ EXAMPLES = r'''
     host: apic
     username: admin
     password: SomeSecretPassword
-    validate_certs: false
+    validate_certs: no
     tenant: production
     app_profile: intranet
     epg: web_epg
@@ -144,7 +144,7 @@ EXAMPLES = r'''
     host: apic
     username: admin
     password: SomeSecretPassword
-    validate_certs: false
+    validate_certs: no
     epg: web_epg
     state: query
 
@@ -153,7 +153,7 @@ EXAMPLES = r'''
     host: apic
     username: admin
     password: SomeSecretPassword
-    validate_certs: false
+    validate_certs: no
     ap: ticketing
     state: query
 '''
@@ -270,7 +270,7 @@ from ansible.module_utils.basic import AnsibleModule
 def main():
     argument_spec = aci_argument_spec()
     argument_spec.update(
-        epg=dict(type='str', aliases=['name', 'epg_name']),  # Not required for querying all objects
+        epg=dict(type='str', aliases=['epg_name', 'name']),  # Not required for querying all objects
         bd=dict(type='str', aliases=['bd_name', 'bridge_domain']),
         ap=dict(type='str', aliases=['app_profile', 'app_profile_name']),  # Not required for querying all objects
         tenant=dict(type='str', aliases=['tenant_name']),  # Not required for querying all objects

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

@@ -41,7 +41,6 @@ options:
   transmit_state:
     description:
     - Enable or Disable Transmit state.
-    required: false
     choices: [ disabled, enabled ]
     default: enabled
   state:

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

@@ -26,7 +26,7 @@ options:
   port_channel:
     description:
     - Name of the port channel.
-    required: true
+    required: yes
     aliases: [ name ]
   description:
     description:
@@ -49,48 +49,48 @@ options:
     - Port channel interface policy mode.
     - Determines the LACP method to use for forming port-channels.
     - The APIC defaults new Port Channel Polices to C(off).
-    choices: [ active, mac-pin, mac-pin-nicload, off, passive ]
-    default: off
+    choices: [ active, mac-pin, mac-pin-nicload, 'off', passive ]
+    default: 'off'
   fast_select:
     description:
     - Determines if Fast Select is enabled for Hot Standby Ports.
     - This makes up the LACP Policy Control Policy; if one setting is defined, then all other Control Properties
       left undefined or set to false will not exist after the task is ran.
-    - The APIC defaults new LACP Policies to C(true).
+    - The APIC defaults new LACP Policies to C(yes).
     type: bool
-    default: true
+    default: 'yes'
   graceful_convergence:
     description:
     - Determines if Graceful Convergence is enabled.
     - This makes up the LACP Policy Control Policy; if one setting is defined, then all other Control Properties
       left undefined or set to false will not exist after the task is ran.
-    - The APIC defaults new LACP Policies to C(true).
+    - The APIC defaults new LACP Policies to C(yes).
     type: bool
-    default: true
+    default: 'yes'
   load_defer:
     description:
     - Determines if Load Defer is enabled.
     - This makes up the LACP Policy Control Policy; if one setting is defined, then all other Control Properties
       left undefined or set to false will not exist after the task is ran.
-    - The APIC defaults new LACP Policies to C(false).
+    - The APIC defaults new LACP Policies to C(no).
     type: bool
-    default: false
+    default: 'no'
   suspend_individual:
     description:
     - Determines if Suspend Individual is enabled.
     - This makes up the LACP Policy Control Policy; if one setting is defined, then all other Control Properties
       left undefined or set to false will not exist after the task is ran.
-    - The APIC defaults new LACP Policies to C(true).
+    - The APIC defaults new LACP Policies to C(yes).
     type: bool
-    default: true
+    default: 'yes'
   symmetric_hash:
     description:
     - Determines if Symmetric Hashing is enabled.
     - This makes up the LACP Policy Control Policy; if one setting is defined, then all other Control Properties
       left undefined or set to false will not exist after the task is ran.
-    - The APIC defaults new LACP Policies to C(false).
+    - The APIC defaults new LACP Policies to C(no).
     type: bool
-    default: false
+    default: 'no'
   state:
     description:
     - Use C(present) or C(absent) for adding or removing.